This is an automated email from the ASF dual-hosted git repository.
sushuang pushed a commit to branch feat-cartesian-layout
in repository https://gitbox.apache.org/repos/asf/echarts-doc.git
The following commit(s) were added to refs/heads/feat-cartesian-layout by this
push:
new a99907c2 grid: add doc for outerBounds, and clarify some grid doc.
a99907c2 is described below
commit a99907c24e04dc511b9d0ec7f223879119f00e4f
Author: 100pah <sushuang0...@gmail.com>
AuthorDate: Wed Jul 30 14:55:08 2025 +0800
grid: add doc for outerBounds, and clarify some grid doc.
---
en/option/component/grid.md | 67 +++++++++++++++++++++++++-
en/option/partial/rect-layout-width-height.md | 6 ++-
zh/option/component/grid.md | 68 ++++++++++++++++++++++++++-
zh/option/partial/rect-layout-width-height.md | 6 ++-
4 files changed, 139 insertions(+), 8 deletions(-)
diff --git a/en/option/component/grid.md b/en/option/component/grid.md
index 6e9134e3..0b502e33 100644
--- a/en/option/component/grid.md
+++ b/en/option/component/grid.md
@@ -22,7 +22,7 @@ In ECharts 2.x, there could only be one single grid component
at most in a singl
Whether to show the grid in rectangular coordinate.
{{ use: partial-rect-layout-width-height(
- componentName = "grid ",
+ componentName = "grid",
defaultLeft = "'10%'",
defaultTop = 60,
defaultRight = "'10%'",
@@ -30,9 +30,10 @@ Whether to show the grid in rectangular coordinate.
) }}
## containLabel(boolean) = false
-
<ExampleUIControlBoolean default="false" />
+{{ use: partial-version(version = "6.0.0", deprecated = 'See
[grid.outerBoundsMode](~grid.outerBoundsMode).') }}
+
Whether the grid region contains [axis tick label](~yAxis.axisLabel).
+ When containLabel is `false`:
@@ -42,6 +43,68 @@ Whether the grid region contains [axis tick
label](~yAxis.axisLabel).
+ `grid.left` `grid.right` `grid.top` `grid.bottom` `grid.width`
`grid.height` decide the location and size of the rectangle that contains the
axes, and the labels of the axes.
+ Setting to `true` will help when the length of axis labels is dynamic
and is hard to approximate. This will avoid labels from overflowing the
container or overlapping other components.
+## outerBoundsMode(string) = 'auto'
+{{ use: partial-version(version = "6.0.0") }}
+
+The "outer bounds" is a constraint rectangle used to prevent axis labels and
axis names from overflowing. `outerBoundsMode` defines the strategy for
determining the "outer bounds".
+
+In most cases, we do not need to specify
[grid.outerBoundsMode](~grid.outerBoundsMode),
[grid.outerBounds](~grid.outerBounds),
[grid.outerBoundsContain](~grid.outerBoundsContain) and
[grid.containLabel](~grid.containLabel), as the default settings can prevent
axis labels and axis names from overflowing the canvas.
+
+The grid component (Cartesian) layout strategy:
++ First, lay out axis lines based on the rect defined by
[grid.left](~grid.left)/[right](~grid.right)/[top](~grid.top)/[bottom](~grid.bottom)/[width](~grid.width)/[height](~grid.height).
This can meet the requirement of aligning axis lines across multiple grids.
++ Then, if axis labels and/or axis names overflow the "outer bounds", shrink
the rectangle to prevent that overflow.
[grid.outerBoundsContain](~grid.outerBoundsContain) determines whether axis
label and axis name is confined by the "outer bounds".
+
+Options of `outerBoundsMode`:
+- `'auto'`/`null`/`undefined` (default):
+ - Behave the same as `outerBoundsMode: 'same'` when `grid.containLabel:
true`.
+ - Otherwise, the "outer bounds" is determined by
[grid.outerBounds](~grid.outerBounds) if specified.
+ - Otherwise, automatically determine the "outer bounds" - typically
defaulting to the current canvas, or a assigned layout rectangle if this `grid`
is laid out in another coordinate system (see
[grid.coordinateSystem](~grid.coordinateSystem)).
+- `'none'`: Force the "outer bounds" to be infinity (i.e., no constraint),
regardless of the specified [grid.outerBounds](~grid.outerBounds).
+- `'same'`: Force the "outer bounds" to be the same as the layout rectangle
defined by
[grid.left](~grid.left)/[right](~grid.right)/[top](~grid.top)/[bottom](~grid.bottom)/[width](~grid.width)/[height](~grid.height),
regardless of the specified [grid.outerBounds](~grid.outerBounds).
+
+> The "outer bounds" encompasses the functionality of
[grid.containLabel](~grid.containLabel); therefore,
[grid.containLabel](~grid.containLabel) is deprecated. `grid.containLabel:
true` is equivalent to `grid: {outerBoundsMode: 'same', outerBoundsContain:
'axisLabel'}`.
+> The effect might be slightly different, but usually indiscernible. You can
use the code below to enforce the previous effect, though it's unnecessary in
most cases.
+> ```js
+> import {use} from 'echarts/core';
+> import {LegacyGridContainLabel} from 'echarts/features';
+> use([LegacyGridContainLabel]);
+> ```
+
+**Demo**: [outerBounds
example](${galleryEditorPath}doc-example/grid-outerBounds&edit=1&reset=1).
+
+
+## outerBounds(Object)
+{{ use: partial-version(version = "6.0.0") }}
+
+See details in [grid.outerBoundsMode](~grid.outerBoundsMode).
+
+See also [outerBounds
example](${galleryEditorPath}doc-example/grid-outerBounds&edit=1&reset=1).
+
+{{ use: partial-rect-layout-width-height(
+ hostName = "`outerBounds`",
+ noZ = true,
+ prefix = '##',
+ defaultLeft = 0,
+ defaultTop = 0,
+ defaultRight = 0,
+ defaultBottom = 0
+) }}
+
+## outerBoundsContain(boolean) = 'auto'
+{{ use: partial-version(version = "6.0.0") }}
+
+Options:
+- `'auto'`/`null`/`undefined` (default):
+ - Behave the same as `outerBoundsContain: 'axisLabel'` if `containLabel:
true`.
+ - Otherwise, behave the same as `outerBoundsContain: 'all'`.
+- `'all'`: The "outer bounds" constrain the grid (Cartesian) rectangle
(determined by the x-axis and y-axis lines) and axis labels and axis names.
+- `'axisLabel'`: The "outer bounds" constrain the grid (Cartesian) rectangle
(determined by the x-axis and y-axis lines) and axis labels, but exclude axis
names.
+
+For more details, see [grid.outerBoundsMode](~grid.outerBoundsMode).
+
+See also [outerBounds
example](${galleryEditorPath}doc-example/grid-outerBounds&edit=1&reset=1).
+
+
{{ use: partial-component-common-style(
componentName = "grid",
prefix = '#',
diff --git a/en/option/partial/rect-layout-width-height.md
b/en/option/partial/rect-layout-width-height.md
index 78fc65de..463c388a 100644
--- a/en/option/partial/rect-layout-width-height.md
+++ b/en/option/partial/rect-layout-width-height.md
@@ -9,17 +9,19 @@
{{ use: partial-rect-layout(
hostName = ${hostName},
+ noZ = ${noZ},
+ prefix = ${prefix},
defaultLeft = ${defaultLeft},
defaultTop = ${defaultTop},
defaultRight = ${defaultRight},
defaultBottom = ${defaultBottom}
) }}
-## width(string|number) = ${defaultWidth|default("'auto'")}
+#${prefix|default("#")} width(string|number) =
${defaultWidth|default("'auto'")}
Width of ${hostNameStr}. {{ if: !${defaultWidth} }}Adaptive by default.{{ /if
}}
-## height(string|number) = ${defaultHeight|default("'auto'")}
+#${prefix|default("#")} height(string|number) =
${defaultHeight|default("'auto'")}
Height of ${hostNameStr}. {{ if: !${defaultHeight} }}Adaptive by default.{{
/if }}
diff --git a/zh/option/component/grid.md b/zh/option/component/grid.md
index 7bef5940..a46fa252 100644
--- a/zh/option/component/grid.md
+++ b/zh/option/component/grid.md
@@ -59,7 +59,7 @@ const option = {
是否显示直角坐标系网格。
{{ use: partial-rect-layout-width-height(
- componentName = "grid ",
+ componentName = "直角坐标系（grid）",
defaultLeft = "'10%'",
defaultTop = 60,
defaultRight = "'10%'",
@@ -68,6 +68,8 @@ const option = {
## containLabel(boolean) = false
+{{ use: partial-version(version = "6.0.0", deprecated = '参考
[grid.outerBoundsMode](~grid.outerBoundsMode)。') }}
+
<ExampleUIControlBoolean default="false" />
grid 区域是否包含坐标轴的[刻度标签](~yAxis.axisLabel)。
@@ -79,8 +81,70 @@ grid 区域是否包含坐标轴的[刻度标签](~yAxis.axisLabel)。
+ `grid.left` `grid.right` `grid.top` `grid.bottom` `grid.width`
`grid.height` 决定的是包括了坐标轴标签在内的所有内容所形成的矩形的位置。
+ 这常用于『防止标签溢出』的场景，标签溢出指的是，标签长度动态变化时，可能会溢出容器或者覆盖其他组件。
+## outerBoundsMode(string) = 'auto'
+{{ use: partial-version(version = "6.0.0") }}
+
+外边界（outer bounds）是一个用于限制轴标签和轴名称溢出的矩形区域。`outerBoundsMode` 用于定义如何确定该“外边界”的策略。
+
+在大多数情况下，无需显式指定
[grid.outerBoundsMode](~grid.outerBoundsMode)、[grid.outerBounds](~grid.outerBounds)、[grid.outerBoundsContain](~grid.outerBoundsContain)
和 [grid.containLabel](~grid.containLabel)，因为默认配置已经能够有效防止轴标签和轴名称溢出画布。
+
+直角坐标系组件（grid）的布局策略如下：
++ 首先，根据
[grid.left](~grid.left)/[right](~grid.right)/[top](~grid.top)/[bottom](~grid.bottom)/[width](~grid.width)/[height](~grid.height)
所定义的矩形区域布置轴线。这可以满足多个 grid 对齐轴线的需求。
++ 然后，如果轴标签或轴名称超出了外边界（outer
bounds），则会收缩该矩形区域以避免溢出。其中，[grid.outerBoundsContain](~grid.outerBoundsContain)
可决定轴标签和轴名称是否受外边界的限制。
+
+`outerBoundsMode` 的可选值有：
+- `'auto'`/`null`/`undefined`（默认值）：
+ - 当 `grid.containLabel: true` 时，行为等同于 `outerBoundsMode: 'same'`。
+ - 否则，如果设置了 [grid.outerBounds](~grid.outerBounds)，则使用该值作为外边界（outer bounds）。
+ - 否则，自动确定外边界（outer bounds）—— 通常默认为当前 canvas 区域；或者，假如该 grid 被布局在其他坐标系中时（参见
[grid.coordinateSystem](~grid.coordinateSystem)），使用其他坐标系提指定的布局矩形作为外边界。
+- `'none'`：强制将外边界（outer bounds）设为无限大（即不作任何限制），无视是否设置了
[grid.outerBounds](~grid.outerBounds)。
+- 'same'：强制将外边界（outer bounds）设置为由
[grid.left](~grid.left)/[right](~grid.right)/[top](~grid.top)/[bottom](~grid.bottom)/[width](~grid.width)/[height](~grid.height)
所定义的矩形，无视是否设置了 [grid.outerBounds](~grid.outerBounds)。
+
+> 外边界（outer bounds）已涵盖 [grid.containLabel](~grid.containLabel) 的功能，因此
[grid.containLabel](~grid.containLabel) 被不再推荐使用（deprecated）。
+> `grid.containLabel: true` 等价于 `grid: {outerBoundsMode: 'same',
outerBoundsContain:
'axisLabel'}`。效果上可能会有细微差别，但通常难以察觉。你可以使用以下代码来强制保持原有效果，不过一般并无此必要。
+> ```js
+> import {use} from 'echarts/core';
+> import {LegacyGridContainLabel} from 'echarts/features';
+> use([LegacyGridContainLabel]);
+> ```
+
+**示例**: [outerBounds
示例](${galleryEditorPath}doc-example/grid-outerBounds&edit=1&reset=1).
+
+
+## outerBounds(Object)
+{{ use: partial-version(version = "6.0.0") }}
+
+详见 [grid.outerBoundsMode](~grid.outerBoundsMode).
+
+也参见 [outerBounds
示例](${galleryEditorPath}doc-example/grid-outerBounds&edit=1&reset=1).
+
+{{ use: partial-rect-layout-width-height(
+ hostName = "外边界（`outerBounds`）",
+ noZ = true,
+ prefix = '##',
+ defaultLeft = 0,
+ defaultTop = 0,
+ defaultRight = 0,
+ defaultBottom = 0
+) }}
+
+## outerBoundsContain(boolean) = 'auto'
+{{ use: partial-version(version = "6.0.0") }}
+
+可选值：
+- `'auto'`/`null`/`undefined`（默认）：
+ - 若设置了 `containLabel: true`，行为等同于 `outerBoundsContain: 'axisLabel'`。
+ - 否则，行为等同于 `outerBoundsContain: 'all'`。
+- `'all'`：外边界（outer bounds）会限制直角坐标系（grid）由 x 轴线和 y 轴线决定的矩形区域、轴标签（axis
label）和轴名称（axis name）。
+- `'axisLabel'`：外边界（outer bounds）会限制直角坐标系（grid）由 x 轴线和 y 轴线决定矩形区域和轴标签（axis
label）；不会限制轴名称（axis name）。
+
+更多信息参见 [grid.outerBoundsMode](~grid.outerBoundsMode).
+
+也参见 [outerBounds
示例](${galleryEditorPath}doc-example/grid-outerBounds&edit=1&reset=1).
+
+
{{ use: partial-component-common-style(
- componentName = "网格",
+ componentName = "直角坐标系（grid）",
prefix = '#',
needShow = true
) }}
diff --git a/zh/option/partial/rect-layout-width-height.md
b/zh/option/partial/rect-layout-width-height.md
index becf82c1..0594a455 100644
--- a/zh/option/partial/rect-layout-width-height.md
+++ b/zh/option/partial/rect-layout-width-height.md
@@ -9,19 +9,21 @@
{{ use: partial-rect-layout(
hostName = ${hostName},
+ noZ = ${noZ},
+ prefix = ${prefix},
defaultLeft = ${defaultLeft},
defaultTop = ${defaultTop},
defaultRight = ${defaultRight},
defaultBottom = ${defaultBottom}
) }}
-## width(string|number) = ${defaultWidth|default("'auto'")}
+#${prefix|default("#")} width(string|number) =
${defaultWidth|default("'auto'")}
<ExampleUIControlPercent default="50%"/>
${hostNameStr}的宽度。{{ if: !${defaultWidth} }}默认自适应。{{ /if }}
-## height(string|number) = ${defaultHeight|default("'auto'")}
+#${prefix|default("#")} height(string|number) =
${defaultHeight|default("'auto'")}
<ExampleUIControlPercent default="50%"/>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@echarts.apache.org
For additional commands, e-mail: commits-h...@echarts.apache.org
