新增圖表/圖示 📊

範例

請參考以下 PR，了解如何使用 Langium 新增新的圖表語法。

警告

以下步驟仍在開發中，將很快更新。

步驟 1：語法 & 解析

步驟 2：渲染

編寫一個渲染器，在解析期間給定找到的資料來渲染圖表。要查看範例，請查看 sequenceRenderer.js 而不是流程圖渲染器，因為這是一個更通用的範例。

將渲染器放置在 diagram 資料夾中。

步驟 3：偵測新的圖表類型

第二件事是將偵測新圖表類型的功能新增到 diagram-api/detectType.ts 中的 detectType。偵測應返回新圖表類型的鍵。此鍵將用作 aria roledescription，因此它應該是一個清楚描述圖表類型的詞。例如，如果您的新圖表使用 UML 部署圖，一個好的鍵是 "UMLDeploymentDiagram"，因為螢幕閱讀器等輔助技術會將其讀作「U-M-L 部署圖」。另一個好鍵是 "deploymentDiagram"，因為它會被讀作「部署圖」。一個不好的鍵是 "deployment"，因為它無法充分描述圖表。

請注意，圖表類型鍵不必與為語法選擇的圖表關鍵字相同，但如果它們相同則會很有幫助。

圖表的常見部分

不同類型的圖表之間有一些共同的功能。我們嘗試將圖表標準化，使最終使用者盡可能地以相似的方式操作。共同點是

指令，一種從圖表程式碼中修改圖表配置的方式。
無障礙功能，一種讓作者為使用螢幕閱讀器存取帶有圖表的文字的人提供標題和描述等額外資訊的方式。
主題，有一種通用的方法可以修改 Mermaid 中圖表的樣式。
註解應遵循 Mermaid 標準

以下是如何處理這些不同領域的一些指標。

無障礙功能

Mermaid 會自動為圖表 SVG HTML 元素新增以下無障礙功能資訊

aria-roledescription
可存取的標題
可存取的描述

aria-roledescription

aria-roledescription 會自動設定為圖表類型並插入 SVG 元素中。

請參閱 aria-roledescription 的定義，位於可存取豐富網際網路應用程式 W3 標準。

可存取的標題和描述

可存取標題和描述的語法在無障礙功能文件章節中說明。

設定標題和描述的函式由通用模組提供。這是 flowDb.js 中的匯入

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

可存取的標題和描述會插入到 mermaidAPI 中 render 函式的 SVG 元素中。

主題

Mermaid 支援主題，並具有整合的主題引擎。您可以閱讀更多關於如何使用主題的資訊在文件中。

當向圖表新增主題時，它會歸結為程式碼中的幾個重要位置。

樣式引擎的進入點在 src/styles.js 中。當樣式應用於圖表時，Mermaid 會呼叫 getStyles 函式。

此函式會反過來呼叫一個函式，您的圖表應提供該函式，返回新圖表的 CSS。圖表專用的 CSS，通常也稱為 getStyles，位於您的圖表資料夾 src/diagrams 下，且應命名為 styles.js。呼叫 getStyles 函式時會將主題選項作為參數，如以下範例所示

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

請注意，您需要將您的函式提供給主要的 getStyles，方法是將其新增到 src/styles.js 中 themes 物件中，如提供的範例中的 xyzDiagram

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

色彩的實際選項和值在 src/theme/theme-[xyz].js 中定義。如果您在現有的主題檔案中提供圖表所需的選項，則主題功能將順利運作，不會發生問題。

新增圖表/圖示 📊 ​

範例 ​

步驟 1：語法 & 解析 ​

步驟 2：渲染 ​

步驟 3：偵測新的圖表類型 ​

圖表的常見部分 ​

無障礙功能 ​

aria-roledescription ​

可存取的標題和描述 ​

主題 ​