Back to Details

docs-lens-chart-settings

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
—

从源代码验证 Kibana Lens 图表设置

<!-- Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. Elasticsearch B.V. licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
记录 Lens 图表设置时，务必对照 Kibana 源代码核实标签、选项和渲染顺序。不要猜测 UI 标签。

Verifying Kibana Lens Chart Settings from Source Code

关键原则

When documenting Lens chart settings, always verify labels, options, and rendering order against the Kibana source code. Do NOT guess UI labels.
  1. UI 标签来自 i18n 
    defaultMessage
    字符串    ——始终提取准确的标签。
  2. JSX 中的渲染顺序 = UI 中的渲染顺序——按照它们在组件树中出现的相同顺序记录设置。
  3. 条件渲染无处不在——许多设置只会出现在特定条件下（图表类型、所选选项、维度数量）。必须追踪这些条件。
  4. 共享组件会按图表进行参数化——同一个 
    LegendSettings
    组件会根据 props，在 Treemap、Waffle 和 Pie 之间表现出不同行为。

Key Principles

源代码目录结构

—

分区图表（pie、donut、treemap、mosaic、waffle）

  1. UI labels come from i18n 
    defaultMessage
    strings     — always extract the exact label.
  2. Rendering order in JSX = rendering order in the UI — document settings in the same order they appear in the component tree.
  3. Conditional rendering is everywhere — many settings only appear under specific conditions (chart type, selected options, number of dimensions). Trace the conditions.
  4. Shared components are parameterized per chart — the same 
    LegendSettings
    component behaves differently for treemaps vs waffle vs pie based on 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
共享 Legend 组件：
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

Source Code Layout

其他图表类型

Partition charts (pie, donut, treemap, mosaic, waffle)

—
All partition-type charts share code under:
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
Shared legend component:
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/
    ：bar、line、area
  • visualizations/heatmap/
  • visualizations/gauge/
  • visualizations/metric/
  • visualizations/tagcloud/

Other chart types

验证工作流

—

第 1 步：查找图表元数据

Each chart type has its own directory under 
visualizations/
:
  • visualizations/xy/
    for bar, line, area
  • visualizations/heatmap/
  • visualizations/gauge/
  • visualizations/metric/
  • visualizations/tagcloud/
对于分区图表，请从 
partition_charts_meta.ts
开始。该文件为每种图表定义：
  • toolbar.categoryOptions
    ——Slice labels 选项（若无则为空数组）
  • toolbar.numberOptions
    ——Slice values 选项（若无则为空数组）
  • toolbar.emptySizeRatioOptions
    ——Donut hole 选项（仅 pie/donut）
  • toolbar.isDisabled
    ——是否完全禁用 Style 面板（waffle）
  • legend.defaultLegendStats
    ——启用 Legend 中的 Statistics/Show value（仅 waffle）
  • legend.hideNestedLegendSwitch
    ——隐藏 Nested 开关（waffle）
  • legend.getShowLegendDefault
    ——Auto 模式下 Legend 的默认可见性行为
  • maxBuckets
    ——Group by 维度的最大数量

Verification Workflow

第 2 步：追踪 Style 设置

Step 1: Find the chart metadata

—
For partition charts, start with 
partition_charts_meta.ts
. This file defines per-chart:
  • toolbar.categoryOptions
    — Slice labels options (or empty array if none)
  • toolbar.numberOptions
    — Slice values options (or empty array if none)
  • toolbar.emptySizeRatioOptions
    — Donut hole options (pie/donut only)
  • toolbar.isDisabled
    — Whether the Style panel is disabled entirely (waffle)
  • legend.defaultLegendStats
    — Enables Statistics/Show value in legend (waffle only)
  • legend.hideNestedLegendSwitch
    — Hides the Nested toggle (waffle)
  • legend.getShowLegendDefault
    — Default legend visibility behavior for Auto mode
  • maxBuckets
    — Maximum Group by dimensions
读取 
toolbar/style_settings.tsx
，了解 Style 面板的结构：
  • 如果存在 
    emptySizeRatioOptions
    → 渲染 Appearance 折叠面板 + Titles and text 折叠面板
  • 如果不存在 → 仅直接渲染 
    PartitionTitlesAndTextSettings
    （无子标题）
然后读取 
toolbar/titles_and_text_settings.tsx
：
  • categoryOptions
    渲染为第一个按钮组（标签：检查 i18n 键 
    xpack.lens.pieChart.labelSliceLabels
    ）
  • numberOptions
    渲染为第二个按钮组（标签：检查 i18n 键 
    xpack.lens.pieChart.sliceValues
    ）
  • 如果 
    numberDisplay === 'percent'
    ，则会出现 Decimal places 输入框
如果 
categoryOptions
为空，则隐藏第一个按钮组。如果 
numberOptions
为空，则隐藏第二个按钮组。如果 
isDisabled
为 true，则整个部分会被禁用或隐藏。

Step 2: Trace the Style settings

第 3 步：追踪 Legend 设置

Read 
toolbar/style_settings.tsx
to understand the Style panel structure:
  • If 
    emptySizeRatioOptions
    exists → renders Appearance accordion + Titles and text accordion
  • If not → renders only 
    PartitionTitlesAndTextSettings
    directly (no sub-headers)
Then read 
toolbar/titles_and_text_settings.tsx
:
  • categoryOptions
    renders as the first button group (label: check i18n key 
    xpack.lens.pieChart.labelSliceLabels
    )
  • numberOptions
    renders as the second button group (label: check i18n key 
    xpack.lens.pieChart.sliceValues
    )
  • If 
    numberDisplay === 'percent'
    , a Decimal places input appears
If 
categoryOptions
is empty, the first button group is hidden. If 
numberOptions
is empty, the second button group is hidden. If 
isDisabled
is true, the entire section is disabled/hidden.
读取 
toolbar/legend_settings.tsx
（分区图表包装器），查看传递给共享 
LegendSettings
组件的 props。需要检查的关键 props：
Prop作用验证方式
legendOptions
可见性选项（Auto/Show/Hide）所有分区图表始终存在
position
仅在同时传入 
location
时渲染		分区图表不传入 
location
→ 隐藏 Position
renderNestedLegendSwitch
Nested 开关
!hideNestedLegendSwitch && groups > 1
allowedLegendStats
Statistics/Show value仅当图表元数据中定义了 
defaultLegendStats
legendSize
/ 
onLegendSizeChange
Width 下拉菜单当 
isVerticalLegend
为 true 时渲染
shouldTruncate
/ 
onTruncateLegendChange
Label truncation 开关Legend 未隐藏时始终存在
showAutoLegendSizeOption
尺寸下拉菜单中的 Auto仅用于 8.3 之前的可视化

Step 3: Trace the Legend settings

第 4 步：确定渲染顺序

Read 
toolbar/legend_settings.tsx
(partition wrapper) to see what props are passed to the shared 
LegendSettings
component. Key props to check:
PropWhat it controlsHow to verify
legendOptions
Visibility options (Auto/Show/Hide)Always present for all partition charts
position
Only renders if 
location
is also passed		Partition charts do NOT pass 
location
→ Position hidden
renderNestedLegendSwitch
Nested toggle
!hideNestedLegendSwitch && groups > 1
allowedLegendStats
Statistics/Show valueOnly if 
defaultLegendStats
defined in chart meta
legendSize
/ 
onLegendSizeChange
Width dropdownRenders if 
isVerticalLegend
is true
shouldTruncate
/ 
onTruncateLegendChange
Label truncation toggleAlways present when legend not hidden
showAutoLegendSizeOption
Auto in size dropdownOnly for pre-8.3 visualizations
从头到尾读取共享的 
legend_settings.tsx
JSX。对于分区图表（无 
location
prop），实际渲染顺序为：
  1. Visibility（始终显示）
  2. Width（Legend 未隐藏时，通过 LegendSizeSettings 渲染）
  3. Label truncation + Line limit（Legend 未隐藏时）
  4. Nested（Legend 未隐藏、有多个组且未设置 
    hideNestedLegendSwitch
    时）
不会为分区图表渲染的设置：
  • Position——需要 
    location
    prop（只有 XY 图表传入）
  • Statistics——要求 
    allowedLegendStats.length > 1
  • Show value——要求恰好有 1 个类型为 Value/CurrentAndLastValue 的允许 Legend 统计项

Step 4: Determine rendering order

第 5 步：验证选项标签

Read the shared 
legend_settings.tsx
JSX top to bottom. For partition charts (no 
location
prop), the actual rendering order is:
  1. Visibility (always)
  2. Width (when legend not hidden, via LegendSizeSettings)
  3. Label truncation + Line limit (when legend not hidden)
  4. Nested (when legend not hidden AND multiple groups AND not hideNestedLegendSwitch)
Settings that do NOT render for partition charts:
  • Position — requires 
    location
    prop (only XY charts pass this)
  • Statistics — requires 
    allowedLegendStats.length > 1
  • Show value — requires exactly 1 allowed legend stat of type Value/CurrentAndLastValue
对于每个按钮组或下拉菜单，检查选项数组中的 
label
或 
inputDisplay
。常见误区：
你可能以为实际 UI 标签来源
"Labels""Slice labels"
xpack.lens.pieChart.labelSliceLabels
"Values""Slice values"
xpack.lens.pieChart.sliceValues
"Legend size""Width"
xpack.lens.shared.legendSizeSetting.label
"Truncate""Label truncation"
xpack.lens.shared.labelTruncation
"Max lines""Line limit"
xpack.lens.shared.maxLinesLabel
"Show"（Legend）"Show"
xpack.lens.pieChart.legendVisibility.show

Step 5: Verify option labels

快速参考：各图表之间的差异

For each button group or dropdown, check the 
label
or 
inputDisplay
in the options array. Common pitfalls:
What you might assumeActual UI labelSource
"Labels""Slice labels"
xpack.lens.pieChart.labelSliceLabels
"Values""Slice values"
xpack.lens.pieChart.sliceValues
"Legend size""Width"
xpack.lens.shared.legendSizeSetting.label
"Truncate""Label truncation"
xpack.lens.shared.labelTruncation
"Max lines""Line limit"
xpack.lens.shared.maxLinesLabel
"Show" (legend)"Show"
xpack.lens.pieChart.legendVisibility.show
功能Pie/DonutTreemapMosaicWaffle
Slice labelsHide/Inside/AutoHide/Show（无）（无）
Slice valuesHide/Integer/PercentageHide/Integer/PercentageHide/Integer/Percentage（无）
Donut hole是否否否
Style 面板被禁用否否否是
Legend Position否否否否
Legend Width是是是是
Nested legend是（>1 个组）是（>1 个组）是（>1 个组）否
Show value否否否是
Statistics否否否否
Legend 默认可见性Auto 在 bucket > 1 时显示Auto 隐藏Auto 隐藏Auto 始终显示
Group by 维度上限3221
颜色映射仅第一个 Group by仅第一个 Group by垂直轴Group by

Quick Reference: Per-Chart Differences

需要避免的常见错误

FeaturePie/DonutTreemapMosaicWaffle
Slice labelsHide/Inside/AutoHide/Show(none)(none)
Slice valuesHide/Integer/PercentageHide/Integer/PercentageHide/Integer/Percentage(none)
Donut holeYesNoNoNo
Style panel disabledNoNoNoYes
Legend PositionNoNoNoNo
Legend WidthYesYesYesYes
Nested legendYes (>1 group)Yes (>1 group)Yes (>1 group)No
Show valueNoNoNoYes
StatisticsNoNoNoNo
Default legend visibilityAuto shows when >1 bucketAuto hidesAuto hidesAuto shows always
Max Group by dimensions3221
Color mappingFirst Group by onlyFirst Group by onlyVertical axisGroup by
  1. 误以为分区图表存在 Position——并不存在。只有 XY 类型的图表才有 Position。
  2. 使用 "Legend size" 而不是 "Width"——实际标签是 "Width"。
  3. 在 Width 选项中加入 Auto——Auto 只会在 8.3 之前的可视化中显示。
  4. 为非 waffle 图表记录 Statistics——只有 waffle 定义了 
    defaultLegendStats
    。
  5. 误以为所有图表都有 "Titles and text" 子标题——仅当定义了 
    emptySizeRatioOptions
    时才会出现（pie/donut）。
  6. 弄错 Nested legend 的条件——它要求 
    hideNestedLegendSwitch !== true
    ，并且有多个 Group by 维度。
  7. 误以为颜色映射适用于所有 Group by 层级——只有第一个维度可用。

Common Mistakes to Avoid

—
  1. Assuming Position exists for partition charts — it doesn't. Only XY-type charts have Position.
  2. Using "Legend size" instead of "Width" — the actual label is "Width".
  3. Including Auto in Width options — Auto only shows for pre-8.3 visualizations.
  4. Documenting Statistics for non-waffle charts — only waffle has 
    defaultLegendStats
    .
  5. Assuming "Titles and text" sub-header exists for all charts — it only appears when 
    emptySizeRatioOptions
    is defined (pie/donut).
  6. Getting the Nested legend condition wrong — it requires both 
    hideNestedLegendSwitch !== true
    AND multiple Group by dimensions.
  7. Assuming color mapping works on all Group by levels — only available on the first dimension.
—