# Cardflow 主题使用简介

> 版本：1.0.7
> 适用程序：emlog Pro
> 作者：LAO.CHEN

Cardflow 是一款以卡片式布局呈现内容的三栏博客主题，支持左侧边栏、主内容区与右侧边栏，内置首页轮播、公告、音乐播放器、AI 评论互动、访客统计与前台会员中心等能力。

---

## 一、主要特性

- 三栏布局，左侧边栏组件可在后台拖拽增删排序
- 首页文章列表四种样式：图文卡片、紧凑列表、图文列表、交错图文
- 首页精选轮播、公告卡片、无图文章默认封面
- 七套主题主色、三档圆角、深浅色切换、五套字体、可调页面宽度
- 文章页目录、代码高亮与一键复制、图片灯箱、点赞/点踩/收藏/打赏/分享、相关文章、版权声明
- 文章自定义字段：副标题、封面、提示语、引用、相册、视频、音频、下载、作者的话、转载来源
- 音乐播放器（基于 Meting 接口）
- AI 评论互动（OpenAI 兼容接口）：自动摘要、评论自动回复、批量补评论
- 访客统计：PV/UV、趋势、设备、浏览器、系统、地域、热门页面、访问轨迹
- 前台会员中心：微语、在线写作、我的文章、个人资料、我的点赞/点踩/收藏
- 自定义页面模板：关于本站、文章归档、友情链接、访客统计、微语

---

## 二、快速上手

1. 开启【模板设置】插件。
2. 在「模板设置 → 头部设置」配置文字或图片 LOGO、站点图标。
3. 在「模板设置 → 外观设置」选择主色、圆角、深浅色默认值、页面宽度与字体。
4. 在「模板设置 → 首页设置」选择文章列表样式与摘要字数。
5. 进入「外观 → 边栏」，拖拽配置左侧边栏组件与右侧边栏组件。
6. 按需创建自定义页面（关于、归档、友情链接、访客统计、微语）。
7. 按需在「音乐设置」「AI 评论互动」「访客统计」中开启对应功能。

---

## 三、后台设置说明

设置项位于「模板设置」插件页，按左侧标签页分组。

### 头部设置

| 设置项 | 说明 |
| --- | --- |
| LOGO 显示模式 | 选择文字 LOGO 或图片 LOGO |
| 文字 LOGO | 文字模式下显示，留空使用站点名称 |
| 英文站点副标题 | 显示在文字 LOGO 旁，留空使用站点副标题 |
| 图片 LOGO | 图片模式下使用，推荐高度 42px 左右 |
| 图片 LOGO 跟随主题色 | 适合单色 LOGO；彩色 LOGO 建议关闭 |
| 站点图标 Favicon | 留空使用站点根目录 favicon.ico |

### 导航设置

| 设置项 | 说明 |
| --- | --- |
| 导航字体图标映射 | 每行一个，格式 `导航名称\|Remixicon 类名`，如 `首页\|ri-home-4-line`。图标名可在 remixicon.com 查询 |
| 搜索热词 | 每行一个，搜索弹窗中展示；留空显示推荐阅读 |

### 首页设置

| 设置项 | 说明 |
| --- | --- |
| 文章列表样式 | 图文卡片 / 紧凑列表 / 图文列表 / 交错图文 |
| 列表显示封面图 | 关闭后仅显示标题与摘要 |
| 文章列表排序 | 开启后可按最新、评论最多、浏览最多、点赞最多排序 |
| 摘要字数 | 列表页摘要截取长度，40 至 400 |
| 左侧博主卡片用户 ID | 默认显示 ID 为 1 的用户资料 |

### 侧栏设置

| 设置项 | 说明 |
| --- | --- |
| 博主卡片点赞 | 开启后左侧博主名片底部显示点赞按钮 |

左侧边栏组件的增删排序在「外观 → 边栏」中操作，详见第五节。

### 封面设置

| 设置项 | 说明 |
| --- | --- |
| 无图文章使用默认封面 | 文章无封面且正文无图时，按文章 ID 稳定分配默认封面 |
| 默认封面图 1-6 | 内置六张彩色封面，可替换；建议尺寸 1200×675 |

### 公告设置

| 设置项 | 说明 |
| --- | --- |
| 公告文字 | 中间区域顶部的公告卡片，留空不显示 |

### 轮播设置

| 设置项 | 说明 |
| --- | --- |
| 首页精选轮播 | 首页顶部精选文章轮播开关 |
| 精选轮播文章 | 文章 ID，英文逗号分隔；留空自动取最新文章 |
| 轮播文章数量 | 最多展示数量，1 至 10 |
| 轮播自动切换间隔 | 单位秒，填 0 关闭自动切换 |
| 轮播角标文案 | 轮播图左上角角标，留空不显示 |
| 轮播新窗口打开 | 点击轮播文章是否新标签页打开 |

### 外观设置

| 设置项 | 说明 |
| --- | --- |
| 默认主色调 | 七种配色，前台顶栏仍可切换 |
| 圆角风格 | 小 / 中 / 大圆角 |
| 开启黑暗模式切换 | 页面右侧显示日夜切换按钮 |
| 默认配色 | 访客首次访问使用浅色或深色 |
| 页面最大宽度 | 推荐 1200 至 1400 |
| 默认字体 | 主题字体 / 系统黑体 / 宋体 / 楷体 / 圆体 |

### 音乐设置

| 设置项 | 说明 |
| --- | --- |
| 首页音乐播放器 | 开关，开启后显示在左侧边栏博主名片下方 |
| Meting API 接口 | Meting 接口地址，需以 / 结尾，可自建替换 |
| 音乐平台 | 网易云 / QQ音乐 / 酷狗 / 百度 |
| 资源类型 | 歌单 / 单曲 / 专辑 / 歌手 |
| 歌单 / 单曲 ID | 资源 ID，例如歌单链接中的数字 |
| 自动播放 | 受浏览器策略限制，通常需访客先交互 |
| 播放顺序 | 列表循环 / 单曲循环 / 随机播放 |
| 显示歌词 | 播放器内滚动歌词，可点击跳转 |
| 默认折叠播放列表 | 加载时列表默认收起 |
| 默认音量 | 0 到 1 之间的小数，如 0.7 |

### AI 评论互动

详见第八节。

### 文章设置

| 设置项 | 说明 |
| --- | --- |
| 文章页显示侧边栏 | 关闭后正文区域铺满整行 |
| 文章页显示封面图 | 封面依次取自定义字段 cover、文章封面、正文首图 |
| 代码块高亮 | 代码块按语言自动着色 |
| 代码块一键复制 | 代码块右上角复制按钮 |
| 图片灯箱 | 点击图片弹层放大预览 |
| 文章目录 | 根据正文标题自动生成目录 |
| 显示字数 | 文章头部显示正文字数 |
| 显示预计阅读时间 | 按每分钟约 300 字估算 |
| 点赞 / 点踩 / 收藏 / 打赏 / 分享 | 文章底部互动按钮，可分别开关 |
| 打赏标题 | 打赏弹窗标题，留空显示「赞赏作者」 |
| 相关文章数量 | 0 为关闭 |
| 版权声明 | 文章底部版权声明开关 |
| 版权声明逐行内容 | 格式 `标签\|内容`，可用变量 {author}、{title}、{site}、{url} |

### 页面设置

| 设置项 | 说明 |
| --- | --- |
| 微语页每页文章数 | 微语页分页大小 |
| 文章年份分布 | 归档页顶部年份分布柱状图开关 |

### 访客统计

详见第十节。

### 页脚设置

| 设置项 | 说明 |
| --- | --- |
| 页脚版权文字 | 支持多行，留空使用系统底部信息 |
| 页脚快捷链接 | 每行一个，格式 `名称\|链接` |
| 公安备案号 | 填写后前台页脚显示备案信息 |
| 公安备案链接 | 点击备案图标的跳转地址，留空使用默认平台地址 |

---

## 四、边栏组件管理

### 左侧边栏（主题组件，可拖拽）

进入「外观 → 边栏」，页面下方为「左侧边栏组件」区域：

- 点击组件左侧的 ＋ 添加到左侧边栏。
- 点击已添加组件的 × 将其移除。
- 按住已添加列表拖动可调整顺序。
- 改动即时保存，无需额外提交。

可用组件：博主名片、分类、音乐、标签云。

> 左侧边栏的显隐与顺序完全由该拖拽列表控制；旧版本中的「左侧边栏模块顺序」「左侧分类」「左侧标签云」设置已移除。音乐组件仅在首页显示。

### 右侧边栏（emlog 原生组件）

同一页面中的 emlog 原生组件列表用于右侧边栏：

- 使用核心提供的 ＋ 添加、× 移除、拖动排序与保存。
- 可用组件包含 emlog 自带的分类、标签、最新文章、最新评论、自定义文本等。
- 额外新增「网站统计」组件，展示文章数目、评论数目、累计访问、全站字数、运行天数，可在组件卡片中修改标题。

> 分类与标签在右侧边栏会被自动跳过，避免与左侧边栏重复。

---

## 五、自定义页面模板

在「页面 → 新建页面」时，右侧「模板」下拉可选择主题提供的页面模板：

| 模板名称 | 用途 |
| --- | --- |
| 关于本站 | 博主头像、简介与站点统计，附最近更新 |
| 文章归档 | 按年份与月份归档文章，含年份分布柱状图 |
| 友情链接 | 读取 emlog 友情链接，卡片式展示 |
| 访客统计 | 展示访客统计图表与访问轨迹 |
| 微语 | 展示微语列表，支持分页 |

普通页面使用「自定义页面」默认模板即可。

---

## 六、文章自定义字段

在文章编辑页的「自定义字段」中输入以下字段名并保存，主题会在文章页按约定渲染：

| 字段名 | 说明 |
| --- | --- |
| subtitle | 副标题，显示在标题下方 |
| cover | 封面图 URL，留空自动提取正文首图 |
| tip | 提示语，显示在文章顶部提示条 |
| quote | 引用摘要，显示在正文上方 |
| gallery | 多图相册，每行一个图片地址，支持逗号分隔 |
| gallery_layout | 相册布局：grid 网格 / slider 滑动 |
| video | 视频，支持 B 站 / YouTube 链接、mp4 地址或完整 iframe |
| audio | 音频地址，显示在正文上方播放器 |
| download | 下载资源，每行 `名称\|链接` 或 `名称\|链接\|提取码` |
| note | 作者的话，显示在正文末尾 |
| source | 转载来源，显示在版权区 |
| original | 版权类型：original 原创 / reprint 转载 |

---

## 七、AI 评论互动

接口使用 OpenAI 兼容协议，支持 OpenAI、DeepSeek、通义千问、Kimi、智谱等。

### 配置步骤

1. 在「模板设置 → AI 评论互动」开启总开关。
2. 填写接口地址（Base URL，无需 `/chat/completions`）、API Key、模型名称。
3. 按需设置最大输出 Token 与思考强度。
4. 点击「测试连接」确认接口可用。

### 功能

| 功能 | 说明 |
| --- | --- |
| 新文章自动生成 AI 摘要 | 发布或更新文章时自动生成摘要，显示在文章顶部 |
| 访客评论自动回复 | 访客评论后自动生成回复并展示在评论下方 |
| 批量补评论 | 后台首页「AI 评论互动」卡片中，为无评论的历史文章批量补充 AI 访客评论 |

提示词支持变量：摘要与补评论可用 `{title}`、`{content}`；评论回复可用 `{title}`、`{comment}`。留空使用默认提示词。

### 常见错误

| 提示 | 处理建议 |
| --- | --- |
| 接口限流（HTTP 429） | 稍后重试或调大批量请求间隔 |
| SSL 证书校验失败 | 在 php.ini 配置 curl.cainfo / openssl.cafile，或关闭「校验 SSL 证书」 |
| 返回内容为空且 finish_reason=length | 调大最大输出 Token，推理模型会先消耗额度思考 |
| 服务器未安装 cURL 且已关闭 allow_url_fopen | 安装 cURL 扩展或开启 allow_url_fopen |

---

## 八、音乐播放器

- 数据来自 Meting 接口，需先准备可用的 Meting API 地址（可自建）。
- 依次选择音乐平台、资源类型，并填入对应资源 ID。
- 播放器显示在首页左侧边栏博主名片下方，可配置自动播放、播放顺序、歌词、列表折叠与默认音量。
- 自动播放受浏览器策略限制，通常需访客先与页面交互。

---

## 九、访客统计

### 开启

1. 在「模板设置 → 访客统计」开启「开启访客统计」。
2. 可选开启「解析 IP 地理位置」，并填写地理位置接口地址。
3. 设置统计页面访问权限、是否脱敏显示 IP、数据保留天数。

### 地理位置接口

- 使用 `{ip}` 作为 IP 占位符。
- 接口需返回 country / regionName / city / isp 字段。
- 解析在页面响应后异步执行，失败结果缓存 1 小时，不阻塞页面渲染。

### 统计页面

- 通过自定义页面模板「访客统计」展示。
- 页面包含访问概览、访问趋势、设备分布、浏览器、操作系统、地域分布、热门页面、最近访客与访问轨迹。

---

## 十、会员中心

主题提供前台会员中心，通过 emlog 内置 `/user` 路由访问，需登录后使用。

包含能力：

- 概览：文章、草稿、微语、评论、阅读、获赞等数据
- 微语：发布与删除微语
- 我的文章：查看、编辑、转草稿、删除
- 写文章：Markdown 在线写作，支持封面、分类、标签、摘要、别名、评论开关
- 我的点赞 / 点踩 / 收藏
- 资料设置：头像、昵称、邮箱、个人简介、收款码、修改密码

---

## 十一、常见问题

**前台提示「请开启【模板设置】插件」**
进入后台「插件」开启【模板设置】插件即可。

**左侧边栏组件没显示**
进入「外观 → 边栏」，在「左侧边栏组件」区域添加组件；音乐组件仅首页显示。

**右侧边栏出现两个分类或标签**
主题会在右侧边栏自动跳过分类与标签，若仍重复请检查是否使用了自定义文本组件重复添加。

**文章没有封面图**
可在文章自定义字段 `cover` 填写图片地址，或开启「无图文章使用默认封面」。

**列表样式切换后未生效**
清理浏览器缓存或确认是否命中了 CDN / 页面缓存。

**AI 功能无响应**
确认总开关已开启、接口地址与密钥正确，并点击「测试连接」排查。

**访客统计页面无数据**
确认已开启访客统计，且统计页面访问权限与当前登录身份匹配。