Class EmbeddedHistogramChartBuilder

內嵌直方圖圖表建構工具

直方圖的建構工具。詳情請參閱 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從這個建構工具修改的圖表中移除所有區間。
getChartType()ChartType傳回目前的圖表類型。
getContainer()ContainerInfo傳回圖表 ContainerInfo，該圖表會封裝圖表在工作表中顯示的位置。
getRanges()Range[]傳回目前為此圖表提供資料的區間清單副本。
removeRange(range)EmbeddedChartBuilder從這個建構工具修改的圖表中移除指定範圍。
reverseCategories()EmbeddedHistogramChartBuilder反轉在網域軸上繪製序列的方向。
setBackgroundColor(cssValue)EmbeddedHistogramChartBuilder設定圖表的背景顏色。
setChartType(type)EmbeddedChartBuilder變更圖表類型。
setColors(cssValues)EmbeddedHistogramChartBuilder設定圖表中折線的顏色。
setHiddenDimensionStrategy(strategy)EmbeddedChartBuilder設定要用於隱藏資料列和資料欄的策略。
setLegendPosition(position)EmbeddedHistogramChartBuilder設定圖例相對於圖表的位置。
setLegendTextStyle(textStyle)EmbeddedHistogramChartBuilder設定圖表圖例的文字樣式。
setMergeStrategy(mergeStrategy)EmbeddedChartBuilder設定在有多個範圍時要使用的合併策略。
setNumHeaders(headers)EmbeddedChartBuilder設定要視為標頭的範圍列數或欄數。
setOption(option, value)EmbeddedChartBuilder設定這張圖表的進階選項。
setPosition(anchorRowPos, anchorColPos, offsetX, offsetY)EmbeddedChartBuilder設定位置，變更圖表在工作表中顯示的位置。
setRange(start, end)EmbeddedHistogramChartBuilder設定圖表的範圍。
setStacked()EmbeddedHistogramChartBuilder使用堆疊線條，也就是說，線條和長條圖的值會堆疊 (累加)。
setTitle(chartTitle)EmbeddedHistogramChartBuilder設定圖表的標題。
setTitleTextStyle(textStyle)EmbeddedHistogramChartBuilder設定圖表標題的文字樣式。
setTransposeRowsAndColumns(transpose)EmbeddedChartBuilder設定是否要將圖表的資料列和資料欄互換。
setXAxisTextStyle(textStyle)EmbeddedHistogramChartBuilder設定橫軸的文字樣式。
setXAxisTitle(title)EmbeddedHistogramChartBuilder在水平軸上新增標題。
setXAxisTitleTextStyle(textStyle)EmbeddedHistogramChartBuilder設定水平軸標題的文字樣式。
setYAxisTextStyle(textStyle)EmbeddedHistogramChartBuilder設定垂直軸文字樣式。
setYAxisTitle(title)EmbeddedHistogramChartBuilder為垂直軸新增標題。
setYAxisTitleTextStyle(textStyle)EmbeddedHistogramChartBuilder設定垂直軸標題的文字樣式。
useLogScale()EmbeddedHistogramChartBuilder將範圍軸設為對數刻度 (所有值都必須為正值)。

內容詳盡的說明文件

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

參數

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

回攻員

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

reverseCategories()

反轉在網域軸上繪製序列的方向。對於垂直範圍圖表 (例如折線圖、區域圖或長條圖)，這表示水平軸是從右至左繪製。對於橫向範圍圖表 (例如長條圖)，這表示垂直軸是從上到下繪製。就圓餅圖而言，這表示切片會以逆時針方向繪製。

// Creates a pie chart builder and sets drawing of the slices in a
// counter-clockwise manner.
const builder = Charts.newPieChart();
builder.reverseCategories();

回攻員

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

setBackgroundColor(cssValue)

設定圖表的背景顏色。

// Creates a line chart builder and sets the background color to gray
const builder = Charts.newLineChart();
builder.setBackgroundColor('gray');

參數

名稱類型說明
cssValueString顏色的 CSS 值 (例如 "blue" 或 "#00f")。

回攻員

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

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

setColors(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']);

參數

名稱類型說明
cssValuesString[]顏色 CSS 值的陣列，例如 ["red", "#acf"]。陣列中的第 n 個元素代表圖表中第 n 條線的顏色。

回攻員

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

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

setLegendPosition(position)

設定圖例相對於圖表的位置。根據預設，圖例不會顯示。

// Creates a line chart builder and sets the legend position to right.
const builder = Charts.newLineChart();
builder.setLegendPosition(Charts.Position.RIGHT);

參數

名稱類型說明
positionPosition圖例的位置。

回攻員

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

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

參數

名稱類型說明
textStyleTextStyle圖表圖例使用的文字樣式。

回攻員

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

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

setRange(start, end)

設定圖表的範圍。

如果有任何資料點超出範圍，範圍就會擴大，納入這些資料點。

參數

名稱類型說明
startNumber範圍軸最底的格線值。
endNumber範圍軸最高格線的值。

回攻員

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

setStacked()

使用堆疊線條，也就是說，線條和長條圖的值會堆疊 (累積)。根據預設，系統不會堆疊。

回攻員

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

setTitle(chartTitle)

設定圖表的標題。標題會置中顯示在圖表上方。

// Creates a line chart builder and title to 'My Line Chart'.
const builder = Charts.newLineChart();
builder.setTitle('My Line Chart');

參數

名稱類型說明
chartTitleString圖表標題。

回攻員

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

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

參數

名稱類型說明
textStyleTextStyle用於圖表標題的文字樣式。您可以呼叫 Charts.newTextStyle() 來建立 TextStyleBuilder 物件。

回攻員

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

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

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

參數

名稱類型說明
textStyleTextStyle用於水平軸標題的文字樣式。您可以呼叫 Charts.newTextStyle() 來建立 TextStyleBuilder 物件。

回攻員

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

setXAxisTitle(title)

在水平軸上新增標題。標題會置中，並顯示在軸值標籤下方。

// Creates a line chart builder and sets the X-axis title.
const builder = Charts.newLineChart();
builder.setTitle('X-axis Title');

參數

名稱類型說明
titleStringX 軸的標題。

回攻員

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

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

參數

名稱類型說明
textStyleTextStyle用於水平軸標題的文字樣式。您可以呼叫 Charts.newTextStyle() 來建立 TextStyleBuilder 物件。

回攻員

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

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

參數

名稱類型說明
textStyleTextStyle用於水平軸標題的文字樣式。您可以呼叫 Charts.newTextStyle() 來建立 TextStyleBuilder 物件。

回攻員

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

setYAxisTitle(title)

為垂直軸新增標題。標題會置中，並顯示在值標籤的左側。

// Creates a line chart builder and sets the Y-axis title.
const builder = Charts.newLineChart();
builder.setYAxisTitle('Y-axis Title');

參數

名稱類型說明
titleStringY 軸的標題。

回攻員

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

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

參數

名稱類型說明
textStyleTextStyle用於水平軸標題的文字樣式。您可以呼叫 Charts.newTextStyle() 來建立 TextStyleBuilder 物件。

回攻員

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

useLogScale()

將範圍軸設為對數刻度 (所有值都必須為正值)。範圍軸是垂直圖表 (例如折線圖、面積圖或柱狀圖) 的垂直軸，也是水平圖表 (例如長條圖) 的水平軸。

回攻員

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