Class EmbeddedChartBuilder

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將圖表類型設為「散佈圖」並傳回 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);

參數

名稱類型說明
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()

將圖表類型設為「散佈圖」並傳回 EmbeddedScatterChartBuilder。

回攻員

EmbeddedScatterChartBuilder：散佈圖的建構工具

asTableChart()

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

回攻員

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);

回攻員

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);

回攻員

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

getChartType()

傳回目前圖表類型。

回攻員

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());

回攻員

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());
}

回攻員

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);

參數

名稱類型說明
rangeRange要移除的範圍。

回攻員

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);

參數

名稱類型說明
typeChartType這個圖表要變更為哪種類型。

回攻員

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);

參數

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

回攻員

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);

參數

名稱類型說明
mergeStrategyChartMergeStrategy要使用的合併策略。

回攻員

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);

參數

名稱類型說明
headersInteger要視為標題的列數或欄數。負值會導致標頭 以便自動偵測。

回攻員

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

setOption(option, value)

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

這個方法不會驗證您指定的選項對這個圖表類型或 值為正確格式/結構。

這個範例說明如何變更標題及設定圖例。 

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

參數

名稱類型說明
optionString選項名稱。
valueObject選項的值。

回攻員

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);

參數

名稱類型說明
anchorRowPosInteger圖表的頂端會固定在這個資料列中。
anchorColPosInteger圖表左側會錨定在這一欄。
offsetXInteger圖表右上角會偏移這個像素數。
offsetYInteger圖表的左下角會有許多像素偏移。

回攻員

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);

參數

名稱類型說明
transposeBoolean如果是 true，表示用於建構圖表的資料列與資料欄 轉置。

回攻員

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