From 19186f0120134383e3744a8dc5da2bd62fb6d39c Mon Sep 17 00:00:00 2001 From: Adriano Konzen Date: Mon, 17 Aug 2026 08:50:29 -0300 Subject: [PATCH 1/2] docs(time): document time zone support --- en/api/echarts.md | 2 + en/api/time.md | 82 ++++++++++++++++++++++++++++++ en/option/component/axis-common.md | 42 ++++++++++++++- en/option/option.md | 18 +++++++ zh/api/echarts.md | 2 + zh/api/time.md | 82 ++++++++++++++++++++++++++++++ zh/option/component/axis-common.md | 41 +++++++++++++++ zh/option/option.md | 18 +++++++ 8 files changed, 286 insertions(+), 1 deletion(-) create mode 100644 en/api/time.md create mode 100644 zh/api/time.md diff --git a/en/api/echarts.md b/en/api/echarts.md index 6676c44dc..888885a30 100644 --- a/en/api/echarts.md +++ b/en/api/echarts.md @@ -354,4 +354,6 @@ Sets the platform-related API, which may need to be provided when non-browser pl + `loadImage` Load image, required when using Canvas rendering mode and using URLs as images. +{{ use: echarts-time }} + {{ use: echarts-graphic }} diff --git a/en/api/time.md b/en/api/time.md new file mode 100644 index 000000000..dc390eeea --- /dev/null +++ b/en/api/time.md @@ -0,0 +1,82 @@ +{{ target: echarts-time }} + +## time + +Utilities for parsing, formatting, and rounding temporal values. + +### parse(Function) + +```ts +(time: number|string|Date) => Date +``` + +Parses a timestamp, a `Date`, or a supported date string and returns a `Date`. + +Parsing is independent of the chart's [timeZone](option.html#timeZone). In particular, a string without an explicit offset is parsed in the current system time zone. Use a timestamp, a `Date`, or a string with an explicit offset when the input must identify the same instant in every environment. + +### format(Function) + +```ts +( + time: number|string|Date, + template: string, + timeZone: string, + lang?: string +) => string + +// Deprecated since v6.2.0: +( + time: number|string|Date, + template: string, + isUTC: boolean, + lang?: string +) => string +``` + +Formats a temporal value in an [IANA time zone](https://www.iana.org/time-zones), such as `'America/New_York'`, `'Asia/Shanghai'`, or `'UTC'`. + +{{ use: partial-version( + feature = 'The IANA time-zone overload is available', + version = "6.2.0" +) }} + +The supported templates are listed in [time axisLabel.formatter](option.html#xAxis.axisLabel.formatter). Since `v6.2.0`, `{Z}` formats the UTC offset without a padded hour (for example, `Z`, `-5`, or `+1:05`) and `{ZZ}` formats it with a padded hour (for example, `Z`, `-05:00`, or `+01:05`). + +Example: + +```ts +echarts.time.format( + Date.parse('2024-11-03T06:30:00Z'), + '{yyyy}-{MM}-{dd} {HH}:{mm} {ZZ}', + 'America/New_York' +); +// '2024-11-03 01:30 -05:00' +``` + +The boolean `isUTC` third parameter is deprecated since `v6.2.0`. The legacy `true` value selects UTC, while `false` selects the current system time zone. Pass `'UTC'` or an IANA time-zone string instead. + +### roundTime(Function) + +```ts +( + date: Date, + timeUnit: 'year'|'month'|'day'|'hour'|'minute'|'second'|'millisecond', + timeZone: string +) => Date + +// Deprecated since v6.2.0: +( + date: Date, + timeUnit: 'year'|'month'|'day'|'hour'|'minute'|'second'|'millisecond', + isUTC: boolean +) => Date +``` + +Rounds `date` down to the start of `timeUnit` in the given IANA time zone. The input `Date` is mutated and returned. + +{{ use: partial-version( + feature = 'The IANA time-zone overload is available', + version = "6.2.0" +) }} + +The boolean `isUTC` third parameter is deprecated since `v6.2.0`. The legacy `true` value selects UTC, while `false` selects the current system time zone. Pass `'UTC'` or an IANA time-zone string instead. diff --git a/en/option/component/axis-common.md b/en/option/component/axis-common.md index a7b41ad68..62bb554ed 100644 --- a/en/option/component/axis-common.md +++ b/en/option/component/axis-common.md @@ -819,6 +819,21 @@ Option: componentType = ${componentType} ) }} +#${prefix} timeZone(string) + +{{ use: partial-version(version = "6.2.0") }} + +The [IANA time zone](https://www.iana.org/time-zones) used to align ticks and format labels on this axis. It is available only when [type](~${componentType}.type) is `'time'`. + +For example: +```ts +timeZone: 'America/New_York' +``` + +If this option is not specified, the axis inherits the [global timeZone](${optionDocPath}#timeZone). An axis-level `timeZone` takes precedence over the global value. This effective time zone is also used for temporal values from this axis displayed in `tooltip`. + +This option does not change how input values are parsed. To identify an instant independently of the current system time zone, use a timestamp, a `Date`, or a string with an explicit offset. + {{ if: ${componentType} !== 'angleAxis' }} #${prefix} name(string) @@ -1318,9 +1333,16 @@ Using string templates is an easy way to format date/time with frequently used f | | {s} | 0-59 | 0-59 | | Millisecond | {SSS} | 000-999 | 000-999 | | | {S} | 0-999 | 0-999 | +| UTC Offset | {Z} | `Z`, `-5`, `-3:30`, `+1:05` | `Z`, `-5`, `-3:30`, `+1:05` | +| | {ZZ} | `Z`, `-05:00`, `-03:30`, `+01:05` | `Z`, `-05:00`, `-03:30`, `+01:05` | | Meridian | {A} | AM, PM (Since `v5.5.1`, i18n will be finished in the next version) | 上午、下午 (`v5.5.1` 仅支持英文，将在下个版本支持中文及其他语言) | | | {a} | am, pm | 上午、下午 | +{{ use: partial-version( + feature = '`{Z}` and `{ZZ}` UTC-offset templates are available', + version = "6.2.0" +) }} + > Templates of other languages can be found in [the language package](https://github.com/apache/echarts/tree/master/src/i18n). Please refer to [echarts.registerLocale](api.html#echarts.registerLocale) to register a language. Example: @@ -1358,6 +1380,25 @@ formatter: function (value, index) { } ``` +{{ use: partial-version( + version = "6.2.0", + deprecated = 'Pass a time-zone string as the third parameter of `echarts.time.format` instead of a boolean.' +) }} + +Since `v6.2.0`, the third parameter of `echarts.time.format` accepts an IANA time-zone string or `'UTC'`: + +```ts +formatter: function (value, index) { + // Follow the template rules above. + const timeZone = 'America/New_York'; + return echarts.time.format( + value, + '{yyyy}-{MM}-{dd} {HH}:{mm}:{ss} {ZZ}', + timeZone + ); +} +``` + ** Cascading Templates ** Sometimes, we wish to use different formats for different time granularity. For example, in a quarter-year chart, we may wish to see the month name with the first date of the month, while see the date name with others. This can be made with: @@ -1494,4 +1535,3 @@ Whether to show the tooltip. Defaults to `false`. {{ target: partial-axis-break-identifier-desc }} Note: [${componentType}.breaks.start](~${componentType}.breaks.start) and [${componentType}.breaks.end](~${componentType}.breaks.end) are the unique identifiers for each break item. When calling [chart.setOption](api.html#echartsInstance.setOption) to modify [${componentType}.breaks.gap](~${componentType}.breaks.gap) or [${componentType}.breaks.isExpanded](~${componentType}.breaks.isExpanded), `start` and `end` must be specified. Update animations will only occur if `start` and `end` are not modified; no animation will occur if they are changed. - diff --git a/en/option/option.md b/en/option/option.md index e9c8a5c6f..82e4e5067 100644 --- a/en/option/option.md +++ b/en/option/option.md @@ -150,8 +150,24 @@ The separate hover layer is used to avoid re-painting the whole canvas when hove ECharts 2 use separate layer for all cases. But it brings some problems like the hovered elements may not covering everything else correctly, or translucent elements may not overlay correctly to each other. And it brings extra member cost due to the extra canvas and may bring burden on mobile devices. So since ECharts 3, the hover layer is not used by default. Only when the element amount is large enough will the hover layer used. +# timeZone(string) + +{{ use: partial-version(version = "6.2.0") }} + +The [IANA time zone](https://www.iana.org/time-zones) used to calculate and display temporal values. For example, `'America/New_York'`, `'Asia/Shanghai'`, or `'UTC'`. + +When this option is not specified, ECharts uses the current browser or operating-system time zone. + +This option determines time-axis ticks, `axisLabel`, and `tooltip` formatting. A `timeZone` configured on a time axis overrides this global value for that axis. + +If `timeZone` and the deprecated [useUTC](~useUTC) are both specified, `timeZone` takes precedence. + +This setting affects time calculation and display, but does not change how input values are parsed. Strings without an explicit offset are still parsed in the current system time zone. Use a timestamp, a `Date`, or a string with an explicit offset when the input must identify the same instant in every environment. See [the time part in date](~series-line.data). + # useUTC(boolean) = false +{{ use: partial-version(version = "6.2.0", deprecated = 'Use [timeZone](~timeZone) instead.') }} + Whether to use UTC in display. + `true`: When `axis.type` is `'time'`, ticks is determined according to UTC, and `axisLabel` and `tooltip` use UTC by default. @@ -171,6 +187,8 @@ Notice: if you set `useUTC: true` and use the helper method `echarts.time.format const timeStrUTC = echarts.time.format(value, '{yyyy}-{MM}-{dd} {hh}:{mm}:{ss}', true); ``` +This option is retained for backward compatibility. `useUTC: true` is equivalent to `timeZone: 'UTC'`, while `useUTC: false` is equivalent to leaving `timeZone` unspecified and using the current browser or operating-system time zone. If `timeZone` is also specified, `timeZone` takes precedence. + {{import: partial-rich-inherit-plain-label}} # options(Array) diff --git a/zh/api/echarts.md b/zh/api/echarts.md index 54b449a91..37753ce39 100644 --- a/zh/api/echarts.md +++ b/zh/api/echarts.md @@ -354,4 +354,6 @@ chart.setOption(option); + `measureText` 测量文本宽度，默认会通过`createCanvas`得到 Canvas 元素提供的接口来测量文本宽度，也可以替换成更轻量的实现。 + `loadImage` 加载图片，在使用 Canvas 渲染模式的时候并且使用 URL 作为图片的时候需要提供。 +{{ use: echarts-time }} + {{ use: echarts-graphic }} diff --git a/zh/api/time.md b/zh/api/time.md new file mode 100644 index 000000000..e43c24656 --- /dev/null +++ b/zh/api/time.md @@ -0,0 +1,82 @@ +{{ target: echarts-time }} + +## time + +用于解析、格式化和舍入时间值的工具方法。 + +### parse(Function) + +```ts +(time: number|string|Date) => Date +``` + +解析时间戳、`Date` 或支持的日期字符串并返回 `Date`。 + +解析过程不受图表的 [timeZone](option.html#timeZone) 影响。特别是，没有显式偏移量的字符串按照当前系统时区解析。如果输入必须在所有环境中表示同一时刻，请使用时间戳、`Date` 或带有显式偏移量的字符串。 + +### format(Function) + +```ts +( + time: number|string|Date, + template: string, + timeZone: string, + lang?: string +) => string + +// 从 v6.2.0 起废弃： +( + time: number|string|Date, + template: string, + isUTC: boolean, + lang?: string +) => string +``` + +按照 [IANA 时区](https://www.iana.org/time-zones) 格式化时间值，例如 `'America/New_York'`、`'Asia/Shanghai'` 或 `'UTC'`。 + +{{ use: partial-version( + feature = '支持 IANA 时区重载', + version = "6.2.0" +) }} + +支持的模板参见[时间轴 axisLabel.formatter](option.html#xAxis.axisLabel.formatter)。从 `v6.2.0` 开始，`{Z}` 生成小时不补零的 UTC 偏移量（例如 `Z`、`-5` 或 `+1:05`），`{ZZ}` 生成小时补零的 UTC 偏移量（例如 `Z`、`-05:00` 或 `+01:05`）。 + +示例： + +```ts +echarts.time.format( + Date.parse('2024-11-03T06:30:00Z'), + '{yyyy}-{MM}-{dd} {HH}:{mm} {ZZ}', + 'America/New_York' +); +// '2024-11-03 01:30 -05:00' +``` + +第三个布尔参数 `isUTC` 从 `v6.2.0` 起废弃。旧值 `true` 选择 UTC，`false` 选择当前系统时区。请改传 `'UTC'` 或 IANA 时区字符串。 + +### roundTime(Function) + +```ts +( + date: Date, + timeUnit: 'year'|'month'|'day'|'hour'|'minute'|'second'|'millisecond', + timeZone: string +) => Date + +// 从 v6.2.0 起废弃： +( + date: Date, + timeUnit: 'year'|'month'|'day'|'hour'|'minute'|'second'|'millisecond', + isUTC: boolean +) => Date +``` + +按照给定 IANA 时区，将 `date` 向下舍入到 `timeUnit` 的起点。传入的 `Date` 会被修改并返回。 + +{{ use: partial-version( + feature = '支持 IANA 时区重载', + version = "6.2.0" +) }} + +第三个布尔参数 `isUTC` 从 `v6.2.0` 起废弃。旧值 `true` 选择 UTC，`false` 选择当前系统时区。请改传 `'UTC'` 或 IANA 时区字符串。 diff --git a/zh/option/component/axis-common.md b/zh/option/component/axis-common.md index cef78ec8d..372d40a3e 100644 --- a/zh/option/component/axis-common.md +++ b/zh/option/component/axis-common.md @@ -817,6 +817,21 @@ splitLine: { componentType = ${componentType} ) }} +#${prefix} timeZone(string) + +{{ use: partial-version(version = "6.2.0") }} + +用于对齐此坐标轴刻度和格式化标签的 [IANA 时区](https://www.iana.org/time-zones)。仅当 [type](~${componentType}.type) 为 `'time'` 时有效。 + +例如： +```ts +timeZone: 'America/New_York' +``` + +未指定此选项时，坐标轴继承[全局 timeZone](${optionDocPath}#timeZone)。坐标轴级的 `timeZone` 优先于全局值。`tooltip` 中来自此坐标轴的时间值也使用这个有效时区。 + +此选项不会改变输入值的解析方式。如果需要表示不受当前系统时区影响的确定时刻，请使用时间戳、`Date` 或带有显式偏移量的字符串。 + {{ if: ${componentType} !== 'angleAxis' }} #${prefix} name(string) @@ -1312,6 +1327,13 @@ formatter = function (value, index, extra: AxisLabelFormatterExtraBreakPart) { | | {s} | 0-59 | 0-59 | | Millisecond | {SSS} | 000-999 | 000-999 | | | {S} | 0-999 | 0-999 | +| UTC Offset | {Z} | `Z`、`-5`、`-3:30`、`+1:05` | `Z`、`-5`、`-3:30`、`+1:05` | +| | {ZZ} | `Z`、`-05:00`、`-03:30`、`+01:05` | `Z`、`-05:00`、`-03:30`、`+01:05` | + +{{ use: partial-version( + feature = '支持 `{Z}` 和 `{ZZ}` UTC 偏移量模板', + version = "6.2.0" +) }} > 其他语言请参考相应[语言包](https://github.com/apache/echarts/tree/master/src/i18n)中的定义，语言包可以通过 [echarts.registerLocale](api.html#echarts.registerLocale) 注册。 @@ -1349,6 +1371,25 @@ formatter: function (value, index) { } ``` +{{ use: partial-version( + version = "6.2.0", + deprecated = '请使用时区字符串作为 `echarts.time.format` 的第三个参数，不要再使用布尔值。' +) }} + +从 `v6.2.0` 开始，`echarts.time.format` 的第三个参数接受 IANA 时区字符串或 `'UTC'`： + +```ts +formatter: function (value, index) { + // 时间模版的规则如上描述。 + const timeZone = 'America/New_York'; + return echarts.time.format( + value, + '{yyyy}-{MM}-{dd} {HH}:{mm}:{ss} {ZZ}', + timeZone + ); +} +``` + ** 分级模板 ** 有时候，我们希望对不同的时间粒度采用不同的格式化策略。例如，在季度图表中，我们可能希望对每个月的第一天显示月份，而其他日期显示日期。我们可以使用以下方式实现该效果： diff --git a/zh/option/option.md b/zh/option/option.md index f62e32c60..b791bec29 100644 --- a/zh/option/option.md +++ b/zh/option/option.md @@ -150,8 +150,24 @@ ECharts 2 里是底层强制使用单独的层绘制高亮图形，但是会带来很多问题，比如高亮的图形可能会不正确的遮挡所有其它图形，还有图形有透明度因为高亮和正常图形叠加导致不正确的透明度显示，还有移动端上因为每个图表都要多一个 canvas 带来的额外内存开销。因此 3 里默认不会开启该优化，只有在图形数量特别多，有必要做该优化时才会自动开启。 +# timeZone(string) + +{{ use: partial-version(version = "6.2.0") }} + +用于计算和显示时间值的 [IANA 时区](https://www.iana.org/time-zones)，例如 `'America/New_York'`、`'Asia/Shanghai'` 或 `'UTC'`。 + +未指定此选项时，ECharts 使用当前浏览器或操作系统的时区。 + +此选项决定时间轴刻度、`axisLabel` 和 `tooltip` 的格式。时间轴上配置的 `timeZone` 会覆盖此全局值。 + +如果同时指定 `timeZone` 和已废弃的 [useUTC](~useUTC)，以 `timeZone` 为准。 + +此设置影响时间的计算和显示，但不会改变输入值的解析方式。没有显式偏移量的字符串仍按照当前系统时区解析。如果输入必须在所有环境中表示同一时刻，请使用时间戳、`Date` 或带有显式偏移量的字符串。参见 [date 中时间相关部分](~series-line.data)。 + # useUTC(boolean) = false +{{ use: partial-version(version = "6.2.0", deprecated = '请改用 [timeZone](~timeZone)。') }} + 是否使用 UTC 时间。 + `true`: 表示 `axis.type` 为 `'time'` 时，依据 UTC 时间确定 tick 位置，并且 `axisLabel` 和 `tooltip` 默认展示的是 UTC 时间。 @@ -171,6 +187,8 @@ ECharts 2 里是底层强制使用单独的层绘制高亮图形，但是会带 const timeStrUTC = echarts.time.format(value, '{yyyy}-{MM}-{dd} {hh}:{mm}:{ss}', true); ``` +保留此选项是为了向后兼容。`useUTC: true` 等同于 `timeZone: 'UTC'`，而 `useUTC: false` 等同于不指定 `timeZone`，即使用当前浏览器或操作系统的时区。如果同时指定 `timeZone`，以 `timeZone` 为准。 + {{import: partial-rich-inherit-plain-label }} From ddaa1ec1d44e7906289230ef0195dacfb35d260f Mon Sep 17 00:00:00 2001 From: Adriano Konzen Date: Tue, 18 Aug 2026 16:47:01 -0300 Subject: [PATCH 2/2] docs(time): clarify UTC offset examples --- en/api/time.md | 2 +- en/option/component/axis-common.md | 4 ++-- zh/api/time.md | 2 +- zh/option/component/axis-common.md | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/en/api/time.md b/en/api/time.md index dc390eeea..1c16b64ec 100644 --- a/en/api/time.md +++ b/en/api/time.md @@ -40,7 +40,7 @@ Formats a temporal value in an [IANA time zone](https://www.iana.org/time-zones) version = "6.2.0" ) }} -The supported templates are listed in [time axisLabel.formatter](option.html#xAxis.axisLabel.formatter). Since `v6.2.0`, `{Z}` formats the UTC offset without a padded hour (for example, `Z`, `-5`, or `+1:05`) and `{ZZ}` formats it with a padded hour (for example, `Z`, `-05:00`, or `+01:05`). +The supported templates are listed in [time axisLabel.formatter](option.html#xAxis.axisLabel.formatter). Since `v6.2.0`, `{Z}` formats the UTC offset without a padded hour (for example, `Z`, `+0`, `-5`, or `+1:05`) and `{ZZ}` formats it with a padded hour (for example, `Z`, `+00:00`, `-05:00`, or `+01:05`). Example: diff --git a/en/option/component/axis-common.md b/en/option/component/axis-common.md index 62bb554ed..e8c9ab300 100644 --- a/en/option/component/axis-common.md +++ b/en/option/component/axis-common.md @@ -1333,8 +1333,8 @@ Using string templates is an easy way to format date/time with frequently used f | | {s} | 0-59 | 0-59 | | Millisecond | {SSS} | 000-999 | 000-999 | | | {S} | 0-999 | 0-999 | -| UTC Offset | {Z} | `Z`, `-5`, `-3:30`, `+1:05` | `Z`, `-5`, `-3:30`, `+1:05` | -| | {ZZ} | `Z`, `-05:00`, `-03:30`, `+01:05` | `Z`, `-05:00`, `-03:30`, `+01:05` | +| UTC Offset | {Z} | `Z`, `+0`, `-5`, `-3:30`, `+1:05` | `Z`, `+0`, `-5`, `-3:30`, `+1:05` | +| | {ZZ} | `Z`, `+00:00`, `-05:00`, `-03:30`, `+01:05` | `Z`, `+00:00`, `-05:00`, `-03:30`, `+01:05` | | Meridian | {A} | AM, PM (Since `v5.5.1`, i18n will be finished in the next version) | 上午、下午 (`v5.5.1` 仅支持英文，将在下个版本支持中文及其他语言) | | | {a} | am, pm | 上午、下午 | diff --git a/zh/api/time.md b/zh/api/time.md index e43c24656..2957a00a8 100644 --- a/zh/api/time.md +++ b/zh/api/time.md @@ -40,7 +40,7 @@ version = "6.2.0" ) }} -支持的模板参见[时间轴 axisLabel.formatter](option.html#xAxis.axisLabel.formatter)。从 `v6.2.0` 开始，`{Z}` 生成小时不补零的 UTC 偏移量（例如 `Z`、`-5` 或 `+1:05`），`{ZZ}` 生成小时补零的 UTC 偏移量（例如 `Z`、`-05:00` 或 `+01:05`）。 +支持的模板参见[时间轴 axisLabel.formatter](option.html#xAxis.axisLabel.formatter)。从 `v6.2.0` 开始，`{Z}` 生成小时不补零的 UTC 偏移量（例如 `Z`、`+0`、`-5` 或 `+1:05`），`{ZZ}` 生成小时补零的 UTC 偏移量（例如 `Z`、`+00:00`、`-05:00` 或 `+01:05`）。 示例： diff --git a/zh/option/component/axis-common.md b/zh/option/component/axis-common.md index 372d40a3e..7ff4a11e7 100644 --- a/zh/option/component/axis-common.md +++ b/zh/option/component/axis-common.md @@ -1327,8 +1327,8 @@ formatter = function (value, index, extra: AxisLabelFormatterExtraBreakPart) { | | {s} | 0-59 | 0-59 | | Millisecond | {SSS} | 000-999 | 000-999 | | | {S} | 0-999 | 0-999 | -| UTC Offset | {Z} | `Z`、`-5`、`-3:30`、`+1:05` | `Z`、`-5`、`-3:30`、`+1:05` | -| | {ZZ} | `Z`、`-05:00`、`-03:30`、`+01:05` | `Z`、`-05:00`、`-03:30`、`+01:05` | +| UTC Offset | {Z} | `Z`、`+0`、`-5`、`-3:30`、`+1:05` | `Z`、`+0`、`-5`、`-3:30`、`+1:05` | +| | {ZZ} | `Z`、`+00:00`、`-05:00`、`-03:30`、`+01:05` | `Z`、`+00:00`、`-05:00`、`-03:30`、`+01:05` | {{ use: partial-version( feature = '支持 `{Z}` 和 `{ZZ}` UTC 偏移量模板',