添加新图表 📊

🌐 Adding a New Diagram/Chart 📊

示例

🌐 Examples

请参考以下 PR，了解如何使用 Langium 添加新的图表语法。

🌐 Please refer to the following PRs on how to use Langium to add a new diagram grammar.

• https://github.com/mermaid-js/mermaid/pull/4839
• https://github.com/mermaid-js/mermaid/pull/4751

警告

以下步骤仍在进行中，将会很快更新。

步骤 1：语法与解析

🌐 Step 1: Grammar & Parsing

步骤 2：渲染

🌐 Step 2: Rendering

编写一个渲染器，根据解析过程中找到的数据渲染图表。要查看示例，请查看 sequenceRenderer.js，而不是流程图渲染器，因为这是一个更通用的示例。

🌐 Write a renderer that given the data found during parsing renders the diagram. To look at an example look at sequenceRenderer.js rather than the flowchart renderer as this is a more generic example.

将渲染器放入图表文件夹中。

🌐 Place the renderer in the diagram folder.

步骤 3：检测新图表类型

🌐 Step 3: Detection of the new diagram type

第二步是向 diagram-api/detectType.ts 中的 detectType 添加检测新图表类型的功能。检测应该返回新图表类型的一个键。 此键将用于 aria roledescription，因此它应该是一个能够清楚描述图表类型的单词。例如，如果你的新图表使用 UML 部署图，一个好的键可以是 "UMLDeploymentDiagram"，因为辅助技术（如屏幕阅读器）会将其读作“U-M-L Deployment diagram”。另一个好的键可以是 "deploymentDiagram"，因为它会被读作“Deployment Diagram”。一个不好的键会是 "deployment"，因为它不足以描述图表。

🌐 The second thing to do is to add the capability to detect the new diagram to type to the detectType in diagram-api/detectType.ts. The detection should return a key for the new diagram type. This key will be used to as the aria roledescription, so it should be a word that clearly describes the diagram type. For example, if your new diagram uses a UML deployment diagram, a good key would be "UMLDeploymentDiagram" because assistive technologies such as a screen reader would voice that as "U-M-L Deployment diagram." Another good key would be "deploymentDiagram" because that would be voiced as "Deployment Diagram." A bad key would be "deployment" because that would not sufficiently describe the diagram.

请注意，图表类型键不必与为语法选择的图表关键字相同，但如果它们相同会更有帮助。

🌐 Note that the diagram type key does not have to be the same as the diagram keyword chosen for the grammar, but it is helpful if they are the same.

图表的常见部分

🌐 Common parts of a diagram

不同类型的图表之间有一些共同的特性。我们尽量将图表标准化，使其对终端用户的使用尽可能相似。共同点包括：

🌐 There are a few features that are common between the different types of diagrams. We try to standardize the diagrams that work as similar as possible for the end user. The commonalities are:

• 指令，是一种从图表代码内部修改图表配置的方法。
• 无障碍性，指作者为使用屏幕阅读器访问带有图表的文本的人提供标题和描述等额外信息的方式。
• 主题，在 Mermaid 中有一种常见的方法可以修改图表的样式。
• 注释应遵循Mermaid标准

以下是一些关于如何处理这些不同字段的建议。

🌐 Here are some pointers on how to handle these different areas.

可访问性

🌐 Accessibility

Mermaid 会自动为图表的 SVG HTML 元素添加以下可访问性信息：

🌐 Mermaid automatically adds the following accessibility information for the diagram SVG HTML element:

• aria-roledescription
• 可访问标题
• 可访问描述

aria-roledescription

aria-roledescription 会自动设置为图表类型 并插入到 SVG 元素中。

🌐 The aria-roledescription is automatically set to the diagram type and inserted into the SVG element.

请参阅 可访问丰富互联网应用 W3 标准 中的 aria-roledescription 定义

🌐 See the definition of aria-roledescription in the Accessible Rich Internet Applications W3 standard.

可访问的标题和描述

🌐 accessible title and description

可访问标题和描述的语法在可访问性文档部分中有描述。

🌐 The syntax for accessible titles and descriptions is described in the Accessibility documentation section.

设置标题和描述的功能由一个通用模块提供。这是在 flowDb.js 中的导入方式:

🌐 The functions for setting title and description are provided by a common module. This is the import in flowDb.js:

import {
  setAccTitle,
  getAccTitle,
  getAccDescription,
  setAccDescription,
  clear as commonClear,
} from '../../commonDb';

无障碍标题和描述会在 mermaidAPI 的 render 函数中插入到 SVG 元素中。

🌐 The accessibility title and description are inserted into the SVG element in the render function in mermaidAPI.

主题化

🌐 Theming

Mermaid 支持主题并且有一个集成的主题引擎。你可以在文档中了解更多关于如何使用主题的信息。

🌐 Mermaid supports themes and has an integrated theming engine. You can read more about how the themes can be used in the docs.

在向图表添加主题时，关键在于代码中的几个重要位置。

🌐 When adding themes to a diagram it comes down to a few important locations in the code.

样式引擎的入口点在 src/styles.js。当 Mermaid 将样式应用到图表时，会调用 getStyles 函数。

🌐 The entry point for the styling engine is in src/styles.js. The getStyles function will be called by Mermaid when the styles are being applied to the diagram.

此函数将依次调用一个函数 _ 你的图表应提供 _，该函数返回新图表的 CSS。这个图表特定的函数，也通常被称为 getStyles，位于 src/diagrams 下你的图表文件夹中，文件名应为 styles.js。getStyles 函数将以主题选项作为参数进行调用，如下例所示：

🌐 This function will in turn call a function your diagram should provide returning the css for the new diagram. The diagram specific, also which is commonly also called getStyles and located in the folder for your diagram under src/diagrams and should be named styles.js. The getStyles function will be called with the theme options as an argument like in the following example:

const getStyles = (options) =>
  `
    .line {
      stroke-width: 1;
      stroke: ${options.lineColor};
      stroke-dasharray: 2;
    }
    // ...
    `;

请注意，你需要将你的函数提供给主 getStyles，通过将其添加到 src/styles.js 中的 themes 对象，就像在提供的示例中的 xyzDiagram 一样：

🌐 Note that you need to provide your function to the main getStyles by adding it into the themes object in src/styles.js like in the xyzDiagram in the provided example:

const themes = {
  flowchart,
  'flowchart-v2': flowchart,
  sequence,
  xyzDiagram,
  //...
};

颜色的实际选项和值是在 src/theme/theme-[xyz].js 中定义的。如果你在现有的主题文件中提供图表所需的选项，那么主题设置就能顺利运行，不会出现问题。

🌐 The actual options and values for the colors are defined in src/theme/theme-[xyz].js. If you provide the options your diagram needs in the existing theme files then the theming will work smoothly without hiccups.

示例

🌐 Examples

@mermaid-js/examples 包含了一系列示例，这些示例被像 mermaid.live 这样的工具使用，帮助用户快速上手新的图表。

🌐 The @mermaid-js/examples package contains a collection of examples that are used by tools like mermaid.live to help users get started with the new diagram.

你可以复制一个现有的示例图文件，例如：packages/examples/src/examples/flowchart.ts，然后根据你的图表的具体细节进行修改。

🌐 You can duplicate an existing diagram example file, eg: packages/examples/src/examples/flowchart.ts, and modify it with details specific to your diagram.

然后你可以导入 packages/examples/src/index.ts 文件中的示例，并将其添加到 examples 数组中。

🌐 Then you can import the example in the packages/examples/src/index.ts file and add it to the examples array.

每个图表至少应有一个示例，并且该示例应标记为默认。最好添加更多示例以展示图表的不同特性。

🌐 Each diagram should have at least one example, and that should be marked as default. It is good to add more examples to showcase different features of the diagram.