Cài đặt và sử dụng — Theme Editor

Bước 1: Kích hoạt plugin

Vào Settings → Plugin Manager, tìm plugin-theme-editor và bật.

Hoặc kích hoạt qua dòng lệnh:

bash

yarn pm enable plugin-theme-editor

Khi kích hoạt lần đầu, plugin tự động tạo 4 theme mặc định: Default Light, Dark, Compact, Compact Dark.

Bước 2: Mở Theme Editor

Vào Settings → Theme để quản lý và tùy chỉnh giao diện:

Mục	Mô tả
Màu sắc chính	`colorPrimary` — màu chủ đạo của toàn bộ ứng dụng
Font	`fontFamily`, `fontSize` — font chữ và kích thước
Border radius	`borderRadius` — độ bo góc các thành phần UI
Spacing	`marginSM`, `paddingLG`... — khoảng cách giữa các thành phần

Giao diện Theme Editor

Plugin bao gồm antd token previewer — hiển thị trực quan hàng trăm component demo (Button, Input, Table, Modal...) với theme hiện tại, giúp bạn thấy ngay tác động của mỗi thay đổi.

Bước 3: Tạo theme mới

Nhấn Create Theme trong trang quản lý theme
Tùy chỉnh các token:
- Seed tokens: colorPrimary, colorSuccess, colorWarning, colorError, colorInfo, borderRadius, fontSize
- Map tokens: Tự động tính từ seed tokens (ví dụ: colorPrimaryHover tính từ colorPrimary)
- Alias tokens: Mapping cụ thể cho component (ví dụ: colorBgContainer)
Xem trước (Preview) trên giao diện mẫu — thay đổi hiển thị real-time
Nhấn Lưu để lưu theme

Ví dụ tạo theme qua API

typescript

await agent.resource('themeConfig').create({
  values: {
    config: {
      token: {
        colorPrimary: '#722ed1',
        borderRadius: 8,
        fontSize: 14,
      },
    },
    optional: true,
    default: false,
  },
});

Bước 4: Áp dụng theme

Đặt theme mặc định (admin)

Chọn theme từ danh sách và nhấn Set as default. User mới sẽ dùng theme này.

Chuyển đổi theme (user)

Mỗi user có thể chọn theme riêng. Khi chọn, plugin gọi action users:updateTheme:

typescript

await agent.resource('users').updateTheme({
  values: { themeId: 2 },
});

Plugin lưu themeId vào user.systemSettings.themeId trong database:

Cấu hình nâng cao — JSON Editor

Cho người dùng nâng cao, plugin cung cấp JSON editor cho phép chỉnh sửa trực tiếp cấu hình theme:

json

{
  "token": {
    "colorPrimary": "#1677ff",
    "colorSuccess": "#52c41a",
    "colorWarning": "#faad14",
    "colorError": "#ff4d4f",
    "borderRadius": 6,
    "fontSize": 14,
    "fontFamily": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto"
  },
  "algorithm": "defaultAlgorithm"
}

Cấu trúc ThemeConfig bao gồm:

Thuộc tính	Kiểu	Mô tả
`token`	`AliasToken`	Tất cả design tokens của antd
`algorithm`	`string`	Thuật toán theme: `defaultAlgorithm`, `darkAlgorithm`, `compactAlgorithm`

Vòng đời plugin

Thành phần client

Thành phần	Mô tả
`InitializeTheme`	Load theme config khi app khởi động
`ThemeEditorProvider`	Context provider cho theme editor state
`ThemeListProvider`	Quản lý danh sách themes
`ThemeCard`	Card hiển thị theme trong danh sách
`TokenPreviewer`	Antd token previewer — xem trước component demos
`ColorPicker`	Bộ chọn màu (react-colorful)
`ThemeConfigEditor`	JSON editor nâng cao (vanilla-jsoneditor)

Lưu ý quan trọng

Theme áp dụng per-user — mỗi user chọn theme riêng qua systemSettings.themeId
Admin đặt default theme cho user mới, nhưng user hiện tại giữ nguyên theme đã chọn
Custom CSS có thể gây xung đột với theme tokens — ưu tiên dùng token thay vì CSS
Sao lưu theme (export JSON) trước khi thay đổi lớn