颜色
表示 RGBA 颜色空间中的一种颜色。此表示方式旨在简化与各种颜色表示形式之间的相互转换,而不使用紧凑格式。例如,在 Java 中,可以向 java.awt.Color
的构造函数简单地提供该表示法的字段;而在 iOS 中,也可轻松地将其提供给 UIColor 的 +colorWithRed:green:blue:alpha
方法;只需编写少量工作,即可轻松地在 JavaScript 中将 CSS 格式设置为 CSS rgba()
字符串。
参考页面没有关于应该解释 RGB 值的绝对颜色空间的信息,例如 sRGB、Adobe RGB、DCI-P3 和 BT.2020。默认情况下,应用应假定采用 sRGB 颜色空间。
当需要确定颜色相等性时,除非另行说明,否则实现方式应将两种颜色视为相同,即它们的所有红色、绿色、蓝色和 alpha 值差异不超过 1e-5
。
示例 (Java):
import com.google.type.Color;
// ...
public static java.awt.Color fromProto(Color protocolor) {
float alpha = protocolor.hasAlpha()
? protocolor.getAlpha().getValue()
: 1.0;
return new java.awt.Color(
protocolor.getRed(),
protocolor.getGreen(),
protocolor.getBlue(),
alpha);
}
public static Color toProto(java.awt.Color color) {
float red = (float) color.getRed();
float green = (float) color.getGreen();
float blue = (float) color.getBlue();
float denominator = 255.0;
Color.Builder resultBuilder =
Color
.newBuilder()
.setRed(red / denominator)
.setGreen(green / denominator)
.setBlue(blue / denominator);
int alpha = color.getAlpha();
if (alpha != 255) {
result.setAlpha(
FloatValue
.newBuilder()
.setValue(((float) alpha) / denominator)
.build());
}
return resultBuilder.build();
}
// ...
示例 (iOS / Obj-C):
// ...
static UIColor* fromProto(Color* protocolor) {
float red = [protocolor red];
float green = [protocolor green];
float blue = [protocolor blue];
FloatValue* alpha_wrapper = [protocolor alpha];
float alpha = 1.0;
if (alpha_wrapper != nil) {
alpha = [alpha_wrapper value];
}
return [UIColor colorWithRed:red green:green blue:blue alpha:alpha];
}
static Color* toProto(UIColor* color) {
CGFloat red, green, blue, alpha;
if (![color getRed:&red green:&green blue:&blue alpha:&alpha]) {
return nil;
}
Color* result = [[Color alloc] init];
[result setRed:red];
[result setGreen:green];
[result setBlue:blue];
if (alpha <= 0.9999) {
[result setAlpha:floatWrapperWithValue(alpha)];
}
[result autorelease];
return result;
}
// ...
示例 (JavaScript):
// ...
var protoToCssColor = function(rgbColor) {
var redFrac = rgbColor.red || 0.0;
var greenFrac = rgbColor.green || 0.0;
var blueFrac = rgbColor.blue || 0.0;
var red = Math.floor(redFrac * 255);
var green = Math.floor(greenFrac * 255);
var blue = Math.floor(blueFrac * 255);
if (!('alpha' in rgbColor)) {
return rgbToCssColor(red, green, blue);
}
var alphaFrac = rgbColor.alpha.value || 0.0;
var rgbParams = [red, green, blue].join(',');
return ['rgba(', rgbParams, ',', alphaFrac, ')'].join('');
};
var rgbToCssColor = function(red, green, blue) {
var rgbNumber = new Number((red << 16) | (green << 8) | blue);
var hexString = rgbNumber.toString(16);
var missingZeros = 6 - hexString.length;
var resultBuilder = ['#'];
for (var i = 0; i < missingZeros; i++) {
resultBuilder.push('0');
}
resultBuilder.push(hexString);
return resultBuilder.join('');
};
// ...
JSON 表示法 |
---|
{ "red": number, "green": number, "blue": number, "alpha": number } |
字段 | |
---|---|
red
|
颜色中以红色表示的值,范围为 [0, 1]。 |
green
|
颜色中的绿色量(以 [0, 1] 为间隔的值)。 |
blue
|
颜色中蓝色的量,以区间 [0, 1] 为单位。 |
alpha
|
此颜色在像素中的应用比例。也就是说,最终像素颜色由以下公式定义:
也就是说,值为 1.0 表示纯色,而值为 0.0 表示完全透明的颜色。它会使用封装容器消息,而非简单的浮动标量,以便区分默认值和未设置的值。如果省略,此颜色对象将以纯色呈现(就好像 alpha 值已被明确设为 1.0 一样)。 |
ColorStyle
颜色值。
JSON 表示法 |
---|
{ // Union field |
字段 | |
---|---|
联合字段 kind 。颜色值的类型。
kind 只能是下列其中一项:
|
|
rgbColor
|
|
themeColor
|
主题颜色。 |
ThemeColorType
主题颜色类型。
SpreadsheetProperties
包含一个 SpreadsheetTheme
,用于定义这些主题颜色类型与具体颜色的映射。
枚举 | |
---|---|
THEME_COLOR_TYPE_UNSPECIFIED
|
未指定的主题颜色 |
TEXT
|
表示主要文本颜色 |
BACKGROUND
|
表示主要背景颜色 |
ACCENT1
|
表示第一种强调色 |
ACCENT2
|
表示第二种强调色 |
ACCENT3
|
表示第三个强调色 |
ACCENT4
|
表示第四种强调色 |
ACCENT5
|
代表第五个强调色 |
ACCENT6
|
代表第六种强调色 |
LINK
|
表示用于超链接的颜色 |
HorizontalAlign
单元格中的文本水平对齐方式。
枚举 | |
---|---|
HORIZONTAL_ALIGN_UNSPECIFIED
|
未指定水平对齐。请勿使用此参数。 |
LEFT
|
文本与单元格左侧明确对齐。 |
CENTER
|
文本与单元格中心明确对齐。 |
RIGHT
|
文本与单元格右侧明确对齐。 |
文本格式
单元格中连续文本的格式。缺少值表示未指定该字段。
JSON 表示法 |
---|
{ "foregroundColor": { object ( |
字段 | |
---|---|
foregroundColor
|
文本的前景颜色。已弃用:使用 |
foregroundColorStyle
|
文本的前景颜色。如果也设置了 |
fontFamily
|
字体系列。 |
fontSize
|
字体大小。 |
bold
|
如果文本为粗体,则返回 true。 |
italic
|
如果文本为斜体,则为 true。 |
strikethrough
|
如果文本有删除线,则为 true。 |
underline
|
如果文本带下划线,则为 true。 |
link
|
文本的链接目的地(如果有)。在 |
链接
外部或本地引用。
JSON 表示法 |
---|
{ // Union field |
字段 | |
---|---|
联合字段 destination 。链接目的地。
destination 只能是下列其中一项:
|
|
uri
|
链接标识符。 |
DataSourceColumn
数据源中的列。
JSON 表示法 |
---|
{
"reference": {
object (
|
字段 | |
---|---|
reference
|
列引用。 |
formula
|
计算列的公式。 |
DataSourceColumnReference
引用数据源列的唯一标识符。
JSON 表示法 |
---|
{ "name": string } |
字段 | |
---|---|
name
|
列的显示名。它在数据源中应该是唯一的。 |
DataExecutionStatus
数据执行状态。
创建数据执行请求,将数据源对象与 DataSource
中的最新数据进行同步。作业通常安排为在后台运行,您可以查看其 state
以了解执行是否已完成
以下几种情况会触发数据执行:
-
Adding a data source
会创建关联的数据源工作表,以及数据执行作业,将数据从数据源同步到工作表。 -
Updating a data source
会创建数据执行作业,以便同样刷新关联的数据源工作表。 -
您可以发送
refresh request
来明确刷新一个或多个数据源对象。
JSON 表示法 |
---|
{ "state": enum ( |
字段 | |
---|---|
state
|
数据执行的状态。 |
errorCode
|
错误代码。 |
errorMessage
|
错误消息,可能为空。 |
lastRefreshTime
|
获取上次成功刷新数据的时间。 |
DataExecutionState
数据执行状态的枚举。
枚举 | |
---|---|
DATA_EXECUTION_STATE_UNSPECIFIED
|
默认值,请勿使用。 |
NOT_STARTED
|
数据执行操作尚未开始。 |
RUNNING
|
数据开始和正在运行。 |
SUCCEEDED
|
数据执行已成功完成。 |
FAILED
|
数据执行已完成,但有错误。 |
DataExecutionErrorCode
数据执行错误代码的枚举。
枚举 | |
---|---|
DATA_EXECUTION_ERROR_CODE_UNSPECIFIED
|
默认值,请勿使用。 |
TIMED_OUT
|
数据执行超时。 |
TOO_MANY_ROWS
|
数据执行返回的行数超出上限。 |
TOO_MANY_COLUMNS
|
数据执行返回的列数超出了上限。 |
TOO_MANY_CELLS
|
数据执行返回的单元格数量超出限制。 |
ENGINE
|
从后端数据执行引擎(如 BigQuery)收到错误。如需了解详情,请查看 errorMessage 。
|
PARAMETER_INVALID
|
提供的一个或多个数据源参数无效。 |
UNSUPPORTED_DATA_TYPE
|
数据执行返回不受支持的数据类型。 |
DUPLICATE_COLUMN_NAMES
|
数据执行结果会返回重复的列名称或别名。 |
INTERRUPTED
|
数据执行中断。请稍后刷新。 |
CONCURRENT_QUERY
|
数据执行操作目前正在进行,在完成之前无法刷新。 |
OTHER
|
其他错误。 |
TOO_MANY_CHARS_PER_CELL
|
数据执行返回的值超出单个单元格允许的字符数上限。 |
DATA_NOT_FOUND
|
未找到数据源引用的数据库。*/ |
PERMISSION_DENIED
|
用户无权访问数据源引用的数据库。 |
MISSING_COLUMN_ALIAS
|
数据执行结果返回缺少别名的列。 |
OBJECT_NOT_FOUND
|
数据源对象不存在。 |
OBJECT_IN_ERROR_STATE
|
数据源对象当前处于错误状态。如需强制刷新,请在 RefreshDataSourceRequest 中设置 force 。
|
OBJECT_SPEC_INVALID
|
数据源对象规范无效。 |
扩展值
电子表格中单元格可包含的值的类型。
JSON 表示法 |
---|
{ // Union field |
字段 | |
---|---|
联合字段 value 。单元格中的值类型。如果未设置任何字段,则单元格内没有数据。
value 只能是下列其中一项:
|
|
numberValue
|
表示双精度值。注意:日期、时间和日期采用 |
stringValue
|
表示字符串值。不包括前导单引号。例如,如果用户在界面中输入了 |
boolValue
|
表示布尔值。 |
formulaValue
|
表示公式。 |
errorValue
|
表示错误。此字段是只读字段。 |
错误值
单元格出错。
JSON 表示法 |
---|
{
"type": enum (
|
字段 | |
---|---|
type
|
错误的类型。 |
message
|
(有关电子表格的语言区域)错误详情的消息。 |
错误类型
错误的类型。
枚举 | |
---|---|
ERROR_TYPE_UNSPECIFIED
|
默认错误类型,请勿使用。 |
ERROR
|
对应于 #ERROR! 错误。
|
NULL_VALUE
|
对应于 #NULL! 错误。
|
DIVIDE_BY_ZERO
|
对应于 #DIV/0 错误。
|
VALUE
|
对应于 #VALUE! 错误。
|
REF
|
对应于 #REF! 错误。
|
NAME
|
对应于 #NAME? 错误。
|
NUM
|
对应于 #NUM! 错误。
|
N_A
|
对应于 #N/A 错误。
|
LOADING
|
对应于 Loading... 状态。
|
布尔值条件
评估结果为 true 或 false 的条件。布尔值条件用于条件格式设置、数据验证以及过滤器中的条件。
JSON 表示法 |
---|
{ "type": enum ( |
字段 | |
---|---|
type
|
条件的类型。 |
values[]
|
条件的值。支持的值数量取决于 |
条件类型
条件的类型。
枚举 | |
---|---|
CONDITION_TYPE_UNSPECIFIED
|
默认值,请勿使用。 |
NUMBER_GREATER
|
单元格的值必须大于条件的值。由数据验证、条件格式和过滤器提供支持。需要单个 ConditionValue 。
|
NUMBER_GREATER_THAN_EQ
|
单元格的值必须大于或等于条件的值。由数据验证、条件格式和过滤器提供支持。需要单个 ConditionValue 。
|
NUMBER_LESS
|
单元格的值必须小于条件的值。由数据验证、条件格式和过滤器提供支持。需要单个 ConditionValue 。
|
NUMBER_LESS_THAN_EQ
|
单元格的值必须小于或等于条件的值。由数据验证、条件格式和过滤器提供支持。需要单个 ConditionValue 。
|
NUMBER_EQ
|
单元格的值必须等于条件的值。由数据验证、条件格式和过滤器提供支持。需要单个 ConditionValue (用于数据验证)、条件格式设置以及针对非数据源对象的过滤条件,以及至少一个 ConditionValue (用于数据源对象的过滤条件)。 |
NUMBER_NOT_EQ
|
单元格的值不得等于条件的值。由数据验证、条件格式和过滤器提供支持。需要单个 ConditionValue (用于数据验证)、条件格式设置以及针对非数据源对象的过滤条件,以及至少一个 ConditionValue (用于数据源对象的过滤条件)。 |
NUMBER_BETWEEN
|
单元格中的值必须介于两个条件值之间。由数据验证、条件格式和过滤器提供支持。只需要两个 ConditionValues 。
|
NUMBER_NOT_BETWEEN
|
单元格的值不得介于两个条件值之间。由数据验证、条件格式和过滤器提供支持。只需要两个 ConditionValues 。
|
TEXT_CONTAINS
|
单元格的值必须包含条件的值。由数据验证、条件格式和过滤器提供支持。需要单个 ConditionValue 。
|
TEXT_NOT_CONTAINS
|
单元格的值不得包含条件值。由数据验证、条件格式和过滤器提供支持。需要单个 ConditionValue 。
|
TEXT_STARTS_WITH
|
单元格的值必须以条件值开头。支持的条件格式和过滤条件。需要单个 ConditionValue 。
|
TEXT_ENDS_WITH
|
单元格的值必须以条件值结尾。支持的条件格式和过滤条件。需要单个 ConditionValue 。
|
TEXT_EQ
|
单元格中的值必须与条件的值完全一致。由数据验证、条件格式和过滤器提供支持。需要单个 ConditionValue (用于数据验证)、条件格式设置以及针对非数据源对象的过滤条件,以及至少一个 ConditionValue (用于数据源对象的过滤条件)。 |
TEXT_IS_EMAIL
|
单元格中的值必须是有效的电子邮件地址。由数据验证支持。不需要 ConditionValues 。
|
TEXT_IS_URL
|
单元格中的值必须是有效网址。由数据验证支持。不需要 ConditionValues 。
|
DATE_EQ
|
单元格的值必须与条件的值相同。由数据验证、条件格式和过滤器提供支持。需要单个 ConditionValue (用于数据验证)、条件格式设置以及针对非数据源对象的过滤条件,以及至少一个 ConditionValue (用于数据源对象的过滤条件)。 |
DATE_BEFORE
|
单元格的值必须早于条件值的日期。由数据验证、条件格式和过滤器提供支持。需要一个可能为 relative date 的 ConditionValue 。 |
DATE_AFTER
|
单元格的值必须晚于条件值的日期。由数据验证、条件格式和过滤器提供支持。需要一个可能为 relative date 的 ConditionValue 。 |
DATE_ON_OR_BEFORE
|
单元格的值不能晚于条件值的日期,由数据验证支持。需要一个可能为 relative date 的 ConditionValue 。 |
DATE_ON_OR_AFTER
|
单元格的值不能晚于条件的值日期。由数据验证支持。需要一个可能为 relative date 的 ConditionValue 。 |
DATE_BETWEEN
|
单元格的值必须介于两个条件值之间。由数据验证支持。只需要两个 ConditionValues 。
|
DATE_NOT_BETWEEN
|
单元格的值必须在两个条件值的日期之外。由数据验证支持。只需要两个 ConditionValues 。
|
DATE_IS_VALID
|
单元格中的值必须是日期。由数据验证支持。不需要 ConditionValues 。
|
ONE_OF_RANGE
|
单元格中的值必须在条件值范围内的网格中列出。由数据验证支持。需要单个 ConditionValue ,并且值必须是采用 A1 表示法的有效范围。
|
ONE_OF_LIST
|
单元格中的值必须位于条件值列表中。由数据验证支持。支持任意数量的 condition values ,列表中的每个项一个。不支持在公式中使用公式。
|
BLANK
|
单元格的值必须为空。支持的条件格式和过滤条件。不需要 ConditionValues 。
|
NOT_BLANK
|
单元格的值不能为空。支持的条件格式和过滤条件。不需要 ConditionValues 。
|
CUSTOM_FORMULA
|
条件的公式必须评估为 true。由数据验证、条件格式和过滤器提供支持。数据源工作表过滤条件不受支持。需要单个 ConditionValue 。
|
BOOLEAN
|
单元格中的值必须是 TRUE/FALSE 或在条件值列表中。由数据验证支持。呈现为单元格复选框。支持零个、一个或两个 ConditionValues 。没有值表示单元格必须为 TRUE 或 FALSE,其中 TRUE 渲染为勾选,FALSE 渲染为未勾选。有 1 个值表示单元格将包含该值时显示为已勾选,并在单元格为空白时取消选中。有两个值表示单元格包含第一个值时会显示为已勾选,当包含第二个值时则会取消选中。例如,["Yes","No"] 表示单元格会在值为“Yes”时呈现勾选框,在值为“No”时呈现未选中的框。
|
TEXT_NOT_EQ
|
单元格的值不能与条件值完全一致。受数据源对象的过滤条件支持。至少需要一个 ConditionValue 。
|
DATE_NOT_EQ
|
单元格的值不能与条件值完全一致。受数据源对象的过滤条件支持。至少需要一个 ConditionValue 。
|
FILTER_EXPRESSION
|
单元格中的值必须遵循指定的模式。需要单个 ConditionValue 。
|
条件值
条件的值。
JSON 表示法 |
---|
{ // Union field |
字段 | |
---|---|
联合字段 value 。条件的值,且只能设置一个。
value 只能是下列其中一项:
|
|
relativeDate
|
相对日期(基于当前日期)。仅当 数据验证不支持相对日期。仅在条件格式和条件过滤器中使用。 |
userEnteredValue
|
条件所基于的值。系统会像在单元格中输入那样解析该值。公式受支持(必须以 |
相对日期
控制日期条件的评估方式。
枚举 | |
---|---|
RELATIVE_DATE_UNSPECIFIED
|
默认值,请勿使用。 |
PAST_YEAR
|
该值为一年前的今天。 |
PAST_MONTH
|
该值为一个月前。 |
PAST_WEEK
|
该值为一周之前。 |
YESTERDAY
|
值为昨天。 |
TODAY
|
值为今天。 |
TOMORROW
|
值为明天。 |
GridRange
工作表中的范围。所有索引都是从零开始的。索引为半开,即起始索引包含边界值,而结束索引不包含边界值 [startIndex, endIndex)。缺少索引表示该端没有范围。
例如,如果 "Sheet1"
为工作表 ID 123456,则:
Sheet1!A1:A1 == sheetId: 123456,
startRowIndex: 0, endRowIndex: 1,
startColumnIndex: 0, endColumnIndex: 1
Sheet1!A3:B4 == sheetId: 123456,
startRowIndex: 2, endRowIndex: 4,
startColumnIndex: 0, endColumnIndex: 2
Sheet1!A:B == sheetId: 123456,
startColumnIndex: 0, endColumnIndex: 2
Sheet1!A5:B == sheetId: 123456,
startRowIndex: 4,
startColumnIndex: 0, endColumnIndex: 2
Sheet1 == sheetId: 123456
起始索引必须始终小于或等于结束索引。如果起始索引等于结束索引,则范围为空。空范围通常毫无意义,通常以 #REF!
的形式在界面中呈现。
JSON 表示法 |
---|
{ "sheetId": integer, "startRowIndex": integer, "endRowIndex": integer, "startColumnIndex": integer, "endColumnIndex": integer } |
字段 | |
---|---|
sheetId
|
此范围所在的工作表。 |
startRowIndex
|
范围的起始行(含该行),如果未设置界限,则不设置。 |
endRowIndex
|
范围的结束行(不含边界值),如果未设置界限,则不设置。 |
startColumnIndex
|
范围的起始列(含),如果没有设置,则不设置。 |
endColumnIndex
|
范围的结束列(不含边界值),如果无界限,则不设置。 |
排序顺序
排列顺序。
枚举 | |
---|---|
SORT_ORDER_UNSPECIFIED
|
默认值,请勿使用该值。 |
ASCENDING
|
升序排序。 |
DESCENDING
|
降序排序。 |
FilterSpec
与特定列关联的过滤条件。
JSON 表示法 |
---|
{ "filterCriteria": { object ( |
字段 | |
---|---|
filterCriteria
|
列的条件。 |
联合字段 reference 。对被过滤列的引用。
reference 只能是下列其中一项:
|
|
columnIndex
|
从零开始的列索引。 |
dataSourceColumnReference
|
对数据源列的引用。 |
过滤条件
在过滤条件或过滤视图中显示/隐藏行的条件。
JSON 表示法 |
---|
{ "hiddenValues": [ string ], "condition": { object ( |
字段 | |
---|---|
condition
|
某个值必须是 true,才会显示值。(这不会替换 |
visibleBackgroundColor
|
作为过滤条件的背景填充颜色;仅显示具有此填充颜色的单元格。它与 |
visibleBackgroundColorStyle
|
作为过滤条件的背景填充颜色;仅显示具有此填充颜色的单元格。此字段与 |
visibleForegroundColor
|
要过滤的前景颜色;仅显示具有此前景颜色的单元格。它与 |
visibleForegroundColorStyle
|
要过滤的前景颜色;仅显示具有此前景颜色的单元格。此字段与 |
排序规范
与特定列或行关联的排序顺序。
JSON 表示法 |
---|
{ "sortOrder": enum ( |
字段 | |
---|---|
sortOrder
|
订单数据应进行排序。 |
foregroundColor
|
按颜色排序的前景颜色;包含前景颜色的单元格会按顶部排序。它与 |
foregroundColorStyle
|
按颜色排序的前景颜色;包含前景颜色的单元格会按顶部排序。与 |
backgroundColor
|
作为背景填充颜色的排序依据;采用此填充颜色的单元格会按顶部排序。它与 |
backgroundColorStyle
|
作为背景填充颜色的排序依据;采用此填充颜色的单元格会按顶部排序。与 |
联合字段 reference 。对排序维度的引用。reference 只能是下列其中一项:
|
|
dimensionIndex
|
排序应应用的维度。 |
dataSourceColumnReference
|
对数据源列的引用。 |
嵌入式对象位置
嵌入式对象(例如图表)的位置。
JSON 表示法 |
---|
{ // Union field |
字段 | |
---|---|
联合字段 location 。对象的位置。只能设置一个值。location 只能是下列其中一项:
|
|
sheetId
|
工作表所在的工作表。仅当嵌套的对象位于自己的工作表中时设置。必须为非负数。 |
overlayPosition
|
对象在网格上叠加的位置。 |
newSheet
|
如果为 true,嵌入的对象会放入为您选择 ID 的新工作表中。仅在写入时使用。 |
OverlayPosition
某个对象在网格上叠加放置的位置。
JSON 表示法 |
---|
{
"anchorCell": {
object (
|
字段 | |
---|---|
anchorCell
|
对象锚定的单元格。 |
offsetXPixels
|
对象相对于锚点单元格的水平偏移量(以像素为单位)。 |
offsetYPixels
|
对象相对于锚点单元格的垂直偏移量(以像素为单位)。 |
widthPixels
|
对象的宽度(以像素为单位)。默认为 600。 |
heightPixels
|
对象的高度(以像素为单位)。默认值为 371。 |
GridCoordinate
工作表中的坐标。所有索引都是从零开始的。
JSON 表示法 |
---|
{ "sheetId": integer, "rowIndex": integer, "columnIndex": integer } |
字段 | |
---|---|
sheetId
|
此坐标所在工作表。 |
rowIndex
|
坐标的行索引。 |
columnIndex
|
坐标的列索引。 |