From 54d1ef9d8f4a0d79143300df26efd12f6f7f8d16 Mon Sep 17 00:00:00 2001
From: sz-p <sz_p@outlook.com>
Date: Tue, 22 Jul 2025 10:17:50 +0800
Subject: [PATCH] add doc for apache/echarts#21117

---
 en/option/partial/mark-area.md  |  6 ++++++
 en/option/partial/mark-line.md  |  6 ++++++
 en/option/partial/mark-point.md |  6 ++++++
 en/option/partial/z.md          | 13 +++++++++++++
 zh/option/partial/mark-area.md  |  6 ++++++
 zh/option/partial/mark-line.md  |  6 ++++++
 zh/option/partial/mark-point.md |  6 ++++++
 zh/option/partial/z.md          | 12 ++++++++++++
 8 files changed, 61 insertions(+)
 create mode 100644 en/option/partial/z.md
 create mode 100644 zh/option/partial/z.md

diff --git a/en/option/partial/mark-area.md b/en/option/partial/mark-area.md
index 6362381e4..2d6caba5e 100644
--- a/en/option/partial/mark-area.md
+++ b/en/option/partial/mark-area.md
@@ -169,6 +169,12 @@ Specify the right-bottom point.
     index = 1
 ) }}
 
+{{ use: partial-z(
+    prefix = "#" + ${prefix},
+    defaultZ = "1",
+    version = "6.0.0"
+) }}
+
 {{ use: partial-animation(
     prefix = "#" + ${prefix},
     defaultAnimation = 'false'
diff --git a/en/option/partial/mark-line.md b/en/option/partial/mark-line.md
index 4d17f0d6c..d39d42420 100644
--- a/en/option/partial/mark-line.md
+++ b/en/option/partial/mark-line.md
@@ -192,6 +192,12 @@ Data of the ending point.
     index = 1
 ) }}
 
+{{ use: partial-z(
+    prefix = "#" + ${prefix},
+    defaultZ = "5",
+    version = "6.0.0"
+) }}
+
 {{ use: partial-animation(
     prefix = "#" + ${prefix}
 ) }}
diff --git a/en/option/partial/mark-point.md b/en/option/partial/mark-point.md
index 19a01584e..3b9e726bc 100644
--- a/en/option/partial/mark-point.md
+++ b/en/option/partial/mark-point.md
@@ -220,6 +220,12 @@ Mark point style.
     prefix = "####" + ${prefix}
 ) }}
 
+{{ use: partial-z(
+    prefix = "#" + ${prefix},
+    defaultZ = "5",
+    version = "6.0.0"
+) }}
+
 {{ use: partial-animation(
     prefix = "#" + ${prefix}
 ) }}
diff --git a/en/option/partial/z.md b/en/option/partial/z.md
new file mode 100644
index 000000000..ee7252433
--- /dev/null
+++ b/en/option/partial/z.md
@@ -0,0 +1,13 @@
+
+{{ target: partial-z }}
+
+#${prefix|default("#")} z(number) = ${defaultZ|default(5)}
+
+{{ use: partial-version(
+    version = ${version}
+) }}
+
+Components with smaller `z` values may be overwritten by those with larger `z` values.
+
+`z` has a lower priority to `zlevel`, and will not create new Canvas.
+
diff --git a/zh/option/partial/mark-area.md b/zh/option/partial/mark-area.md
index 3a7d10985..e4a8cc936 100644
--- a/zh/option/partial/mark-area.md
+++ b/zh/option/partial/mark-area.md
@@ -169,6 +169,12 @@ data: [
     index = 1
 ) }}
 
+{{ use: partial-z(
+    prefix = "#" + ${prefix},
+    defaultZ = "1",
+    version = "6.0.0"
+) }}
+
 {{ use: partial-animation(
     prefix = "#" + ${prefix},
     defaultAnimation = 'false'
diff --git a/zh/option/partial/mark-line.md b/zh/option/partial/mark-line.md
index e4af746e0..35a6e3ff0 100644
--- a/zh/option/partial/mark-line.md
+++ b/zh/option/partial/mark-line.md
@@ -191,6 +191,12 @@ data: [
     index = 1
 ) }}
 
+{{ use: partial-z(
+    prefix = "#" + ${prefix},
+    defaultZ = "5",
+    version = "6.0.0"
+) }}
+
 {{ use: partial-animation(
     prefix = "#" + ${prefix}
 ) }}
diff --git a/zh/option/partial/mark-point.md b/zh/option/partial/mark-point.md
index ca838ba71..b00ee3d05 100644
--- a/zh/option/partial/mark-point.md
+++ b/zh/option/partial/mark-point.md
@@ -220,6 +220,12 @@ data: [{{ if: ${hasType} }}
     prefix = "####" + ${prefix}
 ) }}
 
+{{ use: partial-z(
+    prefix = "#" + ${prefix},
+    defaultZ = "5",
+    version = "6.0.0"
+) }}
+
 {{ use: partial-animation(
     prefix = "#" + ${prefix}
 ) }}
diff --git a/zh/option/partial/z.md b/zh/option/partial/z.md
new file mode 100644
index 000000000..a67dba85a
--- /dev/null
+++ b/zh/option/partial/z.md
@@ -0,0 +1,12 @@
+{{ target: partial-z }}
+
+#${prefix|default("#")} z(number) = ${defaultZ|default(5)}
+
+{{ use: partial-version(
+    version = ${version}
+) }}
+
+`z`值小的图形会被`z`值大的图形覆盖。
+
+`z`相比`zlevel`优先级更低，而且不会创建新的 Canvas。
+