You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@echarts.apache.org by ov...@apache.org on 2025/08/19 08:48:44 UTC
(echarts-doc) 02/03: doc: add doc for break axis apache/echarts#19459
This is an automated email from the ASF dual-hosted git repository.
ovilia pushed a commit to branch feat-break
in repository https://gitbox.apache.org/repos/asf/echarts-doc.git
commit be700aa5386c2d3e7414de9bb61e988df19e05a8
Author: Ovilia <zw...@gmail.com>
AuthorDate: Tue Aug 19 16:48:06 2025 +0800
doc: add doc for break axis apache/echarts#19459
---
en/option/component/axis-common.md | 110 +++++++++++++++++++++++++++++++++++-
en/option/component/x-axis.md | 3 +-
en/option/component/y-axis.md | 3 +-
zh/option/component/axis-common.md | 112 ++++++++++++++++++++++++++++++++++++-
zh/option/component/x-axis.md | 3 +-
zh/option/component/y-axis.md | 3 +-
6 files changed, 228 insertions(+), 6 deletions(-)
diff --git a/en/option/component/axis-common.md b/en/option/component/axis-common.md
index ddcaf154..63df07be 100644
--- a/en/option/component/axis-common.md
+++ b/en/option/component/axis-common.md
@@ -49,6 +49,113 @@ Whether allow overlaping with [jitter](~${componentType}.jitter). If `false`, it
When setting [jitter](~${componentType}.jitter) and [jitterOverlap](~${componentType}.jitterOverlap) is `false`, the minimum distance between two scatters.
{{ /if }}
+
+
+{{ if: ${hasBreakAxis|default(false)} }}
+#${prefix} breaks(Array)
+
+Break axis data, where each sub-element represents a segment of truncated space.
+
+~[800x400](${galleryViewPath}intraday-breaks-2&edit=1&reset=1)
+
+> Break axis is a technique that truncates portions of the coordinate axis to compress the display space of non-critical data segments in charts. Its core purposes are:
+>
+> + **Highlight differences**: When there are extreme differences between data values (such as one value being much larger than others), it prevents large value bars from overwhelmingly occupying space, making small value differences difficult to distinguish.
+> + **Save space**: Reduces blank areas caused by extreme values, making charts more compact.
+>
+> Please note that break axis should only be used when necessary to avoid misleading users. When using break axis, the truncated parts and corresponding values should usually be clearly indicated.
+>
+> Break axis cannot be used in category axes ([type](~${componentType}.type): `'category'`).
+
+##${prefix} start(string|number|Date)
+
+The start value for truncation.
+
++ For coordinate axes with [type](~${componentType}.type) as `'value'` or `'log'`, use `number` type values
++ For coordinate axes with [type](~${componentType}.type) as `'time'`:
+ + `string` type time values (e.g., `'2024-04-09 13:00:00'`)
+ + `number` type timestamps (e.g., `(new Date('2024-04-09 13:00:00')).getTime()`)
+ + `Date` type time objects (e.g., `new Date('2024-04-09 13:00:00')`).
+
+##${prefix} end(string|number|Date)
+
+The end value for truncation.
+
++ For coordinate axes with [type](~${componentType}.type) as `'value'` or `'log'`, use `number` type values
++ For coordinate axes with [type](~${componentType}.type) as `'time'`:
+ + `string` type time values (e.g., `'2024-04-09 13:00:00'`)
+ + `number` type timestamps (e.g., `(new Date('2024-04-09 13:00:00')).getTime()`)
+ + `Date` type time objects (e.g., `new Date('2024-04-09 13:00:00')`).
+
+##${prefix} gap(number|string)
+
+The display size of the break axis truncated area.
+
++ `number`: Same unit as `start` and `end`, not representing pixel size
++ `string`:
+ + Supports percentage forms like `'35%'`, representing relative proportion to the coordinate axis data area size
+ + Supports strings like `'123'`, equivalent to `number` type `123`, note that it does not represent pixel size
+
+##${prefix} isExpanded(boolean) = false
+
+Whether this truncated area is expanded, default is `false`.
+
+#${prefix} breakArea
+
+Style of the break axis truncated area.
+
+##${prefix} show(boolean) = true
+
+Whether to show the truncated area.
+
+##${prefix} itemStyle
+
+Style of the truncated area.
+
+{{ use: partial-item-style(
+ prefix = '###',
+ defaultColor = "#fff",
+ defaultBorderColor = "'#b7b9be'",
+ defaultBorderWidth = 1,
+ defaultType = "[3, 3]",
+ defaultOpacity = 0.6
+) }}
+
+##${prefix} zigzagAmplitude(number) = 4
+
+The amplitude (in the direction perpendicular to the coordinate axis) of the truncated zigzag. The size of the truncated zigzag in the direction perpendicular to the coordinate axis is always the same across different zigzags.
+
+##${prefix} zigzagMinSpan(number) = 4
+
+The minimum size of the truncated zigzag in the coordinate axis direction.
+
+> The size of the truncated zigzag in the coordinate axis direction is a random number between `zigzagMinSpan` and `zigzagMaxSpan`. Randomness is used to simulate the effect of torn paper.
+
+##${prefix} zigzagMaxSpan(number) = 20
+
+The maximum size of the truncated zigzag in the coordinate axis direction.
+
+> The size of the truncated zigzag in the coordinate axis direction is a random number between `zigzagMinSpan` and `zigzagMaxSpan`. Randomness is used to simulate the effect of torn paper.
+
+##${prefix} zigzagZ(number) = 100
+
+The `z` value of the truncated zigzag. Controls the front-to-back order of graphics. Graphics with smaller `z` values will be covered by graphics with larger `z` values.
+
+##${prefix} expandOnClick(boolean) = true
+
+Whether to expand the truncated area when clicking on the break axis truncated area.
+
+#${prefix} breakLabelLayout(Object)
+
+Break axis label layout.
+
+##${prefix} moveOverlap(string|boolean) = 'auto'
+
+When break axis labels overlap, whether to move labels to avoid overlap.
+
+`'auto'` or `true` means moving labels to avoid overlap when overlapping occurs; `false` means not moving.
+{{ /if }}
+
#${prefix} axisLine(Object)
Settings related to axis line.
@@ -806,7 +913,8 @@ To specify the start value of the axis.
{{ use: partial-axis-common-axis-line(
prefix = ${prefix},
componentType = ${componentType},
- hasJitter = ${hasJitter}
+ hasJitter = ${hasJitter},
+ hasBreakAxis = ${hasBreakAxis}
) }}
{{ use: partial-axis-common-axis-tick(
diff --git a/en/option/component/x-axis.md b/en/option/component/x-axis.md
index 8bacfbdd..ec958710 100644
--- a/en/option/component/x-axis.md
+++ b/en/option/component/x-axis.md
@@ -52,7 +52,8 @@ Notice: Set `xAxis.axisLine.onZero` to `false` to activate this option.
componentType = 'xAxis',
axisTypeDefault = "'category'",
hasSplitLineAndArea = true,
- hasJitter = true
+ hasJitter = true,
+ hasBreakAxis = true
) }}
{{ use: partial-z-zlevel(
diff --git a/en/option/component/y-axis.md b/en/option/component/y-axis.md
index 44838309..11e6a5e8 100644
--- a/en/option/component/y-axis.md
+++ b/en/option/component/y-axis.md
@@ -52,7 +52,8 @@ Notice: Set `yAxis.axisLine.onZero` to `false` to activate this option.
componentType = 'yAxis',
axisTypeDefault = "'value'",
hasSplitLineAndArea = true,
- hasJitter = true
+ hasJitter = true,
+ hasBreakAxis = true
) }}
{{ use: partial-z-zlevel(
diff --git a/zh/option/component/axis-common.md b/zh/option/component/axis-common.md
index 0d1679c3..a68b890a 100644
--- a/zh/option/component/axis-common.md
+++ b/zh/option/component/axis-common.md
@@ -47,6 +47,115 @@
在设置了 [jitter](~${componentType}.jitter) 且 [jitterOverlap](~${componentType}.jitterOverlap) 为 `false` 的情况下，两个数据点之间的最小距离。
{{ /if }}
+
+
+{{ if: ${hasBreakAxis|default(false)} }}
+#${prefix} breaks(Array)
+
+断轴的截断数据，每一个子元素表示一段截断的空间。
+
+~[800x400](${galleryViewPath}intraday-breaks-2&edit=1&reset=1)
+
+> 断轴是一种通过在坐标轴上截断部分区域，从而压缩图表中非关键数据段的展示空间的技术。其核心目的是：
+>
+> + **突出差异**：当数据间存在极端差异时（如一个值远大于其他值），避免大数值柱子压倒性占据空间，导致小数值差异难以辨认。
+> + **节省空间**：减少因极值导致的空白区域，使图表更紧凑。
+>
+> 请注意仅在必要的时候使用断轴，以免给用户带来理解上的误导。当使用断轴时，通常应当明确示意截断部分和对应的数值。
+>
+> 断轴无法在类目轴（[type](~${componentType}.type): `'category'`）中使用。
+
+##${prefix} start(string|number|Date)
+
+开始截断的值。
+
++ 对于 [type](~${componentType}.type) 是 `'value'` 或 `'log'` 类型的坐标轴，使用 `number` 类型的值
++ 对于 [type](~${componentType}.type) 是 `'time'` 类型的坐标轴
+ + `string` 类型的时间值（例如 `'2024-04-09 13:00:00'`）
+ + `number` 类型的时间戳（例如 `(new Date('2024-04-09 13:00:00')).getTime()`）
+ + `Date` 类型的时间对象（例如 `new Date('2024-04-09 13:00:00')`）。
+
+##${prefix} end(string|number|Date)
+
+结束截断的值。
+
++ 对于 [type](~${componentType}.type) 是 `'value'` 或 `'log'` 类型的坐标轴，使用 `number` 类型的值
++ 对于 [type](~${componentType}.type) 是 `'time'` 类型的坐标轴
+ + `string` 类型的时间值（例如 `'2024-04-09 13:00:00'`）
+ + `number` 类型的时间戳（例如 `(new Date('2024-04-09 13:00:00')).getTime()`）
+ + `Date` 类型的时间对象（例如 `new Date('2024-04-09 13:00:00')`）。
+
+##${prefix} gap(number|string)
+
+断轴截断区域展示的大小。
+
++ `number`：单位和 `start` 与 `end` 相同，而不表示像素大小
++ `string`：
+ + 支持例如 `'35%'` 的百分比形式，表示相对于坐标轴数据区域大小的相对比例
+ + 支持例如 `'123'` 的字符串，等同于 `number` 类型的 `123，注意不表示像素大小
+
+##${prefix} isExpanded(boolean) = false
+
+该截断区域是否已展开，默认为 `false`。
+
+#${prefix} breakArea
+
+断轴截断区域的样式。
+
+##${prefix} show(boolean) = true
+
+是否显示截断区域。
+
+##${prefix} itemStyle
+
+截断区域样式。
+
+{{ use: partial-item-style(
+ prefix = '###',
+ defaultColor = "#fff",
+ defaultBorderColor = "'#b7b9be'",
+ defaultBorderWidth = 1,
+ defaultType = "[3, 3]",
+ defaultOpacity = 0.6
+) }}
+
+##${prefix} zigzagAmplitude(number) = 4
+
+截断锯齿的振幅（垂直坐标轴方向上）大小。截断锯齿在垂直坐标轴的方向上的大小在不同锯齿上总是相同的。
+
+##${prefix} zigzagMinSpan(number) = 4
+
+截断锯齿在坐标轴方向上最小的大小。
+
+> 截断锯齿在坐标轴方向上的大小是 `zigzagMinSpan` 和 `zigzagMaxSpan` 之间的随机数。通过随机来模拟纸片撕开的效果。
+
+##${prefix} zigzagMaxSpan(number) = 20
+
+截断锯齿在坐标轴方向上最大的大小。
+
+> 截断锯齿在坐标轴方向上的大小是 `zigzagMinSpan` 和 `zigzagMaxSpan` 之间的随机数。通过随机来模拟纸片撕开的效果。
+
+##${prefix} zigzagZ(number) = 100
+
+截断锯齿的 `z` 值。控制图形的前后顺序。`z` 值小的图形会被 `z` 值大的图形覆盖。
+
+##${prefix} expandOnClick(boolean) = true
+
+点击断轴截断区域是否展开截断区域。
+
+#${prefix} breakLabelLayout(Object)
+
+断轴文字布局。
+
+##${prefix} moveOverlap(string|boolean) = 'auto'
+
+当断轴文字重叠时，是否移动文字来避免重叠。
+
+`'auto'` 或 `true` 表示重叠时移动文字来避免重叠；`false` 表示不移动。
+{{ /if }}
+
+
+
#${prefix} axisLine(Object)
坐标轴轴线相关设置。
@@ -803,7 +912,8 @@ max: function (value) {
{{ use: partial-axis-common-axis-line(
prefix = ${prefix},
componentType = ${componentType},
- hasJitter = ${hasJitter}
+ hasJitter = ${hasJitter},
+ hasBreakAxis = ${hasBreakAxis}
) }}
{{ use: partial-axis-common-axis-tick(
diff --git a/zh/option/component/x-axis.md b/zh/option/component/x-axis.md
index d4c2ff55..26aa8125 100644
--- a/zh/option/component/x-axis.md
+++ b/zh/option/component/x-axis.md
@@ -87,7 +87,8 @@ X 轴相对于默认位置的偏移，在相同的 `position` 上有多个 X 轴
componentType = 'xAxis',
axisTypeDefault = "'category'",
hasSplitLineAndArea = true,
- hasJitter = true
+ hasJitter = true,
+ hasBreakAxis = true
) }}
{{ use: partial-z-zlevel(
diff --git a/zh/option/component/y-axis.md b/zh/option/component/y-axis.md
index 1d5d7f8f..54e533dd 100644
--- a/zh/option/component/y-axis.md
+++ b/zh/option/component/y-axis.md
@@ -133,7 +133,8 @@ Y 轴相对于默认位置的偏移，在相同的 `position` 上有多个 Y 轴
componentType = 'yAxis',
axisTypeDefault = "'value'",
hasSplitLineAndArea = true,
- hasJitter = true
+ hasJitter = true,
+ hasBreakAxis = true
) }}
{{ use: partial-z-zlevel(
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@echarts.apache.org
For additional commands, e-mail: commits-help@echarts.apache.org