AidoSaaS-CMS 主题开发：从目录结构到可视化设置页

AidoSaaS-CMS 的主题既支持传统 PHP 模板，也内置了 ComPro 企业主题——一套带可视化设置、模块拖拽与实时配色预览的现代化主题。本文讲清主题契约，并以 ComPro 为范例。

主题目录与清单头

主题放在 content/themes/<slug>/。清单头 style.css 必须包含：Theme Name（等于目录 slug）、Item Id（正版标识）、License: LicenseRef-AidoSaaS-CMS-Free。内核 ThemeLoader::scan() 据此自动登记。

设置页三契约

若要提供后台设置页，需实现三个钩子函数：

• {slug}_settings_page_html($csrf)：渲染设置表单；
• {slug}_settings_save($req)：接收并校验保存；
• {slug}_settings_fields()（可选）：声明字段元信息。

未实现 page_html 会落到报错分支，因此要么三件套齐全，要么不登记设置页。

模板注入变量

模板可接收 posts / post / term / total / paged / per_page / prev_post / next_post / translations 等变量；分页参数名为 paged。归档模板按 archive-{taxonomy}.php 解析，单页按 single-{type}.php 解析。

ComPro 的可视化能力

ComPro 把首页拆成 11 类模块（hero / logos / features / stats / showcase / latest / cta / faq / products / …），通过 sections_order 拖拽编排，并支持 7 组 Tab 的实时配色预览。模块函数统一签名 compro_block_xxx(array $sec): string。

零 GPL 纪律

图标使用自带 IconRegistry（clean-room SVG），编辑器为 MIT 协议的 Milkdown，切勿引入 GPLv2+ 的图标集（如 dashicons）。