Class EmbeddedTableChartBuilder

內嵌資料表圖表建構工具

表格圖表的建構工具。詳情請參閱 Gviz 說明文件。

方法

方法	傳回類型	簡短說明
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	從這個建構工具修改的圖表中移除所有區間。
enablePaging(enablePaging)	EmbeddedTableChartBuilder	設定是否啟用資料分頁功能。
enablePaging(pageSize)	EmbeddedTableChartBuilder	啟用分頁功能，並設定每個頁面中的資料列數量。
enablePaging(pageSize, startPage)	EmbeddedTableChartBuilder	啟用分頁功能，設定每個頁面的列數和要顯示的第一個表格頁面 (頁碼以零為基底)。
enableRtlTable(rtlEnabled)	EmbeddedTableChartBuilder	透過反轉表格的欄順序，為由右至左的語言 (例如阿拉伯文或希伯來文) 新增基本支援功能，讓第 0 欄成為最右邊的欄，而最後一欄則是位於最左邊。
enableSorting(enableSorting)	EmbeddedTableChartBuilder	設定使用者點選資料欄標題時是否要排序資料欄。
getChartType()	ChartType	傳回目前的圖表類型。
getContainer()	ContainerInfo	傳回圖表 ContainerInfo，該圖表會封裝圖表在工作表中顯示的位置。
getRanges()	Range[]	傳回目前為此圖表提供資料的區間清單副本。
removeRange(range)	EmbeddedChartBuilder	從這個建構工具修改的圖表中移除指定範圍。
setChartType(type)	EmbeddedChartBuilder	變更圖表類型。
setFirstRowNumber(number)	EmbeddedTableChartBuilder	設定資料表中第一列的資料列號。
setHiddenDimensionStrategy(strategy)	EmbeddedChartBuilder	設定要用於隱藏資料列和資料欄的策略。
setInitialSortingAscending(column)	EmbeddedTableChartBuilder	根據表格應初始排序的欄索引 (遞增) 進行設定。
setInitialSortingDescending(column)	EmbeddedTableChartBuilder	設定表格應依據哪個欄進行初始排序 (遞減)。
setMergeStrategy(mergeStrategy)	EmbeddedChartBuilder	設定在有多個範圍時要使用的合併策略。
setNumHeaders(headers)	EmbeddedChartBuilder	設定要視為標頭的範圍列數或欄數。
setOption(option, value)	EmbeddedChartBuilder	設定這張圖表的進階選項。
setPosition(anchorRowPos, anchorColPos, offsetX, offsetY)	EmbeddedChartBuilder	設定位置，變更圖表在工作表中顯示的位置。
setTransposeRowsAndColumns(transpose)	EmbeddedChartBuilder	設定是否要將圖表的資料列和資料欄互換。
showRowNumberColumn(showRowNumber)	EmbeddedTableChartBuilder	設定是否要將資料列號碼顯示為表格的第一欄。
useAlternatingRowStyle(alternate)	EmbeddedTableChartBuilder	設定是否將交替顏色樣式指派給表格圖表的奇數和偶數列。

內容詳盡的說明文件

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

參數

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

回攻員

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

---

enablePaging(enablePaging)

設定是否要啟用資料分頁功能。

預設行為是停用分頁。如果啟用分頁，預設的頁面大小為 10。

參數

名稱	類型	說明
enablePaging	Boolean	如果應啟用分頁，則為 true，否則為 false。

回攻員

EmbeddedTableChartBuilder：這個建構工具可用於鏈結。

---

enablePaging(pageSize)

啟用分頁功能，並設定每個頁面中的資料列數量。

預設頁面大小為 10。

// Creates a table chart builder and enables paging with page size of 5.
const builder = Charts.newTableChart();
builder.enablePaging(5);

參數

名稱	類型	說明
pageSize	Integer	資料表每頁的資料列數。

回攻員

EmbeddedTableChartBuilder：這個建構工具可用於鏈結。

---

enablePaging(pageSize, startPage)

啟用分頁功能，設定每個頁面的列數和要顯示的第一個表格頁面 (頁碼以零為基底)。

預設的頁面大小為 10，預設的起始頁面為 0。

// Creates a table chart builder and enables paging with page size of 5 and
// displays page 2 first.
const builder = Charts.newTableChart();
builder.enablePaging(5, 2);

參數

名稱	類型	說明
pageSize	Integer	資料表每頁的資料列數。
startPage	Integer	要顯示的第一個表格頁面 (頁碼以 0 為基底)。

回攻員

EmbeddedTableChartBuilder：這個建構工具可用於鏈結。

---

enableRtlTable(rtlEnabled)

為由右至左的語言 (例如阿拉伯文或希伯來文) 新增基本支援功能，方法是將表格的欄順序倒轉，讓第 0 欄成為最右側欄，而最後一欄則是左側欄。

這不會影響基礎資料中的資料欄索引，只會影響顯示順序。即使啟用這個選項，表格視覺化工具也不支援完整的雙向 (BiDi) 語言顯示功能。如果您啟用分頁 (使用「分頁」選項)，或是表格有捲軸，因為您指定的高度和寬度選項小於必要的表格大小，系統會忽略這個選項。預設行為是停用 RTL 支援。

參數

名稱	類型	說明
rtlEnabled	Boolean	true 表示應啟用由右至左的支援功能，否則為 false。

回攻員

EmbeddedTableChartBuilder：這個建構工具可用於鏈結。

---

enableSorting(enableSorting)

設定使用者點選資料欄標題時是否要排序資料欄。

如果啟用排序功能，使用者只要點選資料欄標題，系統就會自動排序資料列。預設行為是啟用排序。

參數

名稱	類型	說明
enableSorting	Boolean	true 可啟用按一下欄標題的排序功能，否則為 false。

回攻員

EmbeddedTableChartBuilder：這個建構工具可用於鏈結。

---

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

const chart = chartBuilder.build();

sheet.insertChart(chart);

參數

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

回攻員

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

參數

名稱	類型	說明
type	ChartType	要變更的圖表類型。

回攻員

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

---

setFirstRowNumber(number)

設定資料表中第一列的資料列編號。

第一列的預設列號為 1。

// Creates a table chart builder and sets the first row to be 2.
const builder = Charts.newTableChart();
builder.setFirstRowNumber(2);

參數

名稱	類型	說明
number	Integer	資料表中第一列的列號。

回攻員

EmbeddedTableChartBuilder：這個建構工具可用於鏈結。

---

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

參數

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

回攻員

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

---

setInitialSortingAscending(column)

根據表格應最初以遞增方式排序的欄，設定該欄的索引。

資料欄以遞增順序排序，並標示有小箭頭。

// Creates a table chart builder and sorts it by the second column (ascending).
const builder = Charts.newTableChart();
builder.setInitialSortingAscending(2);

參數

名稱	類型	說明
column	Integer	資料表應以哪個資料欄進行初始排序。

回攻員

EmbeddedTableChartBuilder：這個建構工具可用於鏈結。

---

setInitialSortingDescending(column)

設定表格應依據哪個欄進行初始排序 (遞減)。

資料欄以遞減順序排序，並標示有小箭頭。

// Creates a table chart builder and sorts it by the second column (descending).
const builder = Charts.newTableChart();
builder.setInitialSortingDescending(2);

參數

名稱	類型	說明
column	Integer	資料表應以哪個資料欄進行初始排序。

回攻員

EmbeddedTableChartBuilder：這個建構工具可用於鏈結。

---

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

參數

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

回攻員

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

參數

名稱	類型	說明
headers	Integer	要視為標頭的列數或欄數。負值會導致系統自動偵測標頭。

回攻員

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

參數

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

回攻員

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

參數

名稱	類型	說明
anchorRowPos	Integer	圖表的頂端會固定在這個資料列。
anchorColPos	Integer	圖表的左側會固定在這個欄中。
offsetX	Integer	圖表的右上角會偏移這麼多像素。
offsetY	Integer	圖表左下角會偏移這麼多像素。

回攻員

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

參數

名稱	類型	說明
transpose	Boolean	如果為 true，則用於建構圖表的資料列和資料欄會互換。

回攻員

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

---

showRowNumberColumn(showRowNumber)

設定是否要將資料列號碼顯示為表格的第一欄。

預設行為是不會顯示資料列數。

參數

名稱	類型	說明
showRowNumber	Boolean	true 如果表格的第一欄應顯示列號，則為 false，否則為 false。

回攻員

EmbeddedTableChartBuilder：這個建構工具可用於鏈結。

---

useAlternatingRowStyle(alternate)

設定是否將交替顏色樣式指派給表格圖表的奇數和偶數列。

預設行為是使用交替色彩樣式。

參數

名稱	類型	說明
alternate	Boolean	如果應交替顯示顏色樣式，請使用 true，否則請使用 false。

回攻員

EmbeddedTableChartBuilder：這個建構工具可用於鏈結。