Class EmbeddedScatterChartBuilder

內嵌散布圖表建立器

散布圖的建構工具。詳情請參閱 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從這個建構工具修改的圖表中移除指定範圍。
setBackgroundColor(cssValue)EmbeddedScatterChartBuilder設定圖表的背景顏色。
setChartType(type)EmbeddedChartBuilder變更圖表類型。
setColors(cssValues)EmbeddedScatterChartBuilder設定圖表中折線的顏色。
setHiddenDimensionStrategy(strategy)EmbeddedChartBuilder設定要用於隱藏資料列和資料欄的策略。
setLegendPosition(position)EmbeddedScatterChartBuilder設定圖例相對於圖表的位置。
setLegendTextStyle(textStyle)EmbeddedScatterChartBuilder設定圖表圖例的文字樣式。
setMergeStrategy(mergeStrategy)EmbeddedChartBuilder設定在有多個範圍時要使用的合併策略。
setNumHeaders(headers)EmbeddedChartBuilder設定要視為標頭的範圍列數或欄數。
setOption(option, value)EmbeddedChartBuilder設定這張圖表的進階選項。
setPointStyle(style)EmbeddedScatterChartBuilder設定線條中點的樣式。
setPosition(anchorRowPos, anchorColPos, offsetX, offsetY)EmbeddedChartBuilder設定位置,變更圖表在工作表中顯示的位置。
setTitle(chartTitle)EmbeddedScatterChartBuilder設定圖表的標題。
setTitleTextStyle(textStyle)EmbeddedScatterChartBuilder設定圖表標題的文字樣式。
setTransposeRowsAndColumns(transpose)EmbeddedChartBuilder設定是否要將圖表的資料列和資料欄互換。
setXAxisLogScale()EmbeddedScatterChartBuilder將水平軸設為對數刻度 (所有值都必須為正值)。
setXAxisRange(start, end)EmbeddedScatterChartBuilder設定圖表的水平軸範圍。
setXAxisTextStyle(textStyle)EmbeddedScatterChartBuilder設定橫軸的文字樣式。
setXAxisTitle(title)EmbeddedScatterChartBuilder在水平軸上新增標題。
setXAxisTitleTextStyle(textStyle)EmbeddedScatterChartBuilder設定水平軸標題的文字樣式。
setYAxisLogScale()EmbeddedScatterChartBuilder將垂直軸設為對數刻度 (所有值都必須為正值)。
setYAxisRange(start, end)EmbeddedScatterChartBuilder設定圖表垂直軸的範圍。
setYAxisTextStyle(textStyle)EmbeddedScatterChartBuilder設定垂直軸文字樣式。
setYAxisTitle(title)EmbeddedScatterChartBuilder為垂直軸新增標題。
setYAxisTitleTextStyle(textStyle)EmbeddedScatterChartBuilder設定垂直軸標題的文字樣式。

內容詳盡的說明文件

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


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")。

回攻員

EmbeddedScatterChartBuilder:這個建構工具可用於鏈結。


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 條線的顏色。

回攻員

EmbeddedScatterChartBuilder:這個建構工具可用於鏈結。


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圖例的位置。

回攻員

EmbeddedScatterChartBuilder:這個建構工具可用於鏈結。


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圖表圖例使用的文字樣式。

回攻員

EmbeddedScatterChartBuilder:這個建構工具可用於鏈結。


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:這個建構工具可用於鏈結。


setPointStyle(style)

設定線條中點的樣式。根據預設,點沒有特定樣式,只有線會顯示。

// Creates a line chart builder and sets large point style.
const builder = Charts.newLineChart();
builder.setPointStyle(Charts.PointStyle.LARGE);

參數

名稱類型說明
stylePointStyle用於線條中點的樣式。

回攻員

EmbeddedScatterChartBuilder:這個建構工具可用於鏈結。

另請參閱


setPosition(anchorRowPos, anchorColPos, offsetX, offsetY)

設定位置,變更圖表在工作表中顯示的位置。anchorRowPosanchorColPos 的索引為 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:這個建構工具,用於鏈結


setTitle(chartTitle)

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

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

參數

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

回攻員

EmbeddedScatterChartBuilder:這個建構工具可用於鏈結。


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 物件。

回攻員

EmbeddedScatterChartBuilder:這個建構工具可用於鏈結。


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


setXAxisLogScale()

將水平軸設為對數刻度 (所有值都必須為正值)。

回攻員

EmbeddedScatterChartBuilder:這個建構工具可用於鏈結。


setXAxisRange(start, end)

設定圖表的水平軸範圍。

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

// Creates a scatter chart builder and sets the X-axis range to be 0 to 100.
const builder = Charts.newTableChart();
builder.setXAxisRange(0, 100);

參數

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

回攻員

EmbeddedScatterChartBuilder:這個建構工具可用於鏈結。


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 物件。

回攻員

EmbeddedScatterChartBuilder:這個建構工具可用於鏈結。


setXAxisTitle(title)

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

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

參數

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

回攻員

EmbeddedScatterChartBuilder:這個建構工具可用於鏈結。


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 物件。

回攻員

EmbeddedScatterChartBuilder:這個建構工具可用於鏈結。


setYAxisLogScale()

將垂直軸設為對數刻度 (所有值都必須為正值)。

回攻員

EmbeddedScatterChartBuilder:這個建構工具可用於鏈結。


setYAxisRange(start, end)

設定圖表垂直軸的範圍。如果有任何資料點超出範圍,範圍就會擴大,納入這些資料點。

// Creates a scatter chart builder and sets the Y-axis range to be 0 to 100.
const builder = Charts.newTableChart();
builder.setYAxisRange(0, 100);

參數

名稱類型說明
startNumber垂直軸最底部格線的值。
endNumber垂直軸最高格線的值。

回攻員

EmbeddedScatterChartBuilder:這個建構工具可用於鏈結。


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 物件。

回攻員

EmbeddedScatterChartBuilder:這個建構工具可用於鏈結。


setYAxisTitle(title)

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

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

參數

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

回攻員

EmbeddedScatterChartBuilder:這個建構工具可用於鏈結。


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 物件。

回攻員

EmbeddedScatterChartBuilder:這個建構工具可用於鏈結。