# hkcms-skill **Repository Path**: mo3408/hkcms-skill ## Basic Information - **Project Name**: hkcms-skill - **Description**: HkCms 主题开发 Skill 是一套面向开发者和 AI 编程助手的主题开发规范 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: https://skillhub.cn/skills/user_fbefe56b/hkcms-skill - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-10 - **Last Updated**: 2026-09-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: skill, 模板开发 ## README # HkCms 模板开发项目 本项目提供了一套完整的 HkCms 模板开发解决方案，包含模板骨架、自动化创建工具以及详尽的中文开发文档。通过本项目，开发者可以快速掌握 HkCms 模板开发的核心技能，轻松构建出专业、美观的网站模板。 ## 项目概述 HkCms 是一款基于 ThinkPHP 框架开发的内容管理系统，其模板机制灵活强大，支持响应式布局、表单开发、多语言配置等高级功能。本项目整理了模板开发的完整工作流，从项目初始化到最终打包交付，覆盖了开发的全生命周期。 项目核心价值体现在三个方面：首先，提供了一套标准化的模板骨架，开发者只需复制修改即可快速上手；其次，提供了自动化脚本，输基本参数即可自动生成模板基础结构；最后，编写了六份详尽的开发文档，涵盖从基础配置到数据字典的全部知识点。 ## 目录结构 ``` hkcms-skill/ ├── SKILL.md # 模板开发核心心智模型与实战经验 ├── assets/ │ └── skeleton/ # 模板骨架（标准模板目录结构） │ ├── README.md # 骨架使用说明 │ ├── common/ # 公共模板组件 │ │ ├── head.html # 页面头部 │ │ ├── footer.html # 页面底部 │ │ └── page_contentlist.html # 内容列表页 │ ├── category/ # 栏目页模板 │ ├── index/ # 首页与搜索页模板 │ ├── list/ # 列表页模板 │ ├── page/ # 单页模板（含联系表单） │ ├── show/ # 详情页模板 │ ├── info.ini # 模板配置文件 │ ├── config.json # 模板自定义参数配置 │ └── lang/zh-cn.json # 模板语言包 ├── references/ # 开发文档 │ ├── 01-template-structure.md # 模板结构与配置 │ ├── 02-variables.md # 模板变量与输出语法 │ ├── 03-tags-global.md # 全局标签详解 │ ├── 04-tags-content.md # 内容标签详解 │ ├── 05-tags-form-misc.md # 表单与权限控制 │ └── 06-data-dictionary.md # 数据字典 └── scripts/ └── create_template.py # 模板创建自动化脚本 ``` ## 快速开始 比如：豆包、workbuddy等等，在软件对话框中输入：请根据 https://skillhub.cn/install/skillhub.md，安装 @indiv-snowytime/hkcms-skill。 ### 方式一：使用自动化脚本创建模板（推荐） 项目提供了 `create_template.py` 脚本，可快速生成标准模板结构。确保 Python 3.6+ 环境已安装，运行以下命令： ```bash cd scripts python create_template.py ``` 脚本会引导你输入模板名称、标题、作者和版本号，自动生成完整的模板目录结构。生成后的模板位于项目根目录的 `theme_模板名/` 目录下。 ### 方式二：手动使用模板骨架 1. **复制骨架目录**：将 `assets/skeleton` 整个文件夹复制到 HkCms 主题目录 2. **重命名目录**：将 `skeleton` 改为你的主题目录名 3. **修改配置文件**：编辑 `info.ini`，填写必要信息 4. **后台安装**：登录 HkCms 后台，在「模板管理」中安装新主题 5. **绑定模板**：将主题绑定到对应站点 ## 模板开发标准流程 开发一个完整的 HkCms 模板应遵循以下七个步骤，每个步骤环环相扣，缺一不可。 **第一步：确定主题标识与目录**。主题标识即目录名，必须唯一且不包含中文和特殊字符。建议使用 `theme_` 前缀便于识别，如 `theme_myshop`。目录名将在 `info.ini` 中配置，请确保命名规范。 **第二步：编写 info.ini 文件**。这是模板的「身份证」，决定模板能否被系统识别。必须包含 `name`（目录名）、`title`（显示标题）、`author`（作者）、`version`（版本号）四个核心字段。缺少任何一项，模板都将无法被识别安装。 **第三步：按页面类型编写模板**。HkCms 模板分为多种页面类型，各类页面对应不同的业务场景。首页模板 `index/index.html` 是网站的入口页面；栏目页 `category/category.html` 展示栏目概览；列表页 `list/list.html` 呈现文章列表；详情页 `show/show.html` 展示单篇文章内容；单页 `page/page.html` 用于「关于我们」「联系我们」等独立页面。 **第四步：配置模板参数（可选）**。通过 `config.json` 文件可以为模板添加自定义配置项，如背景色选择、布局风格切换等。配置项会在后台「模板设置」中生成可视化表单，提升模板的灵活性和易用性。 **第五步：实现模板多语言（可选）**。如果网站需要支持多语言，在 `lang/` 目录下创建语言包文件，如 `zh-cn.json`、`en.json`。模板中使用 `{:$Think.lang.key}` 语法调用语言变量，系统会根据前台语言设置自动加载对应语言包。 **第六步：导入演示数据（可选）**。为方便用户预览模板效果，可以提供演示数据。必须在模板目录根目录创建 `demo.sql` 文件，并在 `info.ini` 中通过 `uninstall_sql` 参数关联卸载时需执行的清理 SQL，确保安装包「可进可出」。 **第七步：打包发布**。完成所有开发后，将模板目录打包为 ZIP 文件。HkCms 支持在线安装，上传ZIP包即可完成部署。 ## 核心标签速查 HkCms 模板通过标签实现数据调用，以下是开发中最常用的标签。 ### 全局标签 `{:$site_name}` 输出站点名称；`{:$site.cdn_url}` 输出 CDN 地址；`{$breadcrumb|raw}` 输出面包屑导航，需配合 `|raw` 过滤器保持 HTML 结构。栏目导航使用 `` 标签，通过 `type` 参数指定展示层级，`self` 控制是否包含自身。 ### 内容标签 `` 是最核心的内容标签，用于循环输出文章列表。常用参数包括 `limit`（限制数量）、`order`（排序方式）、`catid`（栏目ID）、`where`（筛选条件）。在循环体内，`{$item.title}` 获取标题，`{$item.url}` 获取链接，`{$item.thumb}` 获取缩略图。 详情页中使用 `{$Info.title}` 获取当前文章信息，其他字段如 `{$Info.content|raw}`（内容，需保持HTML）、`{$Info.updatetime}`（更新时间）等均可直接调用。 ### 模板语法 ThinkPHP 模板引擎提供了条件判断和循环控制。条件判断示例：`暂无数据`；循环示例：`{$vo.title}`。变量输出支持默认值语法：`{$title|default='默认标题'}`。 ## 模板骨架说明 项目提供的 `assets/skeleton` 是一个功能完整的响应式模板骨架，涵盖了 HkCms 模板的典型结构和常用组件。 ### 页面结构 骨架采用经典的「头部-主体-尾部」三段式布局。`common/head.html` 包含网站头部、导航菜单；`common/footer.html` 包含页脚信息；各业务页面通过 `` 和 `` 引入头尾模板。 响应式设计方面，骨架内置了移动端抽屉式菜单和吸顶导航栏，通过 CSS 媒体查询实现不同屏幕下的自适应展现。移动端菜单通过 `.mobile-drawer` 类控制，默认隐藏，在小屏幕下自动触发显示。 ### 组件说明 骨架中预置了多种常用组件。侧边栏组件 `.sidebar` 包含分类导航和最新文章列表；筛选组件 `.filter-bar` 支持多条件组合筛选；分页组件配合 `` 标签使用，自动生成分页导航。文章卡片 `.news-item` 统一了列表页和详情页的内容展示样式。 ### 调试提示 开发过程中，可在模板中添加 `{:$Think.config.debug?1:0}` 判断是否开启调试模式。开启调试时，系统会显示详细的模板解析错误信息，便于快速定位问题。完成后请删除或注释掉调试代码。 ## 文档索引 项目提供了六份开发文档，建议按顺序阅读，逐步深入。 | 文档 | 内容概要 | |------|----------| | 01-template-structure.md | 模板目录规范、info.ini 配置、响应式主题开发 | | 02-variables.md | 变量输出语法、全局变量、URL 生成规则 | | 03-tags-global.md | 全局标签（导航、面包屑、广告、循环等）详解 | | 04-tags-content.md | 内容标签（列表、分页、筛选、上下篇等）详解 | | 05-tags-form-misc.md | 表单开发、多语言体系、会员权限控制 | | 06-data-dictionary.md | 核心数据表结构、助手函数库参考 | 开发过程中遇到疑问，可优先查阅对应文档，通常能在「参数详解」或「示例」部分找到答案。 ## 实战经验补充 ### 关于栏目 ID 模板中尽量避免直接使用栏目 ID 硬编码。建议使用栏目英文名（如 `about`）配合 `` 标签定位，栏目英文名在后台「栏目管理」中设置。这样即使栏目顺序调整，模板依然能正确识别目标栏目。 ### 二级栏目侧栏 编写二级栏目侧栏导航时，使用 `{hkcms:channel name="$Cate.id" type="son"}` 可获取当前栏目的子栏目列表。注意：`channel` 标签的 `type` 可选值为 `son`（下级栏目）、`peer`（同级栏目）、`top`（顶级栏目）、`selftop`、`selfson`（当前栏目下级，无下级则返回同级），不存在 `second`；指定栏目需用 `name` 参数传栏目 ID，标签不支持 `catid` 参数。使用前建议先判断当前栏目是否有子栏目（如配合 `{if $Cate.has_child}`），或使用 `empty` 属性处理无数据的情况，避免渲染出错。 ### 移动端适配 移动端抽屉菜单与吸顶导航的层级关系需要特别注意。抽屉应置于页面最顶层（z-index 值较大），吸顶导航使用 `position: sticky` 或 `fixed` 实现。建议在 CSS 中分别针对 `.header-sticky` 和 `.drawer-open` 类编写样式。 ### 交付前检查 模板发布前，请完成以下自检项目：确认 `info.ini` 信息完整正确；检查所有页面无明显样式错位；测试响应式布局在主流分辨率下的表现；验证表单提交功能正常；确认语言包覆盖所有界面文字；准备静态预览页（HTML/CSS/JS 独立文件）以便用户预览效果。 ## 依赖与兼容性 本项目依赖 HkCms v2.2.4.230206 及以上版本，部分高级标签（如 `taglist`、`tagarclist`）需要特定版本支持。模板开发时请参考 `references/06-data-dictionary.md` 确认所用标签的版本要求。 ThinkPHP 版本兼容性：HkCms 基于 ThinkPHP 8 开发，模板语法遵循 ThinkPHP 8 模板引擎规范。 ## 许可证 本项目遵循项目仓库中声明的许可证协议。请在Fork、Star或下载使用前，仔细阅读相关条款。 --- 如有疑问，欢迎在 Gitee 仓库中提交 Issue 或Pull Request，共同完善 HkCms 模板开发生态。