mcpField
D
docs-lens-chart-page

docs-lens-chart-page

github.com/elastic文档处理72148 次安装2 天前更新
代码仓库

关于 docs-lens-chart-page

为 Kibana Lens 图表文档编写或更新页面的操作指南，面向 Elastic 文档作者。它提供从源码核实设置、组织页面内容到示例和格式规范的完整流程。

主要功能

  1. 01核对图表设置与源码
  2. 02规定页面章节和写作流程
  3. 03复用共享文档片段
  4. 04指导图表示例和设置说明
  5. 05提供格式与发布检查清单

适用场景

  1. 01编写新的 Lens 图表类型文档
  2. 02更新现有图表设置参考
  3. 03检查图表页面结构与链接
  4. 04依据 Kibana 源码验证 UI 标签

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/elastic/elastic-docs-skills --skill docs-lens-chart-page

安装后在 Claude Code 中输入/docs-lens-chart-page确认已加载。

附带文件evals/evals.json

详细介绍

创建 Lens 图表文档页面

在 explore-analyze/visualize/charts/ 中创建或更新 Kibana Lens 图表类型的文档页面时，请遵循以下说明。

撰写前：根据源代码核实设置

使用 lens-chart-settings 技能，根据 Kibana 源代码核实所有 UI 标签、选项值和渲染顺序，然后再编写文档。切勿猜测 UI 标签。

研究资源

Kibana 源代码路径
图表类型源路径
分区（饼图、圆环图、矩形树图、马赛克图、华夫图）x-pack/platform/plugins/shared/lens/public/visualizations/partition/
XY（条形图、折线图、面积图）x-pack/platform/plugins/shared/lens/public/visualizations/xy/
指标x-pack/platform/plugins/shared/lens/public/visualizations/metric/
数据表x-pack/platform/plugins/shared/lens/public/visualizations/datatable/

许多可视化会使用共享组件（位于 shared_components/），并针对不同图表传入不同属性。请务必检查特定可视化的包装器，确认传入了哪些属性，而不要假设所有共享组件选项都可用。

EUI 数据可视化指南
需要检查的现有内容
  • Lens 主页面：explore-analyze/visualize/lens.md — 检查是否有可引用或去重的内容。
  • 其他图表页面：explore-analyze/visualize/charts/*.md — 遵循已有模式。
  • 共享片段：explore-analyze/_snippets/lens-*.md — 尽量复用，避免重复。

关键片段：

片段用途
lens-prerequisites.md前提条件段落（数据视图、ES|QL 模式）
lens-rank-by-options.md前几个值的排序依据选项
lens-value-advanced-settings.md值/指标维度的高级设置
lens-breakdown-advanced-settings.md拆分维度的高级设置
lens-histogram-settings.md日期直方图设置
line-chart-legend-settings.md图例设置，包括统计信息（折线图/面积图）
line-chart-style-settings.md样式设置（折线图/面积图）

创建新的图表页面时，请更新 lens.md，添加指向该页面的链接，并删除任何重复内容。

文件位置和 frontmatter

将文件放在 explore-analyze/visualize/charts/<chart-type>.md，并使用以下 frontmatter：

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

图表特定维度

图表类型主要维度其他维度
饼图 / 圆环图按切片拆分、指标（无）
条形图 / 折线图 / 面积图水平轴、垂直轴拆分
指标主要指标次要指标、最大值
仪表图指标最小值、最大值、目标
表格指标、行按指标拆分

页面结构

请严格遵循以下章节顺序。每个图表页面都应保持一致。

1. 标题和简介
# Build <chart type> charts with {{kib}}
  • 用一段话（2-3 句）说明图表的用途以及适用场景。重点介绍目的。
  • 加入具体且可执行的限制条件（例如，“切片数量最多为 6 个时效果最佳”）。避免泛泛的建议。
  • 不要单独创建“适用场景”章节。
  • 添加一行：You can create <chart type> charts in {{kib}} using [**Lens**](../lens.md).
  • 添加一张展示代表性示例的主图。
2. “构建 图表”部分

在步骤导航前加入先决条件代码片段：

:::{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. 高级场景（可选）

仅在介绍用户不容易自行发现的非显而易见技巧时添加：

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

不要创建仅仅是“使用不同字段绘制图表”的场景。对于较简单的图表类型，Examples 部分已经足够。

添加场景时：

  • 每个场景都使用独立的 ## 或 ### 标题，并带有锚点 ID。
  • 尽可能使用基于 Kibana Sample Data 的具体示例。
示例数据注意事项
  • Web 日志中的 response 字段是 text 类型字段——KQL 过滤器必须使用模式匹配（response: 2*），不能使用数值比较。
  • 在示例电商数据中，taxful_total_price 和 taxless_total_price 的值相同。
  • 可用于比较的数值字段很少。当示例数据不支持某个场景时，请使用包含真实字段名称的概念性示例，并添加 :::note 说明用户需要根据自己的数据进行调整。
4. “ settings”部分

按维度/面板组织文档，说明 Lens 编辑器中的每一项配置选项。

每个维度的结构如下：

### <Dimension> settings [<dimension>-settings]

每个维度都使用两个顶级定义列表项：**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。

Legend settings 因图表类型而异：

设置XY 图表分区图表备注
可见性是是Auto / Show / Hide
位置是否分区图表不会传递 location
统计数据是否由 defaultLegendStats 控制
嵌套图例否是（>1 个组）需要多个 Group by 维度
标签截断是是
宽度是是UI 标签是“Width”，不是“Legend size”
5. “ examples”部分
  • 使用 Kibana Sample Data 编写 2–4 个真实场景示例。
  • 使用定义列表格式，并为示例标题加粗。
  • 每个示例的结构：
    • * Example based on: <sample data set name>
    • 将配置项作为项目符号列出（Slice by、Metric、Style、Legend 等）
    • 添加结果图片，并使用 "=60%" 或 "=70%" 设置大小
  • 展示不同功能（例如，基本配置、环形图变体、过滤器、多个指标）。

图表页面专属格式规范

常规语法请参阅 docs-syntax-help 技能。以下约定仅适用于图表页面：

图片
  • 存储在 explore-analyze/images/<image-name>.png
  • 使用以下格式引用：![Alt text](/explore-analyze/images/<image-name>.png "=60%")
  • 尺寸：较小的内嵌图片使用 "=50%"，示例使用 "=60%"，设置截图使用 "=70%"。
  • 替代文本应具有描述性，不要使用“截图”。
图标
图标语法用途
样式／画笔{icon}\brush``样式设置面板
图层设置{icon}\app_management``图层设置（9.3+／Serverless）
操作菜单{icon}\boxes_horizontal``图层操作菜单（9.0-9.2）
添加图层{icon}\plus_in_square``添加图层按钮

图例图标请使用：![Legend icon](/explore-analyze/images/kibana-legend-icon.svg "")

交叉引用
  • 其他图表类型：[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)
内部链接

从操作步骤链接到设置章节：

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

在适用时，从最佳实践链接到高级场景。

变量

使用 {{kib}}（Kibana）、{{es}}（Elasticsearch）、{{data-source}}（数据视图／数据源）。

检查清单

  • Frontmatter 包含 navigation_title 和 description
  • Hero 图片已存在且已被引用
  • “创建图表”步骤导航器使用标准的 Access Lens／Save 步骤
  • 在步骤导航器前加入先决条件片段
  • 所有设置均已对照 Kibana 源代码验证（使用 lens-chart-settings 技能）
  • Lens 编辑器中的所有设置均已记录在“设置”章节
  • 在适用处加入共享片段（不重复）
  • 示例使用 Kibana 示例数据并包含图片
  • 从操作步骤添加指向设置章节的内部链接
  • 从最佳实践链接到相关高级场景
  • 更新 lens.md，使其链接到新页面

评论

支持 Markdown