JavaScript Katana

Hướng dẫn Mermaid.js: Tạo biểu đồ bằng văn bản (Lưu đồ, Biểu đồ tuần tự & Biểu đồ Gantt)

Thư viện Bên ngoài và Quản lý Mô-đun
佐川 直弘 | Naohiro Sagawa
By 佐川 直弘 | Naohiro Sagawa (運営者)
※記事内に広告を含みます。Amazonアソシエイトとして適格販売により収入を得ています。　

.## 1. Mermaid là gì?

目次

Tổng quan và các tính năng chính của Mermaid

Mermaid là một thư viện JavaScript cho phép bạn tạo các sơ đồ và biểu đồ bằng các định nghĩa dựa trên văn bản. Với công cụ này, bạn có thể tạo ra các sơ đồ trực quan một cách dễ dàng chỉ bằng cách viết mã. Vì nó cho phép bạn nhanh chóng tạo lưu đồ, sơ đồ tuần tự, biểu đồ Gantt và nhiều loại khác, nên Mermaid được sử dụng rộng rãi bởi các nhà phát triển phần mềm, quản lý dự án và nhiều người khác.

Một trong những điểm mạnh lớn nhất của Mermaid là bạn có thể định nghĩa các sơ đồ chỉ bằng mã. Điều này giúp việc chỉnh sửa và quản lý sơ đồ trở nên dễ dàng mà không cần dựa vào giao diện đồ họa. Mermaid cũng được tích hợp vào các nền tảng như GitHub và Notion, mang lại tính linh hoạt để sử dụng trong nhiều tình huống khác nhau.

Các trường hợp sử dụng chính và lợi ích của Mermaid

Trường hợp sử dụng

  • Tạo lưu đồ và sơ đồ tuần tự cho phát triển phần mềm.
  • Tạo biểu đồ Gantt cho việc lập kế hoạch dự án.
  • Thêm các biểu diễn trực quan vào tệp Markdown và tài liệu Wiki.

Lợi ích

  • Cú pháp đơn giản: Bạn có thể viết nó giống như mã lập trình, vì vậy ngay cả người mới bắt đầu cũng có thể sử dụng dễ dàng.
  • Quản lý dựa trên mã: Bạn có thể quản lý phiên bản bằng các công cụ kiểm soát nguồn (ví dụ: Git).
  • Tạo và cập nhật nhanh: Các thay đổi trong sơ đồ được phản ánh ngay lập tức chỉ bằng cách chỉnh sửa mã.
  • Mở rộng và tùy chỉnh: Bạn có thể tùy chỉnh thiết kế bằng CSS và mở rộng chức năng bằng JavaScript.

2. Cách sử dụng cơ bản của Mermaid

Cách cài đặt

Mermaid.js có thể được cài đặt theo hai cách: sử dụng liên kết CDN hoặc sử dụng npm.

1. Sử dụng liên kết CDN

Thêm thẻ script sau vào tệp HTML của bạn.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
  </script>
</head>
<body>
  <div class="mermaid">
    graph TD;
      A-->B;
      A-->C;
      B-->D;
      C-->D;
  </div>
</body>
</html>

2. Sử dụng npm

Nếu bạn đã có môi trường Node.js sẵn sàng, có thể cài đặt nó bằng lệnh sau.

npm install mermaid

Với cách này, bạn có thể tích hợp Mermaid như một phần của dự án JavaScript.

Cú pháp và ngữ pháp cơ bản

Với Mermaid.js, bạn có thể tạo các sơ đồ bằng cú pháp dựa trên văn bản trực quan. Dưới đây là một số ví dụ phổ biến.

1. Lưu đồ

Dưới đây là một ví dụ về định nghĩa lưu đồ.

graph TD;
  A[Start] --> B[Process 1]
  B --> C[Process 2]
  C --> D[End]

2. Sơ đồ tuần tự

Một sơ đồ tuần tự mô tả quy trình làm việc của hệ thống có thể được viết như sau.

sequenceDiagram
  participant A as User
  participant B as Server
  A->>B: Send request
  B-->>A: Return response

3. Biểu đồ Gantt

Một biểu đồ Gantt hữu ích cho việc quản lý dự án có thể được viết như sau.

gantt
  title Project Plan
  dateFormat YYYY-MM-DD
  section Planning
  Task A :a1, 2024-01-01, 10d
  Task B :a2, after a1, 7d
  Task C :a3, after a2, 5d

Các loại biểu đồ được hỗ trợ

Mermaid.js hỗ trợ các loại sơ đồ và biểu đồ sau đây.

  • Lưu đồ : Hiển thị luồng của một quy trình.
  • Sơ đồ tuần tự : Trực quan hoá các giao thức và quy trình giao tiếp.
  • Biểu đồ Gantt : Dùng cho quản lý dự án và lập lịch.
  • Sơ đồ lớp : Dùng cho thiết kế hướng đối tượng.
  • Sơ đồ trạng thái : Đại diện cho các chuyển đổi trạng thái.
  • Biểu đồ tròn : Trực quan hoá tỷ lệ phần dữ liệu.

3. Tạo biểu đồ với Mermaid.js

Cách nhúng Mermaid vào HTML

Mermaid.js có thể dễ dàng nhúng vào HTML. Thực hiện các bước dưới đây để tạo sơ đồ.

1. Cấu trúc HTML cơ bản

Mã sau đây cho thấy một ví dụ tối thiểu về việc sử dụng Mermaid.js trong một tệp HTML.

.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Mermaid Diagram</title>
  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
  </script>
</head>
<body>
  <h1>Flowchart Example</h1>
  <div class="mermaid">
    graph TD;
      A[Start] --> B[Process 1]
      B --> C[Process 2]
      C --> D[End]
  </div>
</body>
</html>

2. Hiển thị Nhiều biểu đồ

Nếu bạn muốn hiển thị nhiều biểu đồ, hãy thêm nhiều thẻ div vào HTML của bạn như sau.

<div class="mermaid">
  graph TD;
    A --> B;
    B --> C;
</div>
<div class="mermaid">
  sequenceDiagram
    participant A as User
    participant B as Server
    A->>B: Send request
    B-->>A: Return response
</div>

Khởi tạo và Cấu hình với JavaScript

1. Cài đặt Khởi tạo

Đoạn mã sau khởi tạo Mermaid.js một cách lập trình.

mermaid.initialize({
  startOnLoad: true,
  theme: 'forest',
  flowchart: { curve: 'basis' },
});

Với cấu hình này, giao diện được đổi thành forest, và các đường trong lưu đồ được tùy chỉnh để sử dụng các cạnh cong.

2. Thêm Biểu đồ một cách Động

Ví dụ sau cho thấy cách tạo một biểu đồ một cách động bằng JavaScript.

const code = `
graph LR;
  X[Start] --> Y[Next step];
  Y --> Z[End];
`;
const element = document.querySelector('#dynamicChart');
element.innerHTML = code;
mermaid.init(undefined, element);

Các ví dụ mã thực tế và Giải thích

Ví dụ 1: Tạo Biểu đồ Trình tự

<div class="mermaid">
  sequenceDiagram
    participant User as User
    participant Server as Server
    User->>Server: Data request
    Server-->>User: Data response
</div>

Ví dụ 2: Tạo Biểu đồ Gantt

<div class="mermaid">
  gantt
    title Project Schedule
    dateFormat YYYY-MM-DD
    section Development Phase
      Design :done, 2024-01-01, 2024-01-07
      Implementation :active, 2024-01-08, 2024-01-20
      Testing :2024-01-21, 2024-01-30
</div>

4. Cách sử dụng Mermaid trong WordPress

Giới thiệu và Cài đặt Plugin

Nếu bạn muốn sử dụng Mermaid.js trong WordPress, cách dễ nhất là cài đặt một plugin chuyên dụng. Dưới đây là một số tùy chọn phổ biến.

1. Plugin Mermaid – “Mermaid Markdown Syntax Highlighting”

Plugin này cho phép bạn sử dụng cú pháp Mermaid trực tiếp trong các bài viết.

Các bước Cài đặt

  1. Đăng nhập vào bảng điều khiển quản trị WordPress.
  2. Từ menu, nhấp vào Plugins → Add New.
  3. Trong ô tìm kiếm, nhập Mermaid Markdown Syntax Highlighting.
  4. Cài đặt plugin và kích hoạt nó.

Các bước Cấu hình

  1. Sau khi kích hoạt, bạn có thể điều chỉnh các tùy chọn cơ bản từ màn hình cài đặt.
  2. Tùy chỉnh các cài đặt như theme và auto-load on start.

Cách hiển thị Biểu đồ trong Bài viết

Sau khi cài đặt plugin, bạn có thể hiển thị biểu đồ trong bài viết của mình bằng các shortcode như sau.

Ví dụ: Chèn một Lưu đồ

[mermaid]
graph TD;
  A[Start] --> B[Process 1]
  B --> C[Process 2]
  C --> D[End]
[/mermaid]

Ví dụ: Chèn một Biểu đồ Trình tự

[mermaid]
sequenceDiagram
  participant User
  participant Server
  User->>Server: Send request
  Server-->>User: Return response
[/mermaid]

Ví dụ: Chèn một Biểu đồ Gantt

[mermaid]
gantt
  title Project Plan
  dateFormat YYYY-MM-DD
  section Development
    Design :done, 2024-01-01, 2024-01-07
    Implementation :active, 2024-01-08, 2024-01-20
    Testing :2024-01-21, 2024-01-30
[/mermaid]

Ghi chú và Khắc phục sự cố

1. Cách xử lý khi Biểu đồ không hiển thị

  • Nguyên nhân 1: Plugin chưa được kích hoạt đúng cách. → Kiểm tra lại cài đặt plugin và đảm bảo nó đã được bật.
  • Nguyên nhân 2: Script Mermaid.js không được tải. → Có thể xung đột với giao diện hoặc các plugin khác, vì vậy hãy tắt từng plugin một để xác định xung đột.

2. Cài đặt Thủ công mà không cần Plugin

Nếu bạn không muốn sử dụng plugin, bạn cũng có thể nhúng Mermaid.js một cách thủ công bằng cách thêm đoạn mã sau vào file functions.php của giao diện.

function add_mermaid_script() {
    echo '<script type="module">
        import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs";
        mermaid.initialize({ startOnLoad: true });
    </script>';
}
add_action('wp_footer', 'add_mermaid_script');

5. Thực Hành Tốt Nhất Khi Sử Dụng Mermaid

Cách Quản Lý Các Sơ Đồ Phức Tạp

1. Tách và Tổ Chức Mã Của Bạn

Khi tạo các sơ đồ phức tạp, hãy giữ mã của bạn được tổ chức bằng cách tuân theo các mẹo sau.

  • Thêm chú thích cho mỗi phần
    %% Start of the flowchart
graph TD;
    A[Start] --> B[Process 1]
%% Branching logic
    B --> C[Process 2]
    B --> D[Process 3]
  • Tạo mẫu và tái sử dụng chúng Đối với các dự án lớn, việc chuẩn bị các mẫu và duy trì tính nhất quán trên nhiều sơ đồ là quan trọng.

2. Quản Lý Các Sơ Đồ Trong Các Tệp Ngoài

Thay vì nhúng mã Mermaid trực tiếp vào tệp HTML hoặc Markdown, bạn có thể lưu nó trong các tệp bên ngoài. Điều này cải thiện khả năng bảo trì.

Ví dụ: Lưu mã Mermaid vào một tệp có tên diagram.mmd và tải nó từ HTML.

<div id="diagram-container"></div>
<script>
  fetch('diagram.mmd')
    .then(response => response.text())
    .then((text) => {
      const container = document.getElementById('diagram-container');
      container.innerHTML = text;
      mermaid.init(undefined, container);
    });
</script>

Tùy Chỉnh và Cài Đặt Giao Diện

1. Áp Dụng Giao Diện

Mermaid.js bao gồm nhiều giao diện tích hợp sẵn, cho phép bạn chuyển sang một phong cách hấp dẫn về mặt thị giác một cách dễ dàng.

Danh Sách Giao Diện

  • Mặc định
  • Tối
  • Rừng
  • Neon

Ví Dụ Cấu Hình

mermaid.initialize({
  theme: 'dark',
});

2. Áp Dụng CSS Tùy Chỉnh

Nếu bạn muốn điều chỉnh thiết kế chi tiết hơn, bạn có thể định nghĩa các kiểu bằng CSS.

.mermaid text {
  font-family: Arial, sans-serif;
  fill: #333;
}

Các Xem Xét Về Hiệu Suất

1. Điều Chỉnh Thời Gian Khởi Tạo

Thay vì khởi tạo các sơ đồ khi tải trang, bạn có thể khởi tạo Mermaid chỉ khi người dùng cần. Điều này giảm tải xử lý.

const config = {
  startOnLoad: false,
};

mermaid.initialize(config);

// Render only when needed
document.getElementById('render-btn').addEventListener('click', () => {
  mermaid.init();
});

2. Chuyển Đổi Thành Hình Ảnh Tĩnh

Nếu hiệu suất đặc biệt quan trọng, bạn có thể xuất các sơ đồ được tạo bởi Mermaid dưới dạng tệp hình ảnh và sử dụng chúng như hình ảnh tĩnh. Điều này giảm thiểu tải cho trình duyệt.

6. Tóm Tắt

Giá Trị và Tiện Lợi của Mermaid.js

Mermaid.js là một thư viện JavaScript mạnh mẽ cho phép bạn tạo các sơ đồ bằng các định nghĩa dựa trên mã. Vì nó có thể dễ dàng hiển thị nhiều loại sơ đồ—như lưu đồ, sơ đồ tuần tự và biểu đồ Gantt—nó là một công cụ vô cùng hữu ích cho các nhà phát triển và quản lý dự án.

Một trong những lợi thế lớn nhất của thư viện này là cú pháp đơn giản cho phép bạn tạo các sơ đồ phức tạp một cách hiệu quả. Nó cũng có thể tích hợp với các nền tảng CMS như WordPress, trở thành một cách tuyệt vời để trình bày thông tin trực quan trong các bài viết blog và tài liệu kỹ thuật.

Đánh Giá Mỗi Phần

  1. Mermaid là gì Chúng tôi đã giải thích tổng quan cơ bản về Mermaid.js, các trường hợp sử dụng và lợi ích của việc áp dụng nó.
  2. Cách sử dụng cơ bản của Mermaid Chúng tôi đã giới thiệu các nền tảng cơ bản để sử dụng thực tế, từ các phương pháp cài đặt đến cú pháp cơ bản.
  3. Tạo sơ đồ với Mermaid.js Chúng tôi đã cung cấp hướng dẫn chi tiết về cách tạo sơ đồ bằng HTML và JavaScript.
  4. Cách sử dụng Mermaid trong WordPress Chúng tôi đã đề cập cách tích hợp Mermaid với WordPress, bao gồm việc sử dụng plugin và các ví dụ thực tế trong bài viết.
  5. Thực hành tốt nhất khi sử dụng Mermaid Chúng tôi đã đưa ra lời khuyên thực tế về quản lý mã, tối ưu hiệu suất và tùy chỉnh thiết kế.

Những Khả Năng Tương Lai cho Mermaid.js

Mermaid.js là một dự án mã nguồn mở, và nó có thể tiếp tục thêm các tính năng mới cùng định dạng được hỗ trợ trong tương lai. Nó cũng ngày càng được hỗ trợ trên nhiều nền tảng như GitHub, Notion và WordPress, vì vậy các trường hợp sử dụng tiềm năng của nó được dự đoán sẽ mở rộng hơn nữa.

Vì nó có thể được áp dụng cho nhiều mục đích—như tài liệu kinh doanh, bài thuyết trình, và nâng cao các công cụ quản lý dự án—việc tiếp tục học và thực hành Mermaid.js sẽ giúp bạn sử dụng nó hiệu quả hơn.

Ghi Chú Cuối Cùng

Trong bài viết này, chúng tôi đã giới thiệu Mermaid.js từ cơ bản đến sử dụng thực tế. Vì nó thân thiện với người mới bắt đầu và cũng hữu ích cho tài liệu chuyên nghiệp, hãy thử sử dụng nó.

Khi cần, hãy tham khảo lại hướng dẫn này và bắt đầu tích hợp Mermaid.js vào các dự án thực tế cùng viết kỹ thuật của bạn.

広告