docs-lens-chart-settings

根据源代码验证 Kibana Lens 图表设置

记录 Lens 图表设置时，始终根据 Kibana 源代码验证标签、选项和渲染顺序。切勿猜测 UI 标签。

核心原则

1. UI 标签来自 i18n defaultMessage 字符串——始终提取准确的标签。
2. JSX 中的渲染顺序 = UI 中的渲染顺序——按组件树中显示的顺序记录设置。
3. 条件渲染无处不在——许多设置仅在特定条件下显示（图表类型、所选选项、维度数量）。请追踪这些条件。
4. 共享组件会针对每种图表进行参数化——同一个 LegendSettings 组件会根据 props，在树图、华夫饼图和饼图中的行为各不相同。

源代码布局

分区图表（饼图、圆环图、树图、马赛克图、华夫饼图）

所有分区类型的图表共用以下目录中的代码：

x-pack/platform/plugins/shared/lens/public/visualizations/partition/
├── partition_charts_meta.ts          # Per-chart config (toolbar options, legend config)
├── toolbar/
│   ├── style_settings.tsx            # Orchestrates Style panel sections
│   ├── titles_and_text_settings.tsx  # Slice labels + Slice values options
│   ├── appearance_settings.tsx       # Donut hole (pie/donut only)
│   └── legend_settings.tsx           # Partition-specific legend wrapper

共享图例组件：

x-pack/platform/plugins/shared/lens/public/shared_components/legend/
├── legend_settings.tsx               # Main legend settings (Visibility, Size, Truncation, Nested, Stats)
├── location/legend_location_settings.tsx  # Position (only when `location` prop is defined)
└── size/legend_size_settings.tsx     # Width/Size dropdown

其他图表类型

每种图表类型在 visualizations/ 下都有自己的目录：

• visualizations/xy/ 用于柱状图、折线图、面积图
• visualizations/heatmap/
• visualizations/gauge/
• visualizations/metric/
• visualizations/tagcloud/

验证工作流

第 1 步：查找图表元数据

对于分区图表，请从 partition_charts_meta.ts 开始。此文件定义了每种图表的：

• toolbar.categoryOptions——切片标签选项（如果没有则为空数组）
• toolbar.numberOptions——切片值选项（如果没有则为空数组）
• toolbar.emptySizeRatioOptions——圆环图孔洞选项（仅限饼图/圆环图）
• toolbar.isDisabled——是否完全禁用样式面板（华夫饼图）
• legend.defaultLegendStats——启用图例中的“统计信息/显示值”（仅限华夫饼图）
• legend.hideNestedLegendSwitch——隐藏“嵌套”切换开关（华夫饼图）
• legend.getShowLegendDefault——“自动”模式下默认的图例可见性行为
• maxBuckets——“分组依据”维度的最大数量

第 2 步：追踪样式设置

阅读 toolbar/style_settings.tsx，了解样式面板结构：

• 如果存在 emptySizeRatioOptions → 渲染 外观 折叠面板和 标题和文本 折叠面板
• 如果不存在 → 直接渲染 PartitionTitlesAndTextSettings（无子标题）

然后阅读 toolbar/titles_and_text_settings.tsx：

• categoryOptions 渲染为第一个按钮组（标签：检查 i18n 键 xpack.lens.pieChart.labelSliceLabels）
• numberOptions 渲染为第二个按钮组（标签：检查 i18n 键 xpack.lens.pieChart.sliceValues）
• 如果 numberDisplay === 'percent'，则会显示 小数位数 输入框

如果 categoryOptions 为空，则隐藏第一个按钮组。如果 numberOptions 为空，则隐藏第二个按钮组。如果 isDisabled 为 true，则整个部分会被禁用/隐藏。

第 3 步：追踪图例设置

阅读 toolbar/legend_settings.tsx（分区包装组件），查看传递给共享 LegendSettings 组件的 props。需要检查的关键 props：

Prop	控制内容	验证方法
legendOptions	可见性选项（自动/显示/隐藏）	所有分区图表始终都有
position	仅在同时传入 location 时渲染	分区图表不会传入 location → 隐藏位置
renderNestedLegendSwitch	嵌套切换开关	!hideNestedLegendSwitch && groups > 1
allowedLegendStats	统计信息/显示值	仅当图表元数据中定义了 defaultLegendStats 时显示
legendSize / onLegendSizeChange	宽度下拉菜单	当 isVerticalLegend 为 true 时渲染
shouldTruncate / onTruncateLegendChange	标签截断切换开关	图例未隐藏时始终显示
showAutoLegendSizeOption	尺寸下拉菜单中的“自动”选项	仅适用于 8.3 之前的可视化

步骤 4：确定渲染顺序

从上到下阅读共享的 legend_settings.tsx JSX。对于分区图表（没有 location 属性），实际渲染顺序如下：

1. 可见性（始终显示）
2. 宽度（图例未隐藏时，通过 LegendSizeSettings 显示）
3. 标签截断 + 行数限制（图例未隐藏时显示）
4. 嵌套（图例未隐藏、分组数大于 1 且 hideNestedLegendSwitch 为 false 时显示）

分区图表不会渲染以下设置：

• 位置 — 需要 location 属性（只有 XY 图表会传入此属性）
• 统计信息 — 需要 allowedLegendStats.length > 1
• 显示值 — 需要恰好有 1 个类型为 Value/CurrentAndLastValue 的允许图例统计项

步骤 5：验证选项标签

对于每个按钮组或下拉菜单，请检查选项数组中的 label 或 inputDisplay。常见误区：

你可能以为的名称	UI 中的实际标签	来源
“标签”	“切片标签”	xpack.lens.pieChart.labelSliceLabels
“值”	“切片值”	xpack.lens.pieChart.sliceValues
“图例大小”	“宽度”	xpack.lens.shared.legendSizeSetting.label
“截断”	“标签截断”	xpack.lens.shared.labelTruncation
“最大行数”	“行数限制”	xpack.lens.shared.maxLinesLabel
（图例）“显示”	“显示”	xpack.lens.pieChart.legendVisibility.show

快速参考：各图表的差异

功能	饼图/圆环图	矩形式树图	马赛克图	华夫饼图
切片标签	隐藏/内部/自动	隐藏/显示	（无）	（无）
切片值	隐藏/整数/百分比	隐藏/整数/百分比	隐藏/整数/百分比	（无）
圆环孔洞	有	无	无	无
样式面板已禁用	否	否	否	是
图例位置	否	否	否	否
图例宽度	是	是	是	是
嵌套图例	是（分组数 > 1）	是（分组数 > 1）	是（分组数 > 1）	否
显示值	否	否	否	是
统计信息	否	否	否	否
默认图例可见性	桶数 > 1 时自动显示	自动隐藏	自动隐藏	始终自动显示
按维度分组的最大数量	3	2	2	1
颜色映射	仅第一个“按维度分组”	仅第一个“按维度分组”	垂直轴	按维度分组

应避免的常见错误

1. 认为分区图表存在“位置”选项 — 实际上没有。只有 XY 类型图表有“位置”选项。
2. 使用“图例大小”而不是“宽度” — 实际标签是“宽度”。
3. 在“宽度”选项中包含“自动” — “自动”只会出现在 8.3 之前的可视化中。
4. 为非华夫饼图记录“统计信息” — 只有华夫饼图有 defaultLegendStats。
5. 认为所有图表都有“标题和文本”子标题 — 只有定义了 emptySizeRatioOptions 的图表才会显示（饼图/圆环图）。
6. 弄错“嵌套图例”的条件 — 必须同时满足 hideNestedLegendSwitch !== true 和“按维度分组”的维度数大于 1。
7. 认为颜色映射适用于所有“按维度分组”级别 — 该功能仅适用于第一个维度。