@digiforce-nc/plugin-field-markdown-vditor

Plugin cung cấp kiểu field Markdown editor — tích hợp Vditor, trình soạn thảo WYSIWYG mạnh mẽ với hỗ trợ KaTeX (toán học), Mermaid (sơ đồ), ECharts (biểu đồ) và Flowchart.

Plugin này làm gì?

Hãy hình dung: bạn cần lưu nội dung rich-text (bài viết, tài liệu, ghi chú kỹ thuật) trong bản ghi. Plugin này cung cấp Vditor — editor Markdown WYSIWYG với preview trực tiếp, hỗ trợ upload ảnh qua storage hệ thống, và render các thành phần nâng cao (biểu đồ, công thức toán, sơ đồ).

Ba nhiệm vụ chính

#	Nhiệm vụ	Chi tiết
1	WYSIWYG editing	Vditor editor với 3 chế độ soạn thảo
2	Storage validation	Server action `check` xác thực storage khả dụng cho upload ảnh
3	Asset distribution	Server copy vditor assets vào dist khi build/install

Kiến trúc

Tổng quan

Plugin có cả server (resource vditor, copy assets) và client (Vditor editor). Giá trị lưu dạng text (Markdown) trong database. Server cung cấp endpoint kiểm tra storage cho upload ảnh trong editor.

Luồng hoạt động

Server resource: vditor

Action	Method	Mô tả
`vditor:check`	GET	Kiểm tra storage đã cấu hình và khả dụng cho upload (trả về status + config)

Asset distribution

Khi install hoặc build, server tự động copy thư mục assets của Vditor (CSS, JS, fonts) vào thư mục dist để phục vụ cho client. Điều này đảm bảo editor hoạt động offline mà không cần CDN bên ngoài.

Ba chế độ soạn thảo

Chế độ	Mô tả
WYSIWYG	Soạn trực quan — gõ đến đâu, format đến đó (giống Word)
Instant Rendering	Markdown syntax + preview real-time (giống Typora)
Split View	Code markdown bên trái, preview bên phải

CDN dependencies (lazy-loaded)

Library	Chức năng
KaTeX	Render công thức toán học ( $E = mc^2$ )
Mermaid	Render sơ đồ (flowchart, sequence, class...)
ECharts	Render biểu đồ tương tác (bar, line, pie...)
Flowchart.js	Render lưu đồ dạng text

Ví dụ sử dụng

Cấu hình field markdown

typescript

const contentField = {
  name: 'content',
  type: 'text',
  interface: 'markdownVditor',
  uiSchema: {
    type: 'string',
    title: 'Nội dung',
    'x-component': 'Vditor',
    'x-component-props': {
      mode: 'wysiwyg',
      minHeight: 300,
    },
  },
};

Kiểm tra storage trước khi upload

typescript

const response = await api.resource('vditor').check();
const storageReady = response.data.data;
// storageReady = true → có thể upload ảnh
// storageReady = false → chỉ cho soạn text, không upload

Thành phần client

Thành phần	Mô tả
`Vditor`	Editor component WYSIWYG (lazy-loaded)
`MarkdownVditorFieldInterface`	Định nghĩa interface cho field markdown

Dependencies

Package	Vai trò
`@digiforce-nc/server`	Server framework — resource vditor
`@digiforce-nc/database`	Database ORM — lưu markdown dạng text
`@digiforce-nc/client`	Client framework — đăng ký component
`vditor`	Markdown editor engine