XuCard-typecho主题使用教程
XuCard 主题使用教程（核心篇）
本文基于 Typecho 1.3 编写，所有示例均可在 Typecho 后台「新建文章 / 独立页面」中，切换到「源码模式」后直接粘贴使用。
主题仓库：XuCard ｜ 适用版本：Typecho 1.3
一、主题简介
XuCard 是一款卡片化、玻璃拟态（Glassmorphism）风格的个人主页 / 博客主题。它把内容拆成清晰的卡片区块，并内置三套短代码（[project]、[resource]、[blog]）、五个独立页面模板、时段自适应 Banner，以及深浅色一键切换。
核心特性一览：
- 🎴 卡片化布局：最新文章、随机推荐、社交、音乐、个人信息均以卡片呈现。
- 🧩 短代码系统：用一行代码生成项目 / 资源 / 博客卡片，支持 emoji、图片 URL、内联 SVG 三种图标。
- 📱 响应式：移动端单列、PC 端自动分栏（如「关注公众号」页面）。
- 🌗 深浅色：后台可设「跟随系统 / 浅色 / 深色」，前端可手动切换并本地保存。
- 🔗 社交图标：GitHub / 公众号 / 邮箱，未填写则自动隐藏，无边框圆形按钮。
二、外观设置（后台 → 外观 → 设置外观）
下表为全部配置项，按区块整理：
| 配置项 | 说明 | 留空时 |
|---|---|---|
| 头像 URL | 问候卡片与侧边栏头像图片地址 | 显示昵称首字兜底 |
| Favicon 地址 | 浏览器标签页图标 | 使用主题默认 favicon |
| 站点主人昵称 | 显示为 Hi, 昵称 | 默认显示 zhijiantv |
| 侧边栏状态标签 | 昵称右侧小标签 | 不显示 |
| 个人简介 | 问候卡片下方简介 | 不显示 |
| 自定义问候语 | 留空则按时段自动输出 Morning/Afternoon/Evening/Night | 自动问候 |
| Banner 默认背景图 | 各时段图缺失时的兜底 | 显示柔和渐变 |
| 上午背景图 (06–11) | 上午时段 Banner 背景 | 回退默认图 |
| 下午背景图 (12–17) | 下午时段 Banner 背景 | 回退默认图 |
| 傍晚背景图 (18–21) | 傍晚时段 Banner 背景 | 回退默认图 |
| 夜间背景图 (22–05) | 夜间时段 Banner 背景 | 回退默认图 |
| 背景图对齐位置 | center / top / bottom / left / right，校正主体偏移 | center |
| GitHub 链接 | 首页社交图标 | 隐藏 |
| 公众号链接 | 首页社交图标（可填 /gzh 或主页） | 隐藏 |
| 邮箱链接 | 可填 mailto: 或直接邮箱 | 隐藏 |
| 音乐名称 | 音乐播放器卡片标题 | 隐藏播放器 |
| 音乐音频 URL | 音频直链 | 隐藏播放器 |
| 主题模式 | 跟随系统 / 浅色 / 深色 | 跟随系统 |
| 备案号 | 自动链接工信部备案系统 | 不显示 |
| 近期文章链接 | 指向归档页；留空自动找 slug=archives 页面 | 自动归档页 |
💡 提示：Banner 四段背景图建议尺寸一致（如 1200×400），主题会自动 cover + 居中裁切。三、短代码系统（核心）
短代码是 XuCard 的内容引擎。使用方式：在独立页面 / 文章的「源码模式」下粘贴下面的代码行，保存后前台会自动渲染成卡片。
⚠️ 短代码必须放在源码模式（而非可视化编辑器），否则会被当成纯文本。卡片之间建议空一行分隔。
图标 icon / avatar 字段支持三种写法：
- emoji：
icon="🚀" - 图片 URL：
icon="https://example.com/logo.png"（仅放行http(s)://与站内/路径） - 内联 SVG：直接粘贴
<svg>...</svg>（自动剥离<script>与事件属性，安全）
1. [project] 我的项目卡片
| 字段 | 说明 |
|---|---|
icon | 图标（emoji / 图片 / SVG） |
title | 项目名称 |
year | 年份标签 |
desc | 项目简介 |
tags | 标签，逗号分隔 |
website | 官网链接（按钮「官网」） |
github | GitHub 链接（按钮「GitHub」） |
npm | npm 链接（按钮「npm」） |
示例：
[project icon="🛠️" title="XuMD" year="2026" desc="一个开源的微信公众号 Markdown 编辑器。" tags="Vue3,工具,Typora" website="https://xumd.example.com" github="https://github.com/zhijiantv/XuMD"]
[project icon="https://example.com/logo.png" title="XuTools" year="2026" desc="免费、开源、注重隐私的浏览器端工具箱。" tags="在线工具" github="https://github.com/zhijiantv/XuTools"]2. [resource] 推荐资源卡片
| 字段 | 说明 |
|---|---|
icon | 图标（emoji / 图片 / SVG） |
name | 资源名称 |
star | 评分 1–5（显示为 ⭐） |
desc | 资源描述 |
tags | 标签，可用 , ， 、 分隔，自动生成筛选按钮 |
url | 资源原链接（按钮「访问」） |
示例：
[resource icon="📚" name="MDN Web Docs" star="5" desc="最权威的 Web 技术文档。" tags="前端,文档,参考" url="https://developer.mozilla.org"]
[resource icon="⚡" name="Tailwind CSS" star="4" desc="实用优先的 CSS 框架。" tags="CSS,前端" url="https://tailwindcss.com"]🔑 重要：首页「随机推荐」卡片会随机读取 slug 为share的「推荐分享」独立页面里的[resource]短代码。所以把想被推荐的资源写在/share页面即可。
3. [blog] 优秀博客卡片
| 字段 | 说明 |
|---|---|
avatar | 头像（emoji / 图片 / SVG） |
name | 博客名称 |
url | 博客地址 |
star | 评分 1–5 |
status | 仅 近期更新 或 长期失联，其余按「近期更新」处理 |
desc | 博客简介 |
示例：
[blog avatar="✍️" name="阮一峰的网络日志" url="https://www.ruanyifeng.com/blog/" star="5" status="近期更新" desc="科技与生活的长期观察者。"]
[blog avatar="https://example.com/ava.png" name="某技术周刊" url="https://example.com" star="4" status="长期失联" desc="优质前端周报。"]四、独立页面搭建（必做）
XuCard 的卡片内容靠「独立页面 + 短代码」承载。请在后台新建以下独立页面，并在「模板」下拉中选择对应模板（需先启用本主题）：
| 页面标题 | 缩略名 slug | 选择模板 | 内容写法 |
|---|---|---|---|
| 归档 | archives | XuCard 归档独立页面 | 留空，模板自动按年分组时间线 |
| 我的项目 | projects | 我的项目(project) | 粘贴若干 [project] |
| 推荐分享 | share | 推荐分享(share) | 粘贴若干 [resource]（首页随机推荐来源） |
| 优秀博客 | blogs | 优秀博客(blog) | 粘贴若干 [blog] |
| 关注公众号 | gzh | 关注公众号(gzh) | 留空，靠自定义字段驱动 |
⚠️ 模板下拉里只有@package custom的page-*.php才会出现。XuCard 已全部正确声明，若下拉为空请确认主题文件完整。
关注公众号页（gzh）自定义字段
该页面内容留空，通过自定义字段（fields）填充，字段名如下：
| 字段名 | 说明 | 默认值（留空时） |
|---|---|---|
qrcodeUrl | 公众号二维码图片地址 | 无（建议必填） |
wxName | 公众号名称 | 指尖看世界 |
wxId | 微信号（带一键复制） | zhijian_kan |
wxDesc | 公众号简介 | 内置默认文案 |
bonusText | 关注福利（支持 <br> 换行） | 内置默认文案 |
在编辑器「自定义字段」区点「添加字段」，名称填上表字段名，值填内容即可。
五、首页逻辑说明
- 最新文章：自动读取最新文章，显示封面图（无图则用主题默认图
default-thumb.svg）+ 发布时间（Y/n/j）。 - 随机推荐：每次刷新随机从
/share页面的[resource]中取一条；整张卡片点击跳转/share，卡内资源名单独打开原链接。
两个卡片在移动端宽度与上边卡片一致；PC 端正常并排展示。
六、社交图标
首页社交区仅渲染已填写的链接，未填写项完全不显示，且为无卡片边框的圆形图标：
- GitHub：深色圆形按钮
- 公众号：微信绿
#07c160圆形按钮（官方双气泡图标） - 邮箱：天蓝圆形按钮（
mailto:或直接邮箱均可）
七、深色模式
后台「主题模式」决定默认值；前端右上角（或移动端顶栏）可随时切换，选择会保存到浏览器本地。所有卡片、文字、Banner 均使用主题 CSS 变量（--card / --text / --border 等），深浅色自动适配，无需额外配置。
八、部署与常见问题
1. 独立页面 / 文章 404
Typecho 1.3 任何非首页地址都必须由服务器转发给 index.php。请配置伪静态：
nginx：
location / {
try_files $uri $uri/ /index.php?$query_string;
}后台：设置 → 永久链接 → 启用地址重写。
2. 近期文章 / 归档 404
先确认已新建 slug=archives 的独立页面并选择「XuCard 归档独立页面」模板；若仍 404，可在后台「近期文章链接」手动填写可访问地址（如 /index.php/archives/）。
3. 短代码显示为纯文本
原因通常是：未在「源码模式」下粘贴，或卡片之间没空行导致 Markdown 段落包裹错位。切到源码模式重贴即可。
4. 图标只显示文字 / 残段
- 确认
icon是纯 URL（不要带<a>标签或多余空格）。 - 图片 URL 必须
http(s)://或/开头，否则按文本兜底显示首字符。
九、快速开始清单
- [ ] 启用 XuCard 主题
- [ ] 填写外观设置（昵称、头像、社交链接、Banner）
- [ ] 新建 5 个独立页面（archives / projects / share / blogs / gzh）并选对模板
- [ ] 在 projects 页粘贴
[project]，share 页粘贴[resource]，blogs 页粘贴[blog] - [ ] 在 gzh 页填写自定义字段（至少
qrcodeUrl） - [ ] 配置 nginx 伪静态，测试各页面无 404
完成以上步骤，你的 XuCard 站点即可完整运行。如有问题，优先检查「源码模式粘贴」与「伪静态转发」两个环节。
暂无评论