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

参数

名称	类型	说明
range	Range	要添加的范围。

返回

EmbeddedChartBuilder - this 构建器，用于链式调用

---

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 - this 构建器，用于链式调用

---

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 - this 构建器，用于链式调用

---

setBackgroundColor(cssValue)

设置图表的背景颜色。

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

参数

名称	类型	说明
cssValue	String	颜色的 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);

参数

名称	类型	说明
type	ChartType	要将此图表更改为的类型。

返回

EmbeddedChartBuilder - this 构建器，用于链式调用

---

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

参数

名称	类型	说明
cssValues	String[]	颜色 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);

参数

名称	类型	说明
strategy	ChartHiddenDimensionStrategy	要对隐藏的行和列使用的策略。

返回

EmbeddedChartBuilder - this 构建器，用于链式调用

---

setLegendPosition(position)

设置图例相对于图表的位置。默认情况下，没有图例。

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

参数

名称	类型	说明
position	Position	图例的位置。

返回

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

参数

名称	类型	说明
textStyle	TextStyle	要为图表图例使用的文本样式。

返回

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

参数

名称	类型	说明
mergeStrategy	ChartMergeStrategy	要使用的合并策略。

返回

EmbeddedChartBuilder - this 构建器，用于链式调用

---

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 - this 构建器，用于链式调用

---

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 - 此构建器，用于链式调用。

---

setPointStyle(style)

设置线条中点的样式。默认情况下，数据点没有特定样式，并且只有线条可见。

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

参数

名称	类型	说明
style	PointStyle	用于线条中点的样式。

返回

EmbeddedScatterChartBuilder - 此构建器适用于链接。

另请参阅

• PointStyle

---

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 - this 构建器，用于链式调用

---

setTitle(chartTitle)

设置图表的标题。标题会居中显示在图表上方。

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

参数

名称	类型	说明
chartTitle	String	图表标题。

返回

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

参数

名称	类型	说明
textStyle	TextStyle	要为图表标题使用的文本样式。您可以通过调用 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);

参数

名称	类型	说明
transpose	Boolean	如果为 true，则用于构建图表的行和列会被转置。

返回

EmbeddedChartBuilder - this 构建器，用于链式调用

---

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

参数

名称	类型	说明
start	Number	水平轴最下方网格线的值。
end	Number	水平轴上最高网格线的值。

返回

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

参数

名称	类型	说明
textStyle	TextStyle	要为横轴标题使用的文本样式。您可以通过调用 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');

参数

名称	类型	说明
title	String	X 轴的标题。

返回

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

参数

名称	类型	说明
textStyle	TextStyle	要为横轴标题使用的文本样式。您可以通过调用 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);

参数

名称	类型	说明
start	Number	垂直轴最下方网格的值。
end	Number	垂直轴上最高网格线的值。

返回

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

参数

名称	类型	说明
textStyle	TextStyle	要为横轴标题使用的文本样式。您可以通过调用 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');

参数

名称	类型	说明
title	String	Y 轴的标题。

返回

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

参数

名称	类型	说明
textStyle	TextStyle	要为横轴标题使用的文本样式。您可以通过调用 Charts.newTextStyle() 来创建 TextStyleBuilder 对象。

返回

EmbeddedScatterChartBuilder - 此构建器适用于链接。