docs-lens-chart-page

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Creating Lens Chart Documentation Pages

创建 Lens 图表文档页面

Use these instructions when creating or updating a documentation page for a Kibana Lens chart type in

explore-analyze/visualize/charts/

在

explore-analyze/visualize/charts/

中为 Kibana Lens 图表类型创建或更新文档页面时，请遵循这些说明。

Before writing: verify settings against source code

编写前：根据源代码核对设置

Use the lens-chart-settings skill to verify all UI labels, option values, and rendering order against the Kibana source code before documenting them. Never guess UI labels.

使用 lens-chart-settings skill 核对所有 UI 标签、选项值和呈现顺序，确保它们与 Kibana 源代码一致，然后再编写文档。绝不要猜测 UI 标签。

Research resources

研究资源

Kibana source code paths

Kibana 源代码路径

Chart type	Source path
Partition (pie, donut, treemap, mosaic, waffle)	`x-pack/platform/plugins/shared/lens/public/visualizations/partition/`
XY (bar, line, area)	`x-pack/platform/plugins/shared/lens/public/visualizations/xy/`
Metric	`x-pack/platform/plugins/shared/lens/public/visualizations/metric/`
Datatable	`x-pack/platform/plugins/shared/lens/public/visualizations/datatable/`

Many visualizations use shared components (in

shared_components/

) that accept different props per chart. Always check the visualization-specific wrapper to see which props are passed, rather than assuming all shared component options are available.

图表类型	源代码路径
Partition（饼图、圆环图、树图、马赛克图、蜂格图）	`x-pack/platform/plugins/shared/lens/public/visualizations/partition/`
XY（柱状图、折线图、面积图）	`x-pack/platform/plugins/shared/lens/public/visualizations/xy/`
Metric（指标图）	`x-pack/platform/plugins/shared/lens/public/visualizations/metric/`
Datatable（数据表）	`x-pack/platform/plugins/shared/lens/public/visualizations/datatable/`

许多可视化使用共享组件（位于

shared_components/

中），这些组件会根据图表接收不同的 props。请始终检查特定于可视化的 wrapper，以确定传入了哪些 props，而不要假设所有共享组件选项都可用。

EUI data visualization guidelines

EUI 数据可视化指南

Part-to-whole comparisons (pie, donut, treemap)
Dashboard good practices
Categorical color palettes

Existing content to check

需要检查的现有内容

Main Lens page:
```
explore-analyze/visualize/lens.md
```
— check for content to reference or deduplicate.
Other chart pages:
```
explore-analyze/visualize/charts/*.md
```
— follow established patterns.
Shared snippets:
```
explore-analyze/_snippets/lens-*.md
```
— reuse instead of duplicating.

Key snippets:

Snippet	Purpose
`lens-prerequisites.md`	Prerequisites paragraph (data views, ES\|QL mode)
`lens-rank-by-options.md`	Top values rank-by options
`lens-value-advanced-settings.md`	Advanced settings for value/metric dimensions
`lens-breakdown-advanced-settings.md`	Breakdown advanced settings
`lens-histogram-settings.md`	Date histogram settings
`line-chart-legend-settings.md`	Legend settings including Statistics (line/area)
`line-chart-style-settings.md`	Style settings (line/area)

When creating a new chart page, update

lens.md

to link to it and remove any duplicated content.

Lens 主页面：
```
explore-analyze/visualize/lens.md
```
— 检查可引用或可去重的内容。
其他图表页面：
```
explore-analyze/visualize/charts/*.md
```
— 遵循既有模式。
共享代码片段：
```
explore-analyze/_snippets/lens-*.md
```
— 应复用而不是重复编写。

关键代码片段：

代码片段	用途
`lens-prerequisites.md`	前置条件段落（data view、ES\|QL 模式）
`lens-rank-by-options.md`	Top values 的 rank-by 选项
`lens-value-advanced-settings.md`	value/metric 维度的高级设置
`lens-breakdown-advanced-settings.md`	Breakdown 高级设置
`lens-histogram-settings.md`	Date histogram 设置
`line-chart-legend-settings.md`	图例设置，包括 Statistics（折线图/面积图）
`line-chart-style-settings.md`	样式设置（折线图/面积图）

创建新图表页面时，更新

lens.md

以链接到该页面，并移除重复内容。

File location and frontmatter

文件位置和 Frontmatter

Place the file at

explore-analyze/visualize/charts/<chart-type>.md

with this frontmatter:

yaml

---
navigation_title: <Chart type> charts
description: Instructions and best practices for building <chart type> charts with Kibana Lens in Elastic.
---

将文件放在

explore-analyze/visualize/charts/<chart-type>.md

，并使用以下 frontmatter：

yaml

---
navigation_title: <Chart type> charts
description: Instructions and best practices for building <chart type> charts with Kibana Lens in Elastic.
---

Chart-specific dimensions

图表专用维度

Chart type	Primary dimensions	Additional dimensions
Pie / Donut	Slice by, Metric	(none)
Bar / Line / Area	Horizontal axis, Vertical axis	Breakdown
Metric	Primary metric	Secondary metric, Maximum value
Gauge	Metric	Minimum value, Maximum value, Goal
Table	Metrics, Rows	Split metrics by

图表类型	主要维度	其他维度
饼图 / 圆环图	Slice by、Metric	（无）
柱状图 / 折线图 / 面积图	Horizontal axis、Vertical axis	Breakdown
指标图	Primary metric	Secondary metric、Maximum value
仪表图	Metric	Minimum value、Maximum value、Goal
表格	Metrics、Rows	Split metrics by

Page structure

页面结构

Follow this exact section order. Every chart page uses it consistently.

请严格遵循以下章节顺序。所有图表页面都统一采用此顺序。

1. Title and introduction

1. 标题和简介

undefined

undefined

Build <chart type> charts with {{kib}}


- One paragraph (2-3 sentences): what the chart does and when it's useful. Focus on purpose.
- Weave in specific actionable constraints (e.g., "works best with a maximum of 6 slices"). Skip generic advice.
- Do **not** create a separate "When to use" section.
- A line: `You can create <chart type> charts in {{kib}} using [**Lens**](../lens.md).`
- A hero image of a representative example.


- 一个段落（2-3 个句子）：说明图表的作用及其适用场景。专注于用途。
- 融入具体、可执行的限制（例如，“最多 6 个切片时效果最佳”）。不要提供泛泛的建议。
- 不要单独创建“何时使用”章节。
- 一行：`You can create <chart type> charts in {{kib}} using [**Lens**](../lens.md).`
- 一张代表性示例的主视觉图（hero image）。

2. "Build a <chart type> chart" section

2. “构建 <chart type> 图表”章节

Include the prerequisites snippet before the stepper:

:::{include} ../../_snippets/lens-prerequisites.md
:::

Then use the

stepper

directive:

::::::{stepper}

:::::{step} Access Lens
**Lens** is {{kib}}'s main visualization editor. You can access it:
- From a dashboard: On the **Dashboards** page, open or create the dashboard where you want to add a <chart type> chart, then add a new visualization.
- From the **Visualize library** page by creating a new visualization.
:::::

:::::{step} Set the visualization to <Chart type>
New visualizations often start as **Bar** charts.

Using the **Visualization type** dropdown, select **<Chart type>**.
:::::

:::::{step} Define the data to show
[Chart-specific data configuration steps]
:::::

:::::{step} Customize the chart to follow best practices
[Best practices as a definition list]
:::::

:::::{step} Save the chart
- If you accessed Lens from a dashboard, select **Save and return** to save the visualization and add it to that dashboard, or select **Save to library** to add the visualization to the Visualize library and reuse it later.
- If you accessed Lens from the Visualize library, select **Save**. A menu opens and offers you to add the visualization to a dashboard and to the Visualize library.
:::::

::::::

Key conventions:

Access Lens and Save the chart steps are identical across all chart pages. Copy them verbatim.
Define the data to show lists numbered steps for chart-specific dimensions, then "Optionally:" for additional dimensions. Link dimension names to their settings sections (e.g.,
```
[**Slice by**](#slice-by-settings)
```
).
Customize the chart uses definition list format. List 4-6 actionable best practices. End with a line pointing to the full settings reference.

在 stepper 之前包含前置条件代码片段：

:::{include} ../../_snippets/lens-prerequisites.md
:::

然后使用

stepper

指令：

::::::{stepper}

:::::{step} Access Lens
**Lens** is {{kib}}'s main visualization editor. You can access it:
- From a dashboard: On the **Dashboards** page, open or create the dashboard where you want to add a <chart type> chart, then add a new visualization.
- From the **Visualize library** page by creating a new visualization.
:::::

:::::{step} Set the visualization to <Chart type>
New visualizations often start as **Bar** charts.

Using the **Visualization type** dropdown, select **<Chart type>**.
:::::

:::::{step} Define the data to show
[Chart-specific data configuration steps]
:::::

:::::{step} Customize the chart to follow best practices
[Best practices as a definition list]
:::::

:::::{step} Save the chart
- If you accessed Lens from a dashboard, select **Save and return** to save the visualization and add it to that dashboard, or select **Save to library** to add the visualization to the Visualize library and reuse it later.
- If you accessed Lens from the Visualize library, select **Save**. A menu opens and offers you to add the visualization to a dashboard and to the Visualize library.
::::::

::::::

关键约定：

Access Lens 和 Save the chart 步骤在所有图表页面中完全相同。请逐字复制。
Define the data to show 会先按编号步骤列出图表专用维度，然后以“Optionally:”引出其他维度。将维度名称链接到其设置章节（例如，
```
[**Slice by**](#slice-by-settings)
```
）。
Customize the chart 使用定义列表格式。列出 4-6 条可操作的最佳实践。最后用一行指向完整的设置参考。

3. Advanced scenarios (optional)

3. 高级场景（可选）

Only include when teaching a non-obvious technique users wouldn't discover on their own:

Using formulas (e.g., computing error rates as a percentage)
Configuring multiple metrics for completion progress (waffle)
Setting up dynamic bounds or goals from data (gauge)
Defining custom color ranges (heat map)
Configuring color bands with thresholds (gauge)

Do NOT create scenarios that are just "use the chart with different fields". For simpler chart types, the Examples section is sufficient.

When including scenarios:

Each scenario gets its own
```
##
```
or
```
###
```
heading with an anchor ID.
Use concrete examples based on Kibana Sample Data when possible.

仅在讲解用户无法自行发现的非显而易见的技术时包含此节：

使用公式（例如，将错误率计算为百分比）
为完成进度配置多个指标（waffle）
根据数据设置动态边界或目标（gauge）
定义自定义颜色范围（heat map）
使用阈值配置颜色带（gauge）

不要创建仅是“换用不同字段使用该图表”的场景。对于较简单的图表类型，示例章节已足够。

包含这些场景时：

每个场景都应有独立的
```
##
```
或
```
###
```
标题，并带锚点 ID。
尽可能基于 Kibana Sample Data 使用具体示例。

Sample data considerations

示例数据注意事项

The
```
response
```
field in web logs is a text field — KQL filters must use pattern matching (
```
response: 2*
```
), not numeric comparisons.
In sample ecommerce data,
```
taxful_total_price
```
and
```
taxless_total_price
```
are identical.
Multiple comparable numeric fields are rare. When sample data doesn't support a scenario, use a conceptual example with realistic field names and add a
```
:::note
```
explaining users need to adapt to their data.

Web 日志中的
```
response
```
字段是 text 字段——KQL 过滤器必须使用模式匹配（
```
response: 2*
```
），而不是数值比较。
在示例电子商务数据中，
```
taxful_total_price
```
和
```
taxless_total_price
```
完全相同。
可比较的数值字段很少见。示例数据无法支持某个场景时，请使用包含逼真字段名的概念性示例，并添加
```
:::note
```
说明用户需要根据自身数据进行调整。

4. "<Chart type> settings" section

4. “<Chart type> 设置”章节

Document every configuration option in the Lens editor, organized by dimension/panel.

Structure each dimension as:

undefined

记录 Lens 编辑器中的每一个配置选项，并按维度或面板组织。

按以下结构组织每个维度：

undefined

<Dimension> settings [<dimension>-settings]


Within each dimension, use **two top-level definition list entries**: `**Data**` and `**Appearance**`.

**Data**:
- List all available functions/aggregation types.
- For each function, document the **Field** selector first, then function-specific sub-options as nested bullets.
- **Field selector conventions**:
  - **Top values**: Supports up to 4 fields. Multiple fields create multi-term grouping. Fields can be reordered by dragging.
  - **Date histogram**: Single date field only.
  - **Intervals**: Single numeric field only.
  - **Filters**: No field selector (KQL queries reference fields directly).
- Reuse shared snippets wherever applicable.

**Appearance**:
- List visual options: Name, Value format, Color, Series color, Color mapping, etc.

After dimension-specific settings, add a `### General layout` section for global settings ({icon}\`brush\` **Style** and legend). Split into `#### Style settings` and `#### Legend settings` as needed.

**Legend settings** vary by chart type:

| Setting | XY charts | Partition charts | Notes |
|---------|-----------|-----------------|-------|
| Visibility | Yes | Yes | Auto / Show / Hide |
| Position | Yes | No | Partition charts don't pass `location` |
| Statistics | Yes | No | Controlled by `defaultLegendStats` |
| Nested legend | No | Yes (>1 group) | Multiple Group by dimensions required |
| Label truncation | Yes | Yes | |
| Width | Yes | Yes | UI label is "Width", not "Legend size" |


在每个维度中，使用两个顶层定义列表条目：**Data** 和 **Appearance**。

**Data**：

- 列出所有可用的函数或聚合类型。
- 对于每个函数，先记录 **Field** 选择器，再将函数特有的子选项记录为嵌套项目符号。
- **Field 选择器约定**：
  - **Top values**：最多支持 4 个字段。多个字段会创建多词项分组。可以通过拖动重新排序字段。
  - **Date histogram**：仅支持单个日期字段。
  - **Intervals**：仅支持单个数值字段。
  - **Filters**：没有字段选择器（KQL 查询直接引用字段）。
- 尽可能复用共享代码片段。

**Appearance**：

- 列出视觉选项：Name、Value format、Color、Series color、Color mapping 等。

在维度专用设置之后，添加 `### General layout` 章节以介绍全局设置（{icon}\`brush\` **Style** 和图例）。根据需要拆分为 `#### Style settings` 和 `#### Legend settings`。

**图例设置**因图表类型而异：

| 设置 | XY 图表 | Partition 图表 | 备注 |
|---------|-----------|-----------------|-------|
| Visibility | 是 | 是 | Auto / Show / Hide |
| Position | 是 | 否 | Partition 图表不传入 `location` |
| Statistics | 是 | 否 | 由 `defaultLegendStats` 控制 |
| Nested legend | 否 | 是（超过 1 个分组） | 需要多个 Group by 维度 |
| Label truncation | 是 | 是 | |
| Width | 是 | 是 | UI 标签是“Width”，不是“Legend size” |

5. "<Chart type> examples" section

5. “<Chart type> 示例”章节

2-4 real-world examples using Kibana Sample Data.
Use definition list format with bold example title.
Structure each example:
- ```
* Example based on: <sample data set name>
```
- Configuration keys as bullet points (Slice by, Metric, Style, Legend, etc.)
- An image of the result, sized with
```
"=60%"
```
  or
```
"=70%"
```
Showcase different features (e.g., basic config, donut variant, filters, multiple metrics).

使用 Kibana Sample Data 提供 2-4 个真实世界示例。
使用定义列表格式，并将示例标题设为粗体。
每个示例按以下方式组织：
- ```
* Example based on: <sample data set name>
```
- 以项目符号形式列出配置键（Slice by、Metric、Style、Legend 等）
- 插入结果图片，尺寸设为
```
"=60%"
```
  或
```
"=70%"
```
展示不同功能（例如，基础配置、圆环图变体、过滤器、多指标）。

Chart-page-specific formatting

图表页面专用格式

For general syntax, refer to the docs-syntax-help skill. These conventions are specific to chart pages:

有关通用语法，请参阅 docs-syntax-help skill。以下约定专用于图表页面：

Images

图片

Store at
```
explore-analyze/images/<image-name>.png
```

Reference with:

![Alt text](/explore-analyze/images/<image-name>.png "=60%")

Sizing:
```
"=50%"
```
for smaller inline images,
```
"=60%"
```
for examples,
```
"=70%"
```
for settings screenshots.
Alt text should be descriptive, not "screenshot".

存储在
```
explore-analyze/images/<image-name>.png
```

引用方式：

![Alt text](/explore-analyze/images/<image-name>.png "=60%")

尺寸：
```
"=50%"
```
用于较小的内嵌图片，
```
"=60%"
```
用于示例，
```
"=70%"
```
用于设置截图。
替代文本应具有描述性，不要只写“screenshot”。

Icons

图标

Icon	Syntax	Usage
Style/brush	`{icon}\` brush``	Style settings panel
Layer settings	`{icon}\` app_management``	Layer settings (9.3+/Serverless)
Actions menu	`{icon}\` boxes_horizontal``	Layer actions menu (9.0-9.2)
Add layer	`{icon}\` plus_in_square``	Add layer button

For the legend icon, use:

![Legend icon](/explore-analyze/images/kibana-legend-icon.svg "")

图标	语法	用途
Style/brush	`{icon}\` brush``	Style 设置面板
Layer settings	`{icon}\` app_management``	图层设置（9.3+/Serverless）
Actions menu	`{icon}\` boxes_horizontal``	图层操作菜单（9.0-9.2）
Add layer	`{icon}\` plus_in_square``	添加图层按钮

对于图例图标，请使用：

![Legend icon](/explore-analyze/images/kibana-legend-icon.svg "")

Cross-references

交叉引用

Other chart types:
```
[bar charts](bar-charts.md)
```
Lens page:
```
[**Lens**](../lens.md)
```

Lens features:

[Assign colors to terms](../lens.md#assign-colors-to-terms)

Sample data:

[sample data](/manage-data/ingest/sample-data.md)

其他图表类型：
```
[bar charts](bar-charts.md)
```
Lens 页面：
```
[**Lens**](../lens.md)
```

Lens 功能：

[Assign colors to terms](../lens.md#assign-colors-to-terms)

示例数据：

[sample data](/manage-data/ingest/sample-data.md)

Internal links

内部链接

Link from steps to settings sections:

2. Configure the [**Slice by**](#slice-by-settings) dimension.
3. Configure the [**Metric**](#metric-settings) dimension.

Link from best practices to advanced scenarios when relevant.

从步骤链接到设置章节：

2. Configure the [**Slice by**](#slice-by-settings) dimension.
3. Configure the [**Metric**](#metric-settings) dimension.

从最佳实践链接到相关的高级场景。

Variables

变量

Use

{{kib}}

(Kibana),

{{es}}

(Elasticsearch),

{{data-source}}

(data view / data source).

使用

{{kib}}

（Kibana）、

{{es}}

（Elasticsearch）、

{{data-source}}

（data view / data source）。

Checklist

检查清单

Frontmatter has
```
navigation_title
```
and
```
description
```
Hero image exists and is referenced
"Build a chart" stepper uses standard Access Lens / Save steps
Prerequisites snippet included before the stepper
All settings verified against Kibana source code (use lens-chart-settings skill)
All settings from the Lens editor are documented in the Settings section
Shared snippets included where applicable (not duplicated)
Examples use Kibana Sample Data and include images
Internal links from steps to settings sections
Links from best practices to related advanced scenarios
```
lens.md
```
updated to link to the new page

Frontmatter 包含
```
navigation_title
```
和
```
description
```
主视觉图已存在且已被引用
“构建图表”stepper 使用标准的 Access Lens / Save the chart 步骤
stepper 之前已包含前置条件代码片段
所有设置均已根据 Kibana 源代码核对（使用 lens-chart-settings skill）
Settings 章节已记录 Lens 编辑器中的所有设置
在适用情况下已包含共享代码片段，而不是重复编写
示例使用 Kibana Sample Data 并包含图片
从步骤到设置章节的内部链接已添加
从最佳实践到相关高级场景的链接已添加
```
lens.md
```
已更新并链接到新页面