doc: add doc for apache/echarts#18436

apache · Feb 2, 2024 · 3d7d72d · 3d7d72d
1 parent 62d1f0b
commit 3d7d72d
Show file tree

Hide file tree

Showing 2 changed files with 32 additions and 0 deletions.
diff --git a/en/option/component/tooltip.md b/en/option/component/tooltip.md
@@ -199,6 +199,8 @@ Useful when tooltip is cut because of `'overflow: hidden'` set on outer dom of c
     version = "4.7.0"
 ) }}
 
+(DEPRECATED, use [appendTo](~tooltip.appendTo) instead.)
+
 Whether to append the tooltip DOM element as a child of the `<body>` of the HTML page, when using [renderMode](~tooltip.renderMode) `'html'`.
 
 By default `false`, means that the tooltip DOM element will be one of a descendant of its echarts DOM container. But that means that the tooltip might be cut when overflow the container if some of the ancestors DOM element of the echarts container are styled with `overflow: hidden`. This case could also be resolved by setting [tooltip.confine](~tooltip.confine), but it might not suitable for all scenarios.
@@ -207,6 +209,20 @@ Here we provide `appendToBody: true` to auto append the tooltip element to `<bod
 
 Note that it also works when CSS transform used.
 
+## appendTo() = Function | HTMLElement | string | null
+
+{{ use: partial-version(
+    version = "5.5.0"
+) }}
+
+Which DOM element to append the tooltip to. Only avaiable when using [renderMode](~tooltip.renderMode) `'html'`.
+
+The default value is `null``, which means that the tooltip's DOM node will be added as a descendant node of the chart’s DOM container. However, this approach can cause the tooltip to be truncated if it extends beyond the container, due to ancestors of the chart's DOM container having overflow: hidden set. This issue can be partially addressed using tooltip.confine, but it may not cover all scenarios.
+
+For such scenarios, `appendTo` can be specified. When it is a function, the interface is in the form of `(chartContainer: HTMLElement) => HTMLElement | undefined | null`, which means it returns the node that the tooltip's DOM node should be added to. Returning `undefined` or `null` indicates that the default logic described above should be used. Returning an HTMLElement means that it should be added under that node.
+
+Note that it also works when CSS transform used.
+
 ## className(string)
 
 <ExampleUIControlText />

diff --git a/zh/option/component/tooltip.md b/zh/option/component/tooltip.md
@@ -199,6 +199,8 @@ const option = {
     version = "4.7.0"
 ) }}
 
+（已废弃，请使用 [appendTo](~tooltip.appendTo)。）
+
 是否将 tooltip 的 DOM 节点添加为 HTML 的 `<body>` 的子节点。只有当 [renderMode](~tooltip.renderMode) 为 `'html'` 是有意义的。
 
 默认值是 `false`。`false` 表示，tooltip 的 DOM 节点会被添加为本图表的 DOM container 的一个子孙节点。但是这种方式导致，如果本图表的 DOM container 的祖先节点有设置 `overflow: hidden`，那么当 tooltip 超出 container 范围使可能被截断。这个问题一定程度上可以用 [tooltip.confine](~tooltip.confine) 来解决，但是不一定能解决所有场景。
@@ -207,6 +209,20 @@ const option = {
 
 注：CSS transform 的场景，这也可以使用。
 
+## appendTo() = Function | HTMLElement | string | null
+
+{{ use: partial-version(
+    version = "5.5.0"
+) }}
+
+将 tooltip 的 DOM 节点添加到哪个节点下。只有当 [renderMode](~tooltip.renderMode) 为 `'html'` 是有意义的。
+
+默认值是 `null`，表示 tooltip 的 DOM 节点会被添加为本图表的 DOM container 的一个子孙节点。但是这种方式导致，如果本图表的 DOM container 的祖先节点有设置 `overflow: hidden`，那么当 tooltip 超出 container 范围使可能被截断。这个问题一定程度上可以用 [tooltip.confine](~tooltip.confine) 来解决，但是不一定能解决所有场景。
+
+对于这样的场景，可以指定 `appendTo`。当其为 `Function` 形式时，接口形如 `(chartContainer: HTMLElement) => HTMLElement | undefined | null`，即返回 tooltip 的 DOM 节点应该添加到哪个节点下。返回 `undefined` 或 `null` 表示采用上述的默认逻辑。返回 `HTMLElement` 表示添加到该节点下。
+
+注：CSS transform 的场景，这也可以使用。
+
 ## className(string)
 
 <ExampleUIControlText />