Skip to content

图表

图表有助于传达不同技术组件之间的复杂关系和相互连接，并且是项目文档的重要补充。Material for MkDocs 集成了Mermaid.js，这是一个非常流行和灵活的绘图解决方案。

配置

8.2.0

此配置启用了对Mermaid.js图表的原生支持。当页面包含mermaid代码块时，Material for MkDocs 将自动初始化 JavaScript 运行时：

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

无需进一步配置。与自定义集成相比的优势：

  • 与即时加载一起使用，无需任何额外的努力
  • 图表自动使用在mkdocs.yml中定义的字体和颜色1
  • 可以使用附加样式表自定义字体和颜色
  • 支持明亮和暗黑两种颜色方案 - 在此页面上试试吧！

尽管所有Mermaid.js功能都应该可以直接使用，但 Material for MkDocs 当前仅调整流程图、序列图、类图、状态图和实体关系图的字体和颜色。有关为什么当前未为所有图表实现此功能的更多信息，请参见其他图表部分。

使用方法

使用流程图

流程图是表示工作流程或过程的图表。各种步骤被渲染为不同类型的节点，并通过边连接，描述了步骤的必要顺序：

Flow chart
``` mermaid
graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];
```

graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];

使用序列图

序列图描述了多个对象或参与者之间的顺序交互，包括这些参与者之间交换的消息：

Sequence diagram
``` mermaid
sequenceDiagram
  autonumber
  Alice->>John: Hello John, how are you?
  loop Healthcheck
      John->>John: Fight against hypochondria
  end
  Note right of John: Rational thoughts!
  John-->>Alice: Great!
  John->>Bob: How about you?
  Bob-->>John: Jolly good!
```

sequenceDiagram
  autonumber
  Alice->>John: Hello John, how are you?
  loop Healthcheck
      John->>John: Fight against hypochondria
  end
  Note right of John: Rational thoughts!
  John-->>Alice: Great!
  John->>Bob: How about you?
  Bob-->>John: Jolly good!

使用状态图

状态图是描述系统行为的强大工具，将其分解为有限数量的状态和这些状态之间的转换：

State diagram
``` mermaid
stateDiagram-v2
  state fork_state <<fork>>
    [*] --> fork_state
    fork_state --> State2
    fork_state --> State3

    state join_state <<join>>
    State2 --> join_state
    State3 --> join_state
    join_state --> State4
    State4 --> [*]
```

stateDiagram-v2
  state fork_state <<fork>>
    [*] --> fork_state
    fork_state --> State2
    fork_state --> State3

    state join_state <<join>>
    State2 --> join_state
    State3 --> join_state
    join_state --> State4
    State4 --> [*]

使用类图

类图是面向对象编程的核心，通过将实体建模为类以及它们之间的关系来描述系统的结构：

Class diagram
``` mermaid
classDiagram
  Person <|-- Student
  Person <|-- Professor
  Person : +String name
  Person : +String phoneNumber
  Person : +String emailAddress
  Person: +purchaseParkingPass()
  Address "1" <-- "0..1" Person:lives at
  class Student{
    +int studentNumber
    +int averageMark
    +isEligibleToEnrol()
    +getSeminarsTaken()
  }
  class Professor{
    +int salary
  }
  class Address{
    +String street
    +String city
    +String state
    +int postalCode
    +String country
    -validate()
    +outputAsLabel()  
  }
```

classDiagram
  Person <|-- Student
  Person <|-- Professor
  Person : +String name
  Person : +String phoneNumber
  Person : +String emailAddress
  Person: +purchaseParkingPass()
  Address "1" <-- "0..1" Person:lives at
  class Student{
    +int studentNumber
    +int averageMark
    +isEligibleToEnrol()
    +getSeminarsTaken()
  }
  class Professor{
    +int salary
  }
  class Address{
    +String street
    +String city
    +String state
    +int postalCode
    +String country
    -validate()
    +outputAsLabel()  
  }

使用实体关系图

实体关系图由实体类型组成，并指定实体之间存在的关系。它描述了特定领域中相关的事物：

Entity-relationship diagram
``` mermaid
erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE-ITEM : contains
  LINE-ITEM {
    string name
    int pricePerUnit
  }
  CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
```

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE-ITEM : contains
  LINE-ITEM {
    string name
    int pricePerUnit
  }
  CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

其他图表类型

除了上述列出的图表类型外，Mermaid.js还支持饼图、甘特图、用户旅程、Git 图和需求图。这些图表虽然在Mermaid.js中可以正常工作，但我们不认为它们是一个好的选择，因为它们在移动设备上效果不佳。