Class EmbeddedChartBuilder

أداة إنشاءالرسومات البيانيةالمضمّنة

أداة إنشاء تُستخدَم لتعديل EmbeddedChart لا يتم حفظ التغييرات التي تم إجراؤها على الرسم البياني إلا بعد استدعاء Sheet.updateChart(chart) على الرسم البياني الذي تمت إعادة إنشائه. 

const sheet = SpreadsheetApp.getActiveSheet(); const range = sheet.getRange('A1:B8'); let chart = sheet.getCharts()[0]; chart = chart.modify()             .addRange(range)             .setOption('title', 'Updated!')             .setOption('animation.duration', 500)             .setPosition(2, 2, 0, 0)             .build(); sheet.updateChart(chart);

الطُرق

الطريقةنوع القيمة التي يتم إرجاعهاوصف قصير
addRange(range)EmbeddedChartBuilderتضيف هذه الأداة نطاقًا إلى الرسم البياني الذي تعدّله.
asAreaChart()EmbeddedAreaChartBuilderتضبط هذه الدالة نوع الرسم البياني على AreaChart وتعرض EmbeddedAreaChartBuilder.
asBarChart()EmbeddedBarChartBuilderيضبط نوع الرسم البياني على BarChart ويعرض EmbeddedBarChartBuilder.
asColumnChart()EmbeddedColumnChartBuilderتضبط هذه الطريقة نوع الرسم البياني على ColumnChart وتعرض EmbeddedColumnChartBuilder.
asComboChart()EmbeddedComboChartBuilderتضبط هذه الدالة نوع الرسم البياني على ComboChart وتعرض EmbeddedComboChartBuilder.
asHistogramChart()EmbeddedHistogramChartBuilderتضبط هذه السمة نوع الرسم البياني على HistogramChart وتعرض EmbeddedHistogramChartBuilder.
asLineChart()EmbeddedLineChartBuilderتضبط هذه السمة نوع الرسم البياني على LineChart وتعرض EmbeddedLineChartBuilder.
asPieChart()EmbeddedPieChartBuilderتضبط هذه الطريقة نوع الرسم البياني على PieChart وتعرض EmbeddedPieChartBuilder.
asScatterChart()EmbeddedScatterChartBuilderتضبط هذه السمة نوع الرسم البياني على ScatterChart وتعرض EmbeddedScatterChartBuilder.
asTableChart()EmbeddedTableChartBuilderتضبط هذه الطريقة نوع الرسم البياني على TableChart وتعرض EmbeddedTableChartBuilder.
build()EmbeddedChartيتم إنشاء الرسم البياني ليعكس جميع التغييرات التي تم إجراؤها عليه.
clearRanges()EmbeddedChartBuilderيزيل هذا الإجراء جميع النطاقات من الرسم البياني الذي يعدّله هذا المنشئ.
getChartType()ChartTypeتعرِض هذه السمة نوع الرسم البياني الحالي.
getContainer()ContainerInfoتعرض هذه السمة الرسم البياني ContainerInfo، الذي يحدّد مكان ظهور الرسم البياني على ورقة البيانات.
getRanges()Range[]تعرض هذه الدالة نسخة من قائمة النطاقات التي توفّر حاليًا بيانات لهذا الرسم البياني.
removeRange(range)EmbeddedChartBuilderيزيل النطاق المحدّد من الرسم البياني الذي يعدّله هذا المنشئ.
setChartType(type)EmbeddedChartBuilderتغيير نوع الرسم البياني
setHiddenDimensionStrategy(strategy)EmbeddedChartBuilderتضبط هذه السمة الاستراتيجية التي سيتم استخدامها للصفوف والأعمدة المخفية.
setMergeStrategy(mergeStrategy)EmbeddedChartBuilderتضبط هذه السمة استراتيجية الدمج التي سيتم استخدامها عند توفّر أكثر من نطاق واحد.
setNumHeaders(headers)EmbeddedChartBuilderتضبط هذه السمة عدد صفوف أو أعمدة النطاق التي يجب التعامل معها كعناوين.
setOption(option, value)EmbeddedChartBuilderتضبط هذه السمة الخيارات المتقدّمة لهذا الرسم البياني.
setPosition(anchorRowPos, anchorColPos, offsetX, offsetY)EmbeddedChartBuilderتضبط هذه السمة الموضع، ما يؤدي إلى تغيير مكان ظهور الرسم البياني في ورقة البيانات.
setTransposeRowsAndColumns(transpose)EmbeddedChartBuilderتضبط هذه السمة ما إذا كان سيتم نقل صفوف المخطط وأعمدته.

مستندات مفصّلة

addRange(range)

تضيف هذه الأداة نطاقًا إلى الرسم البياني الذي تعدّله. لا تتم إضافة النطاق إذا سبق أن تمت إضافته إلى الرسم البياني. 

const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0];  const chart = sheet.newChart()                   .setChartType(Charts.ChartType.BAR)                   .addRange(sheet.getRange('A1:B8'))                   .setPosition(5, 5, 0, 0)                   .build();  sheet.insertChart(chart);

المعلمات

الاسمالنوعالوصف
rangeRangeالنطاق المطلوب إضافته

الإرجاع

‫EmbeddedChartBuilder: أداة إنشاء السلاسل

asAreaChart()

تضبط هذه الدالة نوع الرسم البياني على AreaChart وتعرض EmbeddedAreaChartBuilder.

الإرجاع

EmbeddedAreaChartBuilder: أداة إنشاء رسم بياني مساحي

asBarChart()

يضبط نوع الرسم البياني على BarChart ويعرض EmbeddedBarChartBuilder.

الإرجاع

EmbeddedBarChartBuilder: أداة إنشاء مخطط شريطي

asColumnChart()

تضبط هذه الطريقة نوع الرسم البياني على ColumnChart وتعرض EmbeddedColumnChartBuilder.

الإرجاع

‫EmbeddedColumnChartBuilder: أداة إنشاء رسم بياني عمودي.

asComboChart()

تضبط هذه الدالة نوع الرسم البياني على ComboChart وتعرض EmbeddedComboChartBuilder.

الإرجاع

‫EmbeddedComboChartBuilder: أداة إنشاء رسم بياني مجمّع.

asHistogramChart()

تضبط هذه السمة نوع الرسم البياني على HistogramChart وتعرض EmbeddedHistogramChartBuilder.

الإرجاع

EmbeddedHistogramChartBuilder: أداة إنشاء لمخطّط مدرّج تكراري.

asLineChart()

تضبط هذه السمة نوع الرسم البياني على LineChart وتعرض EmbeddedLineChartBuilder.

الإرجاع

EmbeddedLineChartBuilder: أداة إنشاء رسم بياني خطي

asPieChart()

تضبط هذه الطريقة نوع الرسم البياني على PieChart وتعرض EmbeddedPieChartBuilder.

الإرجاع

‫EmbeddedPieChartBuilder: أداة إنشاء مخطط دائري.

asScatterChart()

تضبط هذه السمة نوع الرسم البياني على ScatterChart وتعرض EmbeddedScatterChartBuilder.

الإرجاع

EmbeddedScatterChartBuilder: أداة إنشاء مخطط مبعثر.

asTableChart()

تضبط هذه الطريقة نوع الرسم البياني على TableChart وتعرض EmbeddedTableChartBuilder.

الإرجاع

‫EmbeddedTableChartBuilder: أداة إنشاء لرسم بياني جدولي

build()

يتم إنشاء الرسم البياني ليعكس جميع التغييرات التي تم إجراؤها عليه.

لا ترسم هذه الطريقة الرسم البياني تلقائيًا فوق جدول البيانات. يجب إدراج رسم بياني جديد من خلال sheet.insertChart(chart)، وتعديل رسم بياني حالي من خلال sheet.updateChart(chart). 

const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0];  const range = sheet.getRange('A1:B5'); const chart = sheet.newChart()                   .setChartType(Charts.ChartType.BAR)                   .addRange(range)                   .setPosition(5, 5, 0, 0)                   .build();  sheet.insertChart(chart);

الإرجاع

EmbeddedChart: المخطّط الذي تم إنشاؤه، والذي يجب إضافته إلى جدول البيانات.

clearRanges()

يزيل هذا الإجراء جميع النطاقات من الرسم البياني الذي يعدّله هذا المنشئ. 

const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0];  // This code updates the chart to use only the new ranges while preserving the // existing formatting of the chart. const chart = sheet.getCharts()[0]; const newChart = chart.modify()                      .clearRanges()                      .addRange(sheet.getRange('A1:A5'))                      .addRange(sheet.getRange('B1:B5'))                      .build(); sheet.updateChart(newChart);

الإرجاع

‫EmbeddedChartBuilder: أداة إنشاء السلاسل

getChartType()

تعرِض هذه السمة نوع الرسم البياني الحالي.

الإرجاع

ChartType: نوع الرسم البياني

getContainer()

تعرض هذه السمة الرسم البياني ContainerInfo، الذي يحدّد مكان ظهور الرسم البياني على ورقة البيانات. 

const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0];  const chartBuilder = sheet.newChart()                          .setChartType(Charts.ChartType.BAR)                          .addRange(sheet.getRange('A1:B8'))                          .setPosition(5, 5, 0, 0);  // This method returns the exact same data as Chart#getContainerInfo() const containerInfo = chartBuilder.getContainer();  // Logs the values used in setPosition() Logger.log(     'Anchor Column: %s\r\nAnchor Row %s\r\nOffset X %s\r\nOffset Y %s',     containerInfo.getAnchorColumn(),     containerInfo.getAnchorRow(),     containerInfo.getOffsetX(),     containerInfo.getOffsetY(), );

الإرجاع

‫ContainerInfo: عنصر يحتوي على موضع حاوية الرسم البياني.

getRanges()

تعرض هذه الدالة نسخة من قائمة النطاقات التي توفّر حاليًا بيانات لهذا الرسم البياني. استخدِم addRange(range) وremoveRange(range) لتعديل هذه القائمة. 

const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0];  const chartBuilder = sheet.newChart()                          .setChartType(Charts.ChartType.BAR)                          .addRange(sheet.getRange('A1:B8'))                          .setPosition(5, 5, 0, 0);  const ranges = chartBuilder.getRanges();  // There's only one range as a data source for this chart, // so this logs "A1:B8" for (const i in ranges) {   const range = ranges[i];   Logger.log(range.getA1Notation()); }

الإرجاع

Range[]: صفيف من النطاقات التي تعمل كمصدر بيانات للرسم البياني المطلوب إنشاؤه.

removeRange(range)

يزيل النطاق المحدّد من الرسم البياني الذي يعدّله هذا المنشئ. لا يعرض خطأ إذا كان النطاق غير متوفّر في هذا الرسم البياني.

يجب أن يتطابق النطاق الذي تمت إزالته مع نطاق تمت إضافته من خلال addRange(range)، وإلا لن يتم إجراء أي تغيير على الرسم البياني. لا يمكن استخدام هذه الطريقة لإزالة القيم جزئيًا من نطاق. 

const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0];  const firstRange = sheet.getRange('A1:B5'); const secondRange = sheet.getRange('A6:B8');  const chartBuilder = sheet.newChart()                          .setChartType(Charts.ChartType.BAR)                          .addRange(firstRange)                          // This range renders in a different color                          .addRange(secondRange)                          .setPosition(5, 5, 0, 0);  // Note that you can use either of these two formats, but the range // MUST match up with a range that was added via addRange(), or it // is not removed, and does not throw an exception chartBuilder.removeRange(firstRange); chartBuilder.removeRange(sheet.getRange('A6:B8'));  const chart = chartBuilder.build();  sheet.insertChart(chart);

المعلمات

الاسمالنوعالوصف
rangeRangeالنطاق المطلوب إزالته.

الإرجاع

‫EmbeddedChartBuilder: أداة إنشاء السلاسل

setChartType(type)

تغيير نوع الرسم البياني لا تتوافق بعض أنواع الرسوم البيانية المضمّنة حاليًا. يمكنك الاطّلاع على ChartType. 

const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0];  const range = sheet.getRange('A1:B5'); const chart = sheet.newChart()                   .setChartType(Charts.ChartType.BAR)                   .addRange(range)                   .setPosition(5, 5, 0, 0)                   .build();  sheet.insertChart(chart);

المعلمات

الاسمالنوعالوصف
typeChartTypeنوع الرسم البياني الذي تريد تغييره إليه

الإرجاع

‫EmbeddedChartBuilder: أداة إنشاء السلاسل

setHiddenDimensionStrategy(strategy)

تضبط هذه السمة الاستراتيجية التي سيتم استخدامها للصفوف والأعمدة المخفية. القيمة التلقائية هي IGNORE_ROWS. 

const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0];  const range = sheet.getRange('A1:B5'); const chart = sheet.newChart()                   .setChartType(Charts.ChartType.BAR)                   .addRange(range)                   .setHiddenDimensionStrategy(                       Charts.ChartHiddenDimensionStrategy.IGNORE_COLUMNS,                       )                   .setPosition(5, 5, 0, 0)                   .build();  sheet.insertChart(chart);

المعلمات

الاسمالنوعالوصف
strategyChartHiddenDimensionStrategyالاستراتيجية التي سيتم استخدامها للصفوف والأعمدة المخفية

الإرجاع

‫EmbeddedChartBuilder: أداة إنشاء السلاسل

setMergeStrategy(mergeStrategy)

تضبط هذه السمة استراتيجية الدمج التي سيتم استخدامها عند توفّر أكثر من نطاق واحد. إذا كانت القيمة MERGE_ROWS، يتم دمج الصفوف، وإذا كانت القيمة MERGE_COLUMNS، يتم دمج الأعمدة. القيمة التلقائية هي MERGE_COLUMNS. 

const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0];  const range = sheet.getRange('A1:B10'); const range2 = sheet.getRange('C:C10'); const chart = sheet.newChart()                   .setChartType(Charts.ChartType.BAR)                   .addRange(range)                   .addRange(range2)                   .setMergeStrategy(Charts.ChartMergeStrategy.MERGE_ROWS)                   .setPosition(5, 5, 0, 0)                   .build();  sheet.insertChart(chart);

المعلمات

الاسمالنوعالوصف
mergeStrategyChartMergeStrategyاستراتيجية الدمج التي سيتم استخدامها

الإرجاع

‫EmbeddedChartBuilder: أداة إنشاء السلاسل

setNumHeaders(headers)

تضبط هذه السمة عدد صفوف أو أعمدة النطاق التي يجب التعامل معها كعناوين. 

const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0];  const range = sheet.getRange('A1:B5'); const chart = sheet.newChart()                   .setChartType(Charts.ChartType.BAR)                   .addRange(range)                   .setNumHeaders(1)                   .setPosition(5, 5, 0, 0)                   .build();  sheet.insertChart(chart);

المعلمات

الاسمالنوعالوصف
headersIntegerعدد الصفوف أو الأعمدة التي يجب التعامل معها كعناوين تتسبّب القيم السلبية في رصد العناوين تلقائيًا.

الإرجاع

‫EmbeddedChartBuilder: أداة إنشاء السلاسل

setOption(option, value)

تضبط هذه السمة الخيارات المتقدّمة لهذا الرسم البياني. للاطّلاع على قائمة بالخيارات المتاحة، يُرجى الانتقال إلى خيارات إعداد الرسوم البيانية.

لا تتحقّق هذه الطريقة مما إذا كان الخيار الذي تحدّده صالحًا لنوع الرسم البياني هذا أو ما إذا كانت القيمة بالتنسيق/البنية الصحيحة.

يوضّح هذا المثال كيفية تغيير العنوان وإعداد وسيلة إيضاح. 

const spreadsheet = SpreadsheetApp.getActiveSpreadsheet(); const sheet = spreadsheet.getSheets()[0]; const chart = sheet.newChart()  .setOption('title', 'Earnings projections')  .setOption('legend', {    position: 'top',    textStyle: { color: 'blue', fontSize: 16 },  }).build();

المعلمات

الاسمالنوعالوصف
optionStringاسم الخيار
valueObjectتمثّل هذه السمة قيمة الخيار.

الإرجاع

‫EmbeddedChartBuilder: أداة إنشاء السلاسل

setPosition(anchorRowPos, anchorColPos, offsetX, offsetY)

تضبط هذه السمة الموضع، ما يؤدي إلى تغيير مكان ظهور الرسم البياني في ورقة البيانات. anchorRowPos وanchorColPos هما فهرسان يبدآن بالرقم 1. 

const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0];  const range = sheet.getRange('A1:B5'); const chart = sheet.newChart()                   .setChartType(Charts.ChartType.BAR)                   .addRange(range)                   .setPosition(5, 5, 0, 0)                   .build();  sheet.insertChart(chart);

المعلمات

الاسمالنوعالوصف
anchorRowPosIntegerيتم تثبيت الجانب العلوي من الرسم البياني في هذا الصف.
anchorColPosIntegerيتم تثبيت الجانب الأيمن من الرسم البياني في هذا العمود.
offsetXIntegerيتم إزاحة الزاوية العلوية اليسرى من الرسم البياني بهذا العدد من وحدات البكسل.
offsetYIntegerيتم إزاحة الزاوية اليمنى السفلية من الرسم البياني بمقدار عدد وحدات البكسل هذا.

الإرجاع

‫EmbeddedChartBuilder: أداة إنشاء السلاسل

setTransposeRowsAndColumns(transpose)

تضبط هذه السمة ما إذا كان سيتم نقل صفوف المخطط وأعمدته. إذا تم ضبطها على true، يتم تبديل الصفوف والأعمدة. القيمة التلقائية هي false. 

const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0];  const range = sheet.getRange('A1:B5'); const chart = sheet.newChart()                   .setChartType(Charts.ChartType.BAR)                   .addRange(range)                   .setTransposeRowsAndColumns(true)                   .setPosition(5, 5, 0, 0)                   .build();  sheet.insertChart(chart);

المعلمات

الاسمالنوعالوصف
transposeBooleanإذا كانت القيمة true، يتم تبديل الصفوف والأعمدة المستخدَمة لإنشاء الرسم البياني.

الإرجاع

‫EmbeddedChartBuilder: أداة إنشاء السلاسل