Playground¶

Playground chạy tại {SERVER_URL}/playground và dùng authenticated POST để preview hoặc export diagram. Bạn cần URL Gateway, shared rendering token và source phù hợp với renderer muốn dùng.

1. Bắt đầu nhanh¶

Mở {SERVER_URL}/playground.
Chọn renderer, ví dụ plantuml hoặc mermaid.
Mở Token, nhập shared rendering token và lưu.
Nhập diagram source vào vùng Source.
Chọn chế độ params %%krokup hoặc Fenced block.
Chọn Render hoặc chờ auto-render.
Đọc warning bên dưới preview.
Dùng Export để tải output.

Ví dụ PlantUML:

@startuml
Alice -> Bob: Hello
@enduml

2. Chọn renderer và format¶

Khi đổi renderer, Playground nạp source gần nhất đã lưu cho renderer đó. Danh sách output phụ thuộc renderer; chọn format đang được giao diện cung cấp thay vì giả định mọi renderer đều hỗ trợ SVG, PNG và PDF.

Preview chờ một khoảng ngắn sau khi source ngừng thay đổi. Request cũ được hủy khi có source mới để kết quả cũ không ghi đè preview mới nhất. Zoom, pan và Fit chỉ thay đổi góc nhìn trong browser, không thay đổi source hoặc file export.

3. Dùng params¶

Chế độ %%krokup ghi option vào dòng đầu source:

%%krokup {theme=corporate scale=1.5 direction=lr}
@startuml
Alice -> Bob: Review
@enduml

Chế độ Fenced block mô phỏng params trên dòng mở Markdown fence. Source chỉ chứa diagram body; ô params nhận {theme=dark scale=2} hoặc theme=dark scale=2. Playground tự chọn language từ renderer và tạo directive trong request.

Năm control theme, scale, background, direction và padding chỉ hoạt động khi renderer hoặc họ diagram hỗ trợ. Option không áp dụng được có thể tạo warning nhưng vẫn trả output.

4. Export¶

Playground export SVG và PNG với background white, black hoặc transparent. Background trong hộp export được Gateway áp dụng lên file cuối; nó độc lập với option background trong diagram params.

5. Dữ liệu trong browser¶

Dữ liệu	Nơi lưu	Thời gian giữ
Rendering token	`sessionStorage`	Mất khi đóng tab
Source	`localStorage` theo renderer	Còn đến khi xóa browser data
Fenced params	`localStorage` theo renderer	Còn đến khi xóa browser data

Không sử dụng máy dùng chung cho source nhạy cảm nếu chưa xóa dữ liệu browser.

6. Xử lý lỗi¶

Hiện tượng	Cách xử lý
`401`	Nhập lại shared rendering token
`404`	Kiểm tra renderer và format
`429`	Chờ theo `Retry-After`
`504`	Giảm độ phức tạp hoặc thử lại sau
Preview không đổi	Kiểm tra warning, token và Network của browser
Option không có tác dụng	Kiểm tra capability và output format trong Params
Output quá lớn	Giảm `scale`, `width`, `height` hoặc `padding`