本頁面由 Cloud Translation API 翻譯而成。

Class EmbeddedChartBuilder

用於編輯 EmbeddedChart 的建構工具。除非在重新建立的圖表上呼叫 Sheet.updateChart(chart)，否則系統不會儲存對圖表所做的變更。

var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("A1:B8");
var 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)`

新增這個建構工具修改的圖表範圍。如果範圍已新增至圖表，則不新增。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var chart = sheet.newChart()
    .setChartType(Charts.ChartType.BAR)
    .addRange(sheet.getRange("A1:B8"))
    .setPosition(5, 5, 0, 0)
    .build();

sheet.insertChart(chart);

參數

名稱	類型	說明
`range`	`Range`	要新增的範圍。

Return 鍵

EmbeddedChartBuilder：這個用於鏈結的建構工具

`asAreaChart()`

將圖表類型設為 AreaChart，並傳回 EmbeddedAreaChartBuilder。

Return 鍵

EmbeddedAreaChartBuilder：面積圖的建構工具

`asBarChart()`

將圖表類型設為 BarChart，並傳回 EmbeddedBarChartBuilder。

Return 鍵

EmbeddedBarChartBuilder：長條圖的建構工具

`asColumnChart()`

將圖表類型設為 ColumnChart，並傳回 EmbeddedColumnChartBuilder。

Return 鍵

EmbeddedColumnChartBuilder：柱狀圖的建構工具

`asComboChart()`

將圖表類型設為 ComboChart，並傳回 EmbeddedComboChartBuilder。

Return 鍵

EmbeddedComboChartBuilder：組合圖的建構工具

`asHistogramChart()`

將圖表類型設為 HistogramChart，並傳回 EmbeddedHistogramChartBuilder。

Return 鍵

EmbeddedHistogramChartBuilder：直方圖圖表的建構工具

`asLineChart()`

將圖表類型設為 LineChart，並傳回 EmbeddedLineChartBuilder。

Return 鍵

EmbeddedLineChartBuilder：折線圖的建構工具

`asPieChart()`

將圖表類型設為 PieChart，並傳回 EmbeddedPieChartBuilder。

Return 鍵

EmbeddedPieChartBuilder：圓餅圖建構工具

`asScatterChart()`

將圖表類型設為 ScatterChart，並傳回 EmbeddedScatterChartBuilder。

Return 鍵

EmbeddedScatterChartBuilder：散佈圖的建構工具

`asTableChart()`

將圖表類型設為 TableChart，並傳回 EmbeddedTableChartBuilder。

Return 鍵

EmbeddedTableChartBuilder：表格圖表的建構工具

`build()`

建立圖表以反映該圖表的所有變更。

這個方法不會自動在試算表上方繪製圖表。新圖表必須透過 sheet.insertChart(chart) 插入，現有圖表則應透過 sheet.updateChart(chart) 更新。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var range = sheet.getRange("A1:B5");
var chart = sheet.newChart()
    .setChartType(Charts.ChartType.BAR)
    .addRange(range)
    .setPosition(5, 5, 0, 0)
    .build();

sheet.insertChart(chart);

Return 鍵

EmbeddedChart：已建立的圖表，仍須新增至試算表

`clearRanges()`

從這個建構工具修改的圖表中移除所有範圍。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

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

Return 鍵

EmbeddedChartBuilder：這個用於鏈結的建構工具

`getChartType()`

傳回目前的圖表類型。

Return 鍵

ChartType：圖表類型

`getContainer()`

傳回圖表 ContainerInfo，用於封裝圖表在工作表中的位置。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var 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()
var containerInfo = chartBuilder.getContainer();

// Logs the values we 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());

Return 鍵

ContainerInfo：包含圖表容器位置的物件

`getRanges()`

傳回目前提供此圖表資料範圍的清單副本。你可以透過 addRange(range) 和 removeRange(range) 修改這份清單。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var chartBuilder = sheet.newChart()
    .setChartType(Charts.ChartType.BAR)
    .addRange(sheet.getRange("A1:B8"))
    .setPosition(5, 5, 0, 0);

var ranges = chartBuilder.getRanges();

// There's only one range as a data source for this chart,
// so this logs "A1:B8"
for (var i in ranges) {
  var range = ranges[i];
  Logger.log(range.getA1Notation());
}

Return 鍵

Range[]：做為建構圖表的圖表陣列範圍

`removeRange(range)`

從建構工具修改的圖表中移除指定範圍。如果範圍內沒有在此圖表中，則不會擲回錯誤。

移除的範圍必須與透過 addRange(range) 新增的範圍相符；否則不會對圖表進行任何變更。您無法使用這個方法從範圍中移除部分值。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var firstRange = sheet.getRange("A1:B5");
var secondRange = sheet.getRange("A6:B8");

var chartBuilder = sheet.newChart()
    .setChartType(Charts.ChartType.BAR)
    .addRange(firstRange)
    // This range will render 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
// will not be removed, and will not throw an exception
chartBuilder.removeRange(firstRange);
chartBuilder.removeRange(sheet.getRange("A6:B8"));

var chart = chartBuilder.build();

sheet.insertChart(chart);

參數

名稱	類型	說明
`range`	`Range`	要移除的範圍。

Return 鍵

EmbeddedChartBuilder：這個用於鏈結的建構工具

`setChartType(type)`

變更圖表類型。目前並非所有內嵌圖表類型都支援。請參閱 ChartType。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var range = sheet.getRange("A1:B5");
var chart = sheet.newChart()
    .setChartType(Charts.ChartType.BAR)
    .addRange(range)
    .setPosition(5, 5, 0, 0)
    .build();

sheet.insertChart(chart);

參數

名稱	類型	說明
`type`	`ChartType`	變更這張圖表的類型。

Return 鍵

EmbeddedChartBuilder：這個用於鏈結的建構工具

`setHiddenDimensionStrategy(strategy)`

設定用於隱藏列和欄的策略。這個變數預設為 IGNORE_ROWS。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var range = sheet.getRange("A1:B5");
var chart = sheet.newChart()
    .setChartType(Charts.ChartType.BAR)
    .addRange(range)
    .setHiddenDimensionStrategy(Charts.ChartHiddenDimensionStrategy.IGNORE_COLUMNS)
    .setPosition(5, 5, 0, 0)
    .build();

sheet.insertChart(chart);

參數

名稱	類型	說明
`strategy`	`ChartHiddenDimensionStrategy`	用於隱藏列和欄的策略。

Return 鍵

EmbeddedChartBuilder：這個用於鏈結的建構工具

`setMergeStrategy(mergeStrategy)`

設定包含多個範圍的合併策略。如為 MERGE_ROWS，系統會合併資料列；如果為 MERGE_COLUMNS，則會合併資料欄。這個變數預設為 MERGE_COLUMNS。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var range = sheet.getRange("A1:B10");
var range2 = sheet.getRange("C:C10");
var 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);

參數

名稱	類型	說明
`mergeStrategy`	`ChartMergeStrategy`	要使用的合併策略。

Return 鍵

EmbeddedChartBuilder：這個用於鏈結的建構工具

`setNumHeaders(headers)`

設定應視為範圍的列數或欄數。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var range = sheet.getRange("A1:B5");
var chart = sheet.newChart()
    .setChartType(Charts.ChartType.BAR)
    .addRange(range)
    .setNumHeaders(1)
    .setPosition(5, 5, 0, 0)
    .build();

sheet.insertChart(chart);

參數

名稱	類型	說明
`headers`	`Integer`	要視為標頭的列數或欄數。如果設定負值，即可自動偵測標頭。

Return 鍵

EmbeddedChartBuilder：這個用於鏈結的建構工具

`setOption(option, value)`

設定這張圖表的進階選項。如要查看可用選項的清單，請參閱圖表設定選項一文。

這個方法不會驗證您指定的選項是否適用於此圖表類型，或者值的格式/格式是否正確。

以下範例說明如何變更標題及設定圖例。

builder.setOption('title', 'Earnings projections');
builder.setOption('legend', {position: 'top', textStyle: {color: 'blue', fontSize: 16}});

參數

名稱	類型	說明
`option`	`String`	選項的名稱。
`value`	`Object`	選項的值。

Return 鍵

EmbeddedChartBuilder — 用於鏈結的建構工具。

`setPosition(anchorRowPos, anchorColPos, offsetX, offsetY)`

設定位置，以變更圖表在工作表中的顯示位置。anchorRowPos 和 anchorColPos 已建立索引。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var range = sheet.getRange("A1:B5");
var chart = sheet.newChart()
    .setChartType(Charts.ChartType.BAR)
    .addRange(range)
    .setPosition(5, 5, 0, 0)
    .build();

sheet.insertChart(chart);

參數

名稱	類型	說明
`anchorRowPos`	`Integer`	圖表的上方固定在該列的上方。
`anchorColPos`	`Integer`	圖表的左側會固定在圖表的左側。
`offsetX`	`Integer`	圖表的右上角會覆寫許多像素。
`offsetY`	`Integer`	圖表的左下角與這個像素值偏移。

Return 鍵

EmbeddedChartBuilder：這個用於鏈結的建構工具

`setTransposeRowsAndColumns(transpose)`

設定是否傳輸圖表列和欄。如果設為 true，則會切換資料列與資料欄。這個變數預設為 false。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var range = sheet.getRange("A1:B5");
var chart = sheet.newChart()
    .setChartType(Charts.ChartType.BAR)
    .addRange(range)
    .setTransposeRowsAndColumns(true)
    .setPosition(5, 5, 0, 0)
    .build();

sheet.insertChart(chart);

參數

名稱	類型	說明
`transpose`	`Boolean`	如為 `true`，系統會轉錄用於建構圖表的資料列和資料欄。

Return 鍵

EmbeddedChartBuilder：這個用於鏈結的建構工具