Câu hỏi thường gặp (FAQ) — Theme Editor

Sử dụng

Thay đổi theme có ảnh hưởng đến dữ liệu không?

Không. Theme chỉ thay đổi giao diện (màu sắc, font, spacing) — không ảnh hưởng dữ liệu hay logic nghiệp vụ. Bạn có thể thay đổi theme bất cứ lúc nào mà không lo mất dữ liệu.

Mỗi user có thể chọn theme riêng không?

Có. Plugin lưu themeId vào user.systemSettings.themeId. Mỗi user tự chọn theme qua Theme Selector, không ảnh hưởng user khác.

Cách hoạt động:

1. User chọn theme → gọi users:updateTheme với themeId
2. Server cập nhật systemSettings.themeId trong bảng users
3. Client apply theme ngay lập tức

Làm sao quay về theme mặc định?

Hai cách:

1. Qua UI: Vào Theme Selector, chọn theme "Default Light"
2. Qua API: Gọi users:updateTheme với themeId của theme mặc định

Có thể xóa built-in theme không?

Built-in themes (isBuiltIn: true) được đánh dấu là theme hệ thống. Về mặt kỹ thuật có thể xóa qua API, nhưng không nên vì:

• Là fallback khi theme custom bị lỗi
• User mới cần theme mặc định
• Không thể khôi phục dễ dàng sau khi xóa

Seed token, map token, alias token khác nhau thế nào?

Loại	Ví dụ	Mô tả
Seed tokens	colorPrimary, fontSize	Token gốc — bạn đặt giá trị trực tiếp
Map tokens	colorPrimaryHover, colorPrimaryActive	Tự động tính từ seed tokens
Alias tokens	colorBgContainer, colorTextHeading	Mapping cụ thể cho mục đích sử dụng

Bạn chỉ cần thay đổi seed tokens — antd tự động tính toán map và alias tokens.

Cấu hình

Làm sao tạo dark version của theme tùy chỉnh?

Khi tạo theme, chọn algorithm: "darkAlgorithm" trong cấu hình:

{
  "token": {
    "colorPrimary": "#722ed1"
  },
  "algorithm": "darkAlgorithm"
}

Antd sẽ tự động tính toán các màu tối dựa trên seed tokens.

Có thể kết hợp dark + compact không?

Có. Dùng mảng algorithms:

{
  "algorithm": ["darkAlgorithm", "compactAlgorithm"]
}

Plugin đã có sẵn theme Compact Dark khi cài đặt.

Export/Import theme hoạt động thế nào?

• Export: Lấy config JSON từ themeConfig resource → lưu file
• Import: Tạo theme mới với config JSON từ file đã export

// Export
const res = await agent.resource('themeConfig').get({ filterByTk: themeId });
const config = res.body.data.config;
// Lưu config ra file JSON

// Import
await agent.resource('themeConfig').create({
  values: { config, optional: true },
});

Xử lý sự cố

Giao diện bị lỗi sau khi chỉnh theme?

Thường do token không hợp lệ. Xử lý:

1. Chọn lại một built-in theme (Default Light) để khôi phục
2. Kiểm tra config JSON của theme lỗi — đảm bảo giá trị token đúng kiểu (color là hex string, fontSize là số)
3. Xóa cache trình duyệt (Ctrl+Shift+Delete)

Theme không áp dụng cho một số component?

Có thể component đó dùng inline style hoặc CSS cứng thay vì antd token. Plugin chỉ ảnh hưởng đến component sử dụng antd design system. Component tùy chỉnh cần dùng useToken() hook để lấy giá trị token.

User mới không thấy theme mặc định?

Kiểm tra:

1. Có theme nào đặt default: true không? Phải có ít nhất 1 theme mặc định
2. Plugin có đang hoạt động không? Vào Plugin Manager kiểm tra
3. themeConfig:list có ACL public không? (Mặc định đã có)

Lỗi "themeConfig repository does not exist"?

Lỗi này xảy ra khi plugin cố cài đặt nhưng collection themeConfig chưa được tạo trong database. Nguyên nhân:

• Database migration chưa chạy
• Plugin load trước khi database sẵn sàng

Giải pháp: chạy lại migration và restart server:

yarn digiforce-nc upgrade
yarn start