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：這個建構工具用於鏈結。