51 lines
3.0 KiB
Markdown
51 lines
3.0 KiB
Markdown
|
# XControl CMS 平台指南
|
|||
|
|
|
|||
|
|
本文档介绍如何使用全新的 CMS 配置、扩展生态以及主题定制流程，帮助团队快速落地内容管理方案。
|
|||
|
|
|
|||
|
|
## 使用说明
|
|||
|
|
|
|||
|
|
1. **配置文件位置**：所有实例统一使用 [`config/cms.json`](../../config/cms.json) 描述模板、主题、扩展及内容源。提交前可运行 `make lint-cms` 或 GitHub Actions 自动校验以确保配置符合 JSON Schema。
|
|||
|
|
2. **模板管理**：
|
|||
|
|
- `templates` 数组声明可用模板的 `name` 与入口文件 `entry`；
|
|||
|
|
- 可添加 `description` 与 `previewPath` 提供运营预览信息；
|
|||
|
|
- 模板内可读取主题变量 `theme.variables`，应通过公共的 `@xcontrol/cms-theme` SDK 获取。
|
|||
|
|
3. **主题切换**：
|
|||
|
|
- `theme` 字段记录版本、作者与可覆写的变量；
|
|||
|
|
- 在 CI/CD 中读取 `theme.version` 控制静态资源缓存；
|
|||
|
|
- 自定义变量建议遵循 `kebabCase` 或 `camelCase`，并在设计系统中记录来源。
|
|||
|
|
4. **扩展启用**：
|
|||
|
|
- `extensions` 数组列出扩展包；`enabled=false` 的扩展会被打包但默认不挂载；
|
|||
|
|
- `config` 字段由扩展自行解析，应在扩展仓库提供 JSON Schema 或 TypeScript 类型定义；
|
|||
|
|
- 推荐将第三方密钥通过环境变量传入扩展，避免写入配置文件。
|
|||
|
|
5. **内容源配置**：
|
|||
|
|
- `contentSources` 支持 `git`、`filesystem`、`api` 和 `database` 四种类型；
|
|||
|
|
- 每个内容源都需要一个唯一的 `name` 与自定义 `options`；
|
|||
|
|
- 若设定 `readOnly: true`，发布面板会禁用写入操作。
|
|||
|
|
|
|||
|
|
## 扩展开发手册
|
|||
|
|
|
|||
|
|
1. **开发准备**：
|
|||
|
|
- 使用 `pnpm create @xcontrol/cms-extension <name>` 脚手架初始化项目；
|
|||
|
|
- 在 `package.json` 中声明入口 `main` 与 `module`，同时导出扩展元数据 `getExtensionMeta()`。
|
|||
|
|
2. **生命周期**：
|
|||
|
|
- 扩展需实现 `register(app, context)` 方法，在其中挂载路由、配置表单或任务；
|
|||
|
|
- 扩展可通过 `context.cmsConfig` 读取解析后的 `cms.json`；
|
|||
|
|
- 对长耗时任务使用 `context.queue.enqueue`，避免阻塞渲染线程。
|
|||
|
|
3. **测试与发布**：
|
|||
|
|
- 使用 `pnpm test` 运行扩展单测；
|
|||
|
|
- 通过 `pnpm build` 生成产物，并在 `dist/manifest.json` 中输出能力声明；
|
|||
|
|
- 发布到内网 NPM 仓库后，可在主项目 `config/cms.json` 中引用。
|
|||
|
|
|
|||
|
|
## 主题定制指南
|
|||
|
|
|
|||
|
|
1. **继承基础主题**：复制官方主题仓库 `@xcontrol/cms-theme-galaxy`，在 `tokens/` 中调整颜色、排版、阴影等设计变量。
|
|||
|
|
2. **变量发布**：
|
|||
|
|
- 执行 `pnpm build` 生成 `theme.json`；
|
|||
|
|
- 在仓库中创建 `releases/<version>` 标签，与 `cms.json` 的 `theme.version` 对齐；
|
|||
|
|
- 将 `theme.json` 发布到静态资源 CDN，配置 `THEME_REGISTRY_URL` 指向该地址。
|
|||
|
|
3. **模板调试**：
|
|||
|
|
- 本地运行 `pnpm dev --template <template-name>`，自动读取主题变量热更新；
|
|||
|
|
- 使用 `previewPath` 提供的静态图检视最终效果；
|
|||
|
|
- 主题变量新增时记得更新 `theme.variables` 以同步到配置文件。
|
|||
|
|
|