菜单
文档面包屑箭头 Writers' Toolkit面包屑箭头 结构面包屑箭头 主题类型面包屑箭头 可视化
开源
上次审阅：2024 年 6 月 12 日

可视化主题

一个*可视化*主题概述了一种可视化类型、其用例以及用户界面 (UI) 中可用的显示选项。可视化主题始终包含概念和参考内容，并可能包含任务内容。

可视化主题中可以包含以下类型的内容

  • 可视化功能的高级概述及用例
  • 该可视化特有的 UI 选项描述（通用选项单独记录）
  • 有助于用户理解 UI 交互或难以描述的 UI 的屏幕截图
  • 根据需要，提供如何在特殊用例中使用可视化的指导
  • 最佳实践指南

可视化主题不包含

  • 教程内容

大多数可视化需要数据源；不需要数据源的可视化称为*小部件*。因此，小部件比典型的可视化需要更少的文档。这两者的结构在以下章节中解释

可视化主题结构

以下内容适用于需要数据源的可视化。对于不需要数据源的可视化，请参阅 小部件主题结构。

可视化主题包含以下元素。可选章节用星号标记

  • 主题标题 - 可视化主题标题与 UI 中该可视化的名称相同（例如，“时间序列”）。不要在标题中添加“面板”或“可视化”等词语。

  • 介绍 - 包含一段介绍，说明该可视化类型可以帮助用户做什么。

  • 主要视图 - 添加清晰的屏幕截图，展示该可视化显示典型用例。

  • 正文 - 正文可根据需要包含任务/操作方法信息。正文包含以下章节

    • 配置 * - 链接到使用 youtube 短代码描述基本配置示例的 YouTube 视频。

    • Grafana Play 短代码* - 使用 docs/play 短代码添加指向 Grafana Play 中可视化代表性示例的链接。将此短代码放在主图像或配置视频之后。

    • 支持的数据格式 - 提供有关该可视化类型支持哪些数据格式的指导。如果需要，添加示例。

    • 特殊说明或配置选项* - 添加特殊配置或说明以使用可视化完成相关任务。每个都应有自己的标题，除非将其中一些归入一个标题下更合理。

    • 配置选项 - 这是可视化所有配置选项的参考章节。使用 config-options-intro.md 共享文件为此章节添加介绍文本。将选项嵌套在此标题下。

      • 选项 - 对于面板编辑器窗格中的每个可展开选项章节，在主题中添加一个章节，其名称与 UI 章节名称相同，后跟“选项”一词。例如，如果 UI 中一个下拉选项章节名为“轴”，则在主题中包含一个名为“轴选项”的标题。按它们在 UI 中出现的顺序列出这些章节。

        在包含许多配置选项的章节中，将其放入表格中，并从表格链接到更长的描述。对大多数可视化通用的以下选项，使用提供的共享文件

        • 数据链接

        • 字段覆盖

        • 图例

        • 面板选项

        • 标准选项

        • 阈值

        • 工具提示

        • 值映射

          如果一个选项有多个共享文件，请使用与特定可视化 UI 精确匹配的文件。如果没有匹配项，请手动记录选项或创建另一个共享文件。

以下图片显示了页面级目录和（缩略版）页面可能的样子

Example of a visualization page TOC
Annotated example of a visualization page's structure

小部件主题结构

*小部件*是不需要数据源的可视化。这些可视化的选项要少得多，也不需要太多解释。对于需要数据源的可视化，请参阅 可视化主题结构。

小部件主题包含以下元素

  • 主题标题 - H1。小部件主题标题与 UI 中该小部件的名称相同（例如，“时间序列”）。不要在标题中添加“面板”、“可视化”或“小部件”等词语。

  • 介绍 包含一段介绍，说明该可视化类型可以帮助用户做什么。

  • 主要视图 - 添加清晰的屏幕截图，展示该可视化显示典型用例。

  • 正文 - 正文可根据需要包含任务/操作方法信息。正文必须包含以下章节

    • 选项 - 对于面板编辑窗格中的每个可展开选项章节，在主题中添加一个章节，其名称与 UI 章节名称相同，后跟“选项”一词。例如，如果 UI 中一个下拉选项章节名为“轴”，则在主题中包含一个名为“轴选项”的章节。

命名约定

撰写可视化或小部件相关内容时使用

  • 名词形式
  • 小写，除非位于句首

例如

markdown 
Use bar charts to graph categorical data.
A bar chart lets you graph categorical data.

在某些情况下，您应该使用可视化的形容词形式。以下情况应如此处理

  • 可视化的名称本身就是复数形式
  • 由于该词的其他用法，容易引起混淆
  • 您在可视化文档之外引用某个可视化

通过添加“可视化”一词来做到这一点。例如

markdown 
Use time series visualizations to display time-series data as a graph.
A traces visualization turns traces data into a diagram.
Text visualizations allow you to directly include text or HTML in your dashboards.
Click the **Enable node graph** switch to display a node graph visualization above the trace view.

编写可视化主题

要编写可视化或小部件主题，请按照以下步骤操作。

  1. 在 grafana/grafana 仓库中，转到 docs/sources/panels-visualizations/visualizations 目录。

  2. 在 visualizations 目录中，按照以下命名约定创建一个目录

    • 使用可视化类型的名称
    • 使用小写字母
    • 在单词之间添加连字符

  3. 在该目录中，创建一个 index.md 文件。

  4. 将 可视化模板 的内容复制到您的新索引文件中。

    有关可添加到概念主题的内容类型的更多信息，请参阅 可视化主题。

  5. 向 index.md 文件添加其他 front matter。

    有关 front matter 的更多信息，请参阅 Front matter。

可视化主题示例

请参阅以下主题获取可视化主题示例

可视化模板

准备编写时，复制一份 可视化模板 并添加您的内容。