- oxdraw là một công cụ ‘Diagram as Code’ được viết bằng Rust, được thiết kế để chỉnh sửa sơ đồ dựa trên mã theo cách trực quan và duy trì chúng ở dạng có thể tái tạo
- Sơ đồ được viết bằng cú pháp Mermaid và có thể điều chỉnh bằng kéo thả vị trí nút, màu sắc, đường nối, v.v. thông qua giao diện web
- Các thay đổi trực quan được lưu dưới dạng chú thích trong tệp Mermaid, giúp duy trì khả năng tương thích với các công cụ Mermaid khác
- Dự án gồm CLI và trình chỉnh sửa web dựa trên React, đồng thời hỗ trợ cả kết xuất qua dòng lệnh và chế độ chỉnh sửa thời gian thực
- Bằng cách kết hợp năng suất của sơ đồ sinh từ mã với mức độ tự do của chỉnh sửa trực quan, công cụ này được chú ý như một giải pháp thay thế cho các công cụ GUI như Lucidchart
Tổng quan dự án
- Mục tiêu của oxdraw là tạo và duy trì sơ đồ chất lượng cao một cách dễ dàng thông qua cú pháp khai báo và có thể tái tạo
- Sơ đồ được viết bằng cú pháp Mermaid, còn việc tinh chỉnh trực quan được thực hiện trên giao diện web
- Các chỉnh sửa trực quan của người dùng được phản ánh vào mã nguồn gốc, cho phép quản lý phiên bản và tự động hóa
- Các thay đổi được ghi lại dưới dạng chú thích (comment) trong tệp Mermaid, từ đó duy trì khả năng tương thích hoàn toàn với các công cụ khác trong hệ sinh thái Mermaid
- Kho mã nguồn gồm CLI dựa trên Rust và giao diện web dựa trên React, trong đó CLI biên dịch tệp
.mmd thành hình ảnh
Tầm nhìn của dự án
- Trước đây, nhà phát triển đã sử dụng Mermaid để tạo sơ đồ kiến trúc hoặc trực quan hóa codebase, nhưng do giới hạn trong chỉnh sửa chi tiết, họ phải chuyển sang các công cụ như Lucidchart
- oxdraw hướng tới việc kết hợp tính tự động hóa dựa trên mã của Mermaid với mức độ tự do trực quan của Lucidchart
- Qua đó, dự án theo đuổi mục tiêu vừa giữ được tính tái tạo, khả năng cộng tác và khả năng tự động hóa của sơ đồ sinh từ mã, vừa nâng cao chất lượng hoàn thiện về mặt trực quan
Cách sử dụng
- Có thể cài đặt qua Cargo:
cargo install oxdraw
- Kết xuất sơ đồ:
oxdraw --input flow.mmd
- Chạy trình chỉnh sửa tương tác:
oxdraw --input flow.mmd --edit
- CLI nhận tệp Mermaid làm đầu vào để tạo đầu ra SVG hoặc PNG, và chạy trình chỉnh sửa web cục bộ với tùy chọn
--edit
Giải thích các cờ CLI
-i, --input : Nhập tệp nguồn Mermaid-o, --output : Chỉ định đường dẫn lưu kết quả kết xuất--png: Xuất ở định dạng PNG--scale : Điều chỉnh tỷ lệ kết xuất PNG (mặc định 10.0)--edit: Chạy trình chỉnh sửa trực quan--serve-host / --serve-port : Chỉ định địa chỉ và cổng của máy chủ trình chỉnh sửa (mặc định 127.0.0.1:5151)-b, --background-color : Chỉ định màu nền (chỉ dành cho SVG)-q, --quiet: Ẩn các đầu ra như thông báo hoàn tất kết xuất
Tính năng frontend
- Thao tác với nút và cạnh
- Xóa nút hoặc cạnh đã chọn (hỗ trợ phím Delete/Backspace)
- Chỉ định và đặt lại riêng màu nút, viền và màu chữ
- Thiết lập màu cạnh, kiểu đường (liền/nét đứt) và hướng mũi tên
- Thêm và xóa điểm điều khiển (control point) có thể kéo thả trên đường đi của cạnh
- Tương tác canvas và trình chỉnh sửa
- Hiển thị grid snap và hướng dẫn căn chỉnh khi kéo nút
- Di chuyển nút bằng Shift+mũi tên
- Kéo tay nắm của cạnh để chỉnh đường đi, nhấp đúp để thêm/xóa tay nắm
- Hỗ trợ di chuyển theo đơn vị subgraph — di chuyển cùng các nút và cạnh trong nhóm
- Bảng nguồn phản ánh tệp Mermaid theo thời gian thực, đồng thời cung cấp tự động lưu và hiển thị trạng thái (đang lưu/lỗi, v.v.)
- Thanh công cụ phía trên hiển thị đường dẫn tệp hiện tại và trạng thái lưu
Cấu trúc kỹ thuật và giấy phép
- Thành phần gồm Rust 55.7% , TypeScript 40.0% , CSS 3.4% , và khác 0.9%
- Được phát hành theo giấy phép MIT, cho phép sử dụng và chỉnh sửa tự do
- Hiện có 506 Star và 10 Fork, cho thấy sự quan tâm tích cực từ cộng đồng
Đánh giá tổng thể
- oxdraw là một cách tiếp cận mới, kết hợp tự động hóa trong quản lý sơ đồ dựa trên mã với tính trực quan của chỉnh sửa hình ảnh
- Trong khi vẫn duy trì khả năng tương thích hoàn toàn với hệ sinh thái Mermaid, công cụ tận dụng hiệu năng của Rust và giao diện UI tương tác của React
- Đây đang là công cụ được chú ý nhờ cung cấp quy trình làm việc sơ đồ có thể cộng tác cho cả nhà phát triển lẫn nhà thiết kế
1 bình luận
Ý kiến trên Hacker News
Đây thực sự là một dự án rất tuyệt. Việc chọn dựa trên Mermaid.js có lẽ là lựa chọn hợp lý nhất ở thời điểm hiện tại, vì đây là thư viện sơ đồ khai báo phổ biến nhất
Nếu muốn hỗ trợ các loại sơ đồ phức tạp hơn thì cũng đáng để xem qua D2 Language. Nó cung cấp một cách tiếp cận khai báo linh hoạt hơn rất nhiều
Cá nhân tôi đang tự tạo một cổng MacPorts để dùng
Nếu sau này dùng thường xuyên hơn, tôi định đóng góp nó vào kho lưu trữ MacPorts chính thức
Tuy nhiên hiện không có Git tag hay GitHub release gắn với bản phát hành Cargo, nên việc đóng gói khá bất tiện
Tạm thời tôi đang xử lý bằng cách giả định commit cụ thể này (
9ccd9bf53f9a309ccda42b5c17e9c1056493fb90) là bản phát hành 0.1.0Có thể xem cổng liên quan ở đây
Đây đúng là thứ tôi đang tìm. Có một tính năng mà tôi rất muốn thấy trong một giải pháp sơ đồ khai báo
Đó là tính năng popup hiển thị thông tin bổ sung hoặc sơ đồ lồng nhau khi rê chuột
Ví dụ, bạn có muốn khi chia sẻ liên kết thì người khác có thể xem ngay sơ đồ kèm popup và phần lồng nhau không,
hay chỉ cần chia sẻ file
.mmdrồi mở bằng CLI là đủCách sau thì có thể triển khai khá nhanh, nhưng cách trước có thể cần tự host kiểu như ngrok hoặc triển khai lên cloud
Hoặc cũng có thể thêm tính năng xuất ra file HTML (export) để popup hoạt động mà không cần CLI
Chúc mừng bạn đã công bố dự án. Tôi rất ấn tượng với việc dùng cú pháp khai báo để định nghĩa quan hệ và cho phép tùy biến tinh chỉnh mà các hệ thống auto-layout hiện có không làm được
Tuy nhiên, trong
Cargo.tomlcó ghi là giấy phép MIT, nhưng trong kho mã lại không có file giấy phépSẽ tốt hơn nếu bạn thêm vào để có thể kiểm tra ngay trên GitHub
Đây đúng là dự án rất cần thiết. Tôi chủ yếu dùng PlantUML, nhưng chỉ cần số component vượt quá 5 là tôi đã phải dành 20–30% thời gian để chỉnh layout
Cách tiếp cận dùng chú thích để phản ánh vào layout engine rất thú vị. Việc đặt tọa độ của một số component thành ràng buộc cố định rồi để phần còn lại tự động sắp xếp có vẻ sẽ rất hữu ích
Nếu sơ đồ cũng được đưa vào quản lý phiên bản cùng với thay đổi mã nguồn thì code review và quản lý kiến trúc sẽ trở nên tự nhiên hơn nhiều
Chất lượng layout của Mermaid không tốt, và thật đáng tiếc khi GitHub phớt lờ các yêu cầu hỗ trợ PlantUML
Có vẻ mức độ chấp nhận của ‘diagrams as code’ được quyết định bởi định dạng mà các nền tảng lớn hỗ trợ
Thay vì tạo ra một tiêu chuẩn mới, tôi nghĩ các cải tiến như rendering dựa trên trọng số phần tử sẽ thực tế hơn
Chủ đề này cũng đã được bàn trong thảo luận cộng đồng GitHub
Tôi thật sự mong PlantUML có thể giải quyết được vấn đề này
Cái này giống như một phiên bản tăng cường của ngôn ngữ dot trong Graphviz
Nó cung cấp biến và cú pháp gọn gàng hơn, nhưng khái niệm cơ bản thì tương tự
Xem tài liệu Graphviz
Mermaid.js có khái niệm layout engine
Ví dụ như @mermaid-js/layout-elk
Tôi tò mò không biết bạn có dự định triển khai thuật toán của mình thành auto-layout engine cho Mermaid hay không
Dự án rất hay. Tôi xem trên di động nhưng không thấy nút thêm node
Một tính năng nữa tôi muốn có là thu gọn các node phía downstream (collapse downstream nodes). Có thể hơi ngoài phạm vi, nhưng sẽ rất tuyệt nếu có
.mmd. Nhưng tôi nghĩ đây là một đề xuất hayTính năng thu gọn các node downstream có vẻ cũng rất hợp với tính năng animation mà một người dùng khác đã yêu cầu