CardShadow 主题说明文档

一款基于 Typecho 的轻量级博客主题，灵感来自 Kehua 风格设计：清新绿色调、卡片阴影、内置音乐播放器，移动端深度适配。

• 主题名称：CardShadow（卡片阴影）
• 当前版本：v1.7.8（对应发布包 cardtheme-typecho-v17.zip）
• 适用平台：Typecho 1.2.x 及以上
• 设计风格：清新绿（Kehua Green）+ 卡片阴影 + 圆角 + 极简

✨ 核心特性

📦 安装方式

1. 下载主题包 cardtheme-typecho-v17.zip
2. 解压后将 cardtheme 目录上传到 Typecho 的 /usr/themes/ 下
3. 后台 → 控制台 → 外观 → 启用 CardShadow
4. 进入「设置外观」配置音乐链接、社交链接等

⚙️ 主题配置项

• 站点 Logo / 副标题
• 顶部音乐播放器：填写 mp3/m4a 直链（建议 HTTPS）
• 社交图标：GitHub / 邮箱 / RSS
• 首页置顶分类：勾选需要在首页置顶的分类
• 评论头像源：Gravatar / Cravatar / QQ 头像

🎵 音乐播放器说明

v1.7.8 增强了播放兼容性：

• HTTP 链接在 HTTPS 站点会自动升级为 https://
• 浏览器自动播放被拦截时，自动尝试 静音重试

• 加载失败时按钮变红，鼠标悬停显示具体错误：

  • MEDIA_ERR_NETWORK 网络错误
  • MEDIA_ERR_DECODE 解码失败
  • MEDIA_ERR_SRC_NOT_SUPPORTED 资源不可达
• 控制台日志统一前缀 [CardTheme Music] 便于排查

💬 评论与回复

• 回复框直接 追加到被回复评论的下方，不再跳转到页面顶部
• 多级嵌套自动限制缩进，防止深层回复溢出屏幕
• 回复框设置 box-sizing: border-box; max-width: 100%,移动端不撑破布局
• 管理员与游客都可正常评论 / 回复

📱 移动端置顶文章布局

针对置顶标签出现后挤压作者和时间的问题，已做以下优化：

• 分类名超长时使用 text-overflow: ellipsis 截断
• 置顶标签独立一行或与分类同行（自适应宽度）
• 作者、发布时间始终保留独立行，不被覆盖

🎨 设计 Token（节选）

--primary: 142 55% 45%;          /* 主色 */
--primary-soft: 142 50% 94%;     /* 主色浅底 */
--shadow-card: 0 2px 12px hsl(160 20% 10% / 0.06);
--shadow-hover: 0 8px 28px hsl(160 20% 10% / 0.1);
--gradient-primary: linear-gradient(135deg, hsl(142 55% 50%), hsl(155 50% 55%));
--radius: 0.75rem;

所有颜色采用 HSL 格式，便于暗色模式与全局调色。

📁 主题文件结构

cardtheme/
├── index.php          # 首页/列表
├── post.php           # 文章页
├── page.php           # 独立页面
├── archive.php        # 归档
├── header.php         # 头部 + 资源加载
├── footer.php         # 底部 + 播放器
├── sidebar.php        # 侧边栏
├── comments.php       # 评论模板
├── functions.php      # 主题函数 / 配置项
├── style.css          # 主样式
└── assets/
    ├── css/main.css
    ├── js/main.js     # 评论 / 播放器 / 交互
    └── img/

📝 版本更新日志

🛠️ 常见问题

Q: 切换主题后音乐不响？
A: 检查后台音乐链接是否为 HTTPS，并打开浏览器控制台查看 [CardTheme Music] 日志。

Q: 回复评论后页面跳到顶部？
A: 请确保已升级到 v1.7.5+，并清空浏览器缓存。

Q: 移动端置顶标签把作者顶下去？
A: 升级到 v1.7.4+ 并强制刷新（Ctrl+F5）。

Q: 暗色模式如何切换？
A: 跟随系统设置；也可在导航栏点击「☀/🌙」按钮手动切换。

📮 反馈与支持

• 主题预览站：本站
• 问题反馈：下方留言反馈