添加新图表 📊

¥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 角色描述，因此它应该是一个能够清晰描述图表类型的词。例如，如果你的新图表使用 UML 部署图，那么 "UMLDeploymentDiagram" 是一个不错的键，因为屏幕阅读器等辅助技术会将其读作 "U-M-L 部署图。"。另一个不错的键是 "deploymentDiagram"，因为它会被读作 "部署图。"。一个不好的键是 "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.

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

¥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:

• 指令是一种在图表代码中修改图表配置的方法。

  ¥Directives, a way of modifying the diagram configuration from within the diagram code.

• 可访问性，作者可以通过这种方式向使用屏幕阅读器访问带有图表的文本的用户提供标题和描述等附加信息。

  ¥Accessibility, a way for an author to provide additional information like titles and descriptions to people accessing a text with diagrams using a screen reader.

• 主题，在 Mermaid 中修改图表样式是一种常用的方法。

  ¥Themes, there is a common way to modify the styling of diagrams in Mermaid.

• 评论应遵循 Mermaid 标准

  ¥Comments should follow mermaid standards

以下是一些关于如何处理这些不同区域的指示。

¥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

• 无障碍标题

  ¥accessible title

• 无障碍描述

  ¥accessible description

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 下，应命名为 style.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;
    }
    // ...
    `;

请注意，你需要将函数添加到 src/styles.js 中的主题对象中，以便将其提供给主 getStyles 函数，就像示例中的 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.