KnowSphere 页面开发指南
页面与路由的职责
| 页面 | 数据来源 | 注意事项 |
|---|---|---|
| 原生文章详情 | Halo post 变量和已处理正文 | 不取原始快照绕过付费墙 |
| 原生分类、标签列表 | Halo 原生列表、插件集合付费墙 | permalink 优先，避免写死前缀 |
| 会员套餐页 | listMembershipPlans() | 通过已注册路由或自定义页面模板承载 |
| 专栏目录 | listColumns、getColumnDetail | 只显示已发布公开数据 |
| 我的订单、钱包、已购 | 当前用户 Finder 或 UC API | 分页 items、身份隔离、登录提示 |
| 评论区与签到 | 插件 Web Components | 单次挂载、事件清理、Cookie 同源 |
| Pro 任务、分销等 | 对应 Pro Finder / API | 版本、功能关闭和空态均需处理 |
主题文件、Halo 自定义页面和插件控制台 UC 的 URL 不能互相替代。主题创建 templates/uc/orders.html 不会自动改变插件的 UC 路由。
模板字段
<article th:with="detail=${knowSphereFinder.getColumnDetail(columnName).block()}">
<p th:if="${detail == null}">专栏不存在或尚未公开</p>
<th:block th:if="${detail != null}">
<h1 th:text="${detail.column.displayName}"></h1>
<p th:if="${#lists.isEmpty(detail.chapters)}">暂无公开章节</p>
<a th:each="chapter : ${detail.chapters}"
th:href="${chapter.permalink}" th:text="${chapter.title}"></a>
</th:block>
</article>
columnName 由当前已确认的路由模型或主题调用方传入，本例不宣称插件自动提供名为 columnName 的全局变量。ChapterVo 使用 permalink、isFreePreview、dripStatus 等实际字段，不使用虚构的 locked。
交互与布局
- 使用真实空态、加载态、错误态，不填充虚构订单或收入。
- 付款中禁止重复提交；网络恢复后查服务端状态，不能仅改按钮文字。
- 手机端卡片保持可读；键盘可访问按钮和表单，错误提示关联字段。
- 公共页面可以缓存公共目录；用户权益、钱包和订单部分按用户渲染。
- 主题脚本卸载组件时清理事件和轮询，避免切换页面后继续请求。