長條圖的建構工具。詳情請參閱 Gviz 說明文件。
方法
內容詳盡的說明文件
add Range(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 | 要新增的範圍。 |
回攻員
Embedded
:這個建構工具,用於鏈結
as Area Chart()
as Bar Chart()
as Column Chart()
as Combo Chart()
as Histogram Chart()
將圖表類型設為 HistogramChart,並傳回 Embedded
。
回攻員
Embedded
:直方圖的建構工具
as Line Chart()
as Pie Chart()
as Scatter Chart()
as Table Chart()
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);
回攻員
Embedded
:已建立的圖表,仍須新增至試算表
clear Ranges()
從這個建構工具修改的圖表中移除所有區間。
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);
回攻員
Embedded
:這個建構工具,用於鏈結
get Chart Type()
get Container()
傳回圖表 Container
,該圖表會封裝圖表在工作表中顯示的位置。
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(), );
回攻員
Container
:包含圖表容器位置的物件
get Ranges()
傳回目前為此圖表提供資料的區間清單副本。使用 add
和 remove
修改這份清單。
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[]
:用於建立圖表的資料來源的區間陣列
remove Range(range)
從這個建構工具修改的圖表中移除指定範圍。如果範圍不在此圖表中,則不會擲回錯誤。
移除的範圍必須與透過 add
新增的範圍相符,否則圖表不會有所變更。這個方法無法用於從範圍中部分移除值。
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 | 要移除的範圍。 |
回攻員
Embedded
:這個建構工具,用於鏈結
reverse Categories()
反轉在網域軸上繪製序列的方向。對於垂直範圍圖表 (例如折線圖、區域圖或長條圖),這表示水平軸是從右至左繪製。對於橫向範圍圖表 (例如長條圖),這表示垂直軸是從上到下繪製。就圓餅圖而言,這表示切片會以逆時針方向繪製。
// Creates a pie chart builder and sets drawing of the slices in a // counter-clockwise manner. const builder = Charts.newPieChart(); builder.reverseCategories();
回攻員
Embedded
:這個建構工具可用於鏈結。
reverse Direction()
set Background Color(cssValue)
設定圖表的背景顏色。
// Creates a line chart builder and sets the background color to gray const builder = Charts.newLineChart(); builder.setBackgroundColor('gray');
參數
名稱 | 類型 | 說明 |
---|---|---|
css | String | 顏色的 CSS 值 (例如 "blue" 或 "#00f" )。 |
回攻員
Embedded
:這個建構工具可用於鏈結。
set Chart Type(type)
變更圖表類型。目前不支援所有嵌入式圖表類型。請參閱 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);
參數
名稱 | 類型 | 說明 |
---|---|---|
type | Chart | 要變更的圖表類型。 |
回攻員
Embedded
:這個建構工具,用於鏈結
set Colors(cssValues)
設定圖表中線條的顏色。
// Creates a line chart builder and sets the first two lines to be drawn in // green and red, respectively. const builder = Charts.newLineChart(); builder.setColors(['green', 'red']);
參數
名稱 | 類型 | 說明 |
---|---|---|
css | String[] | 顏色 CSS 值的陣列,例如 ["red", "#acf"] 。陣列中的第 n 個元素代表圖表中第 n 條線的顏色。 |
回攻員
Embedded
:這個建構工具可用於鏈結。
set Hidden Dimension Strategy(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 | Chart | 用於隱藏資料列和資料欄的策略。 |
回攻員
Embedded
:這個建構工具,用於鏈結
set Legend Position(position)
設定圖例相對於圖表的位置。根據預設,圖例不會顯示。
// Creates a line chart builder and sets the legend position to right. const builder = Charts.newLineChart(); builder.setLegendPosition(Charts.Position.RIGHT);
參數
名稱 | 類型 | 說明 |
---|---|---|
position | Position | 圖例的位置。 |
回攻員
Embedded
:這個建構工具可用於鏈結。
set Legend Text Style(textStyle)
設定圖表圖例的文字樣式。
// Creates a line chart builder and sets it up for a blue, 26-point legend. const textStyleBuilder = Charts.newTextStyle().setColor('#0000FF').setFontSize(26); const style = textStyleBuilder.build(); const builder = Charts.newLineChart(); builder.setLegendTextStyle(style);
參數
名稱 | 類型 | 說明 |
---|---|---|
text | Text | 圖表圖例使用的文字樣式。 |
回攻員
Embedded
:這個建構工具可用於鏈結。
set Merge Strategy(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);
參數
名稱 | 類型 | 說明 |
---|---|---|
merge | Chart | 要使用的合併策略。 |
回攻員
Embedded
:這個建構工具,用於鏈結
set Num Headers(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 | 要視為標頭的列數或欄數。負值會導致系統自動偵測標頭。 |
回攻員
Embedded
:這個建構工具,用於鏈結
set Option(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 | 選項的值。 |
回攻員
Embedded
:這個建構工具可用於鏈結。
set Position(anchorRowPos, anchorColPos, offsetX, offsetY)
設定位置,變更圖表在工作表中顯示的位置。anchor
和 anchor
的索引為 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);
參數
名稱 | 類型 | 說明 |
---|---|---|
anchor | Integer | 圖表的頂端會固定在這個資料列。 |
anchor | Integer | 圖表的左側會固定在這個欄中。 |
offsetX | Integer | 圖表的右上角會偏移這麼多像素。 |
offsetY | Integer | 圖表左下角會偏移這麼多像素。 |
回攻員
Embedded
:這個建構工具,用於鏈結
set Range(start, end)
設定圖表的範圍。
如果有任何資料點超出範圍,範圍就會擴大,納入這些資料點。
參數
名稱 | 類型 | 說明 |
---|---|---|
start | Number | 範圍軸最底的格線值。 |
end | Number | 範圍軸最高格線的值。 |
回攻員
Embedded
:這個建構工具可用於鏈結。
set Stacked()
set Title(chartTitle)
設定圖表的標題。標題會置中顯示在圖表上方。
// Creates a line chart builder and title to 'My Line Chart'. const builder = Charts.newLineChart(); builder.setTitle('My Line Chart');
參數
名稱 | 類型 | 說明 |
---|---|---|
chart | String | 圖表標題。 |
回攻員
Embedded
:這個建構工具可用於鏈結。
set Title Text Style(textStyle)
設定圖表標題的文字樣式。
// Creates a line chart builder and sets it up for a blue, 26-point title. const textStyleBuilder = Charts.newTextStyle().setColor('#0000FF').setFontSize(26); const style = textStyleBuilder.build(); const builder = Charts.newLineChart(); builder.setTitleTextStyle(style);
參數
名稱 | 類型 | 說明 |
---|---|---|
text | Text | 用於圖表標題的文字樣式。您可以呼叫 Charts.newTextStyle() 來建立 Text 物件。 |
回攻員
Embedded
:這個建構工具可用於鏈結。
set Transpose Rows And Columns(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 ,則用於建構圖表的資料列和資料欄會互換。 |
回攻員
Embedded
:這個建構工具,用於鏈結
set XAxis Text Style(textStyle)
設定橫軸的文字樣式。
// Creates a line chart builder and sets the X-axis text style to blue, 18-point // font. const textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build(); const builder = Charts.newLineChart(); builder.setXAxisTextStyle(textStyle);
參數
名稱 | 類型 | 說明 |
---|---|---|
text | Text | 用於水平軸標題的文字樣式。您可以呼叫 Charts.newTextStyle() 來建立 Text 物件。 |
回攻員
Embedded
:這個建構工具可用於鏈結。
set XAxis Title(title)
在水平軸上新增標題。標題會置中,並顯示在軸值標籤下方。
// Creates a line chart builder and sets the X-axis title. const builder = Charts.newLineChart(); builder.setTitle('X-axis Title');
參數
名稱 | 類型 | 說明 |
---|---|---|
title | String | X 軸的標題。 |
回攻員
Embedded
:這個建構工具可用於鏈結。
set XAxis Title Text Style(textStyle)
設定水平軸標題的文字樣式。
// Creates a line chart builder and sets the X-axis title text style to blue, // 18-point font. const textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build(); const builder = Charts.newLineChart(); builder.setXAxisTitleTextStyle(textStyle);
參數
名稱 | 類型 | 說明 |
---|---|---|
text | Text | 用於水平軸標題的文字樣式。您可以呼叫 Charts.newTextStyle() 來建立 Text 物件。 |
回攻員
Embedded
:這個建構工具可用於鏈結。
set YAxis Text Style(textStyle)
設定垂直軸文字樣式。
// Creates a line chart builder and sets the Y-axis text style to blue, 18-point // font. const textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build(); const builder = Charts.newLineChart(); builder.setYAxisTextStyle(textStyle);
參數
名稱 | 類型 | 說明 |
---|---|---|
text | Text | 用於水平軸標題的文字樣式。您可以呼叫 Charts.newTextStyle() 來建立 Text 物件。 |
回攻員
Embedded
:這個建構工具可用於鏈結。
set YAxis Title(title)
為垂直軸新增標題。標題會置中,並顯示在值標籤的左側。
// Creates a line chart builder and sets the Y-axis title. const builder = Charts.newLineChart(); builder.setYAxisTitle('Y-axis Title');
參數
名稱 | 類型 | 說明 |
---|---|---|
title | String | Y 軸的標題。 |
回攻員
Embedded
:這個建構工具可用於鏈結。
set YAxis Title Text Style(textStyle)
設定垂直軸標題的文字樣式。
// Creates a line chart builder and sets the Y-axis title text style to blue, // 18-point font. const textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build(); const builder = Charts.newLineChart(); builder.setYAxisTitleTextStyle(textStyle);
參數
名稱 | 類型 | 說明 |
---|---|---|
text | Text | 用於水平軸標題的文字樣式。您可以呼叫 Charts.newTextStyle() 來建立 Text 物件。 |
回攻員
Embedded
:這個建構工具可用於鏈結。
use Log Scale()
將範圍軸設為對數刻度 (所有值都必須為正值)。範圍軸是垂直圖表 (例如折線圖、面積圖或柱狀圖) 的垂直軸,也是水平圖表 (例如長條圖) 的水平軸。
回攻員
Embedded
:這個建構工具可用於鏈結。