侧边栏组件

本页讲解侧边栏与首页小部件：页面级统计组件（标签云/词云/分类雷达/归档/图表）、Live2D 看板娘、音乐播放器。前两者由主题自动渲染，后两者有独立配置。

主题配置以 userConfig/_config.tmp.yml 为权威源（CI 时覆盖主题配置）。

阅读方式：每节都按「如何启用 → 常用选项 → 全部可调项 → 边界与冲突」展开，先看效果，再看产生该效果的对应配置，复制即可用。

1. 页面级组件（自动渲染）

用途：以下组件由主题生成器按页面自动渲染，无需配置，随内容自动更新。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

1.1 如何启用

效果：打开 /tags/ 看到标签 chip 列表 + canvas 词云（字号 ∝ 文章数）；打开 /categories/ 看到分类云 + 雷达图；打开 /archives/ 看到时间线与日历。不需要改任何配置，建好内容即出现。

对应配置：无（组件由 layout 模板自动挂载）。

themes/matery/layout/_partial/widget/

1.2 常用选项

① 调整标签云内容

效果：标签列表与词云的词、字号分布随文章 tags 变化；新增标签后词云多一项。

对应配置（文章 front-matter）：

tags:
  - Hexo
  - 教程

② 调整分类雷达图

效果：雷达图的轴与数值随 categories 变化；分类层级越深，分布越细。

对应配置（文章 front-matter）：

categories:
  - 教程
  - Hexo

1.3 全部可调项

组件清单（对应 themes/matery/layout/_partial/widget/ 目录）：

1.4 边界与冲突

• 这些组件挂在对应 layout 上，页面数据来自站点内容本身。
• 想"配置"它们，本质是调整内容结构（如标签命名、分类层级），或修改 themes/matery/layout/_partial/widget/*.ejs 模板（高级定制）。
• 没有文章时词云/雷达图会显示空图，不是配置错误。

1.5 小结

• 最小可用：什么都不用配，发文章即可
• 想改分布：调标签/分类命名与层级
• 想改样式：改 _partial/widget/*.ejs
• 空图：先确认有已发布文章

2. Live2D 看板娘（live2dWidget）

用途：右下角/左下角的 Live2D 看板娘（纯静态模型，无 PHP 后端），与用户交互提示语。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

2.1 如何启用

效果：页面角落出现会呼吸、会跟随鼠标的 Live2D 模型，点击/悬停弹出提示气泡。

对应配置（主题配置）：

live2dWidget:
  enable: true   # 总开关

2.2 常用选项

① 模型与提示语

效果：换成另一个角色模型，或改气泡里显示的提示文字。

对应配置（资源路径，非主题配置）：

source/live2d/model_list.json     # 模型清单
source/live2d/model/              # 本地模型
themes/matery/source/libs/live2d/waifu-tips.json   # 提示语

② 自动加载脚本路径

效果：页面加载 autoload.js 后看板娘才被创建；路径错误则完全不出现。

对应配置：

libs:
  js:
    live2dAutoload: /libs/live2d/autoload.js

③ 菜单定位选择器

效果：导航菜单里的 menu-2d-home 等 class 决定看板娘提示框出现的位置。

对应配置（菜单配置）：

menu:
  home:
    class: menu-2d-home

2.3 全部可调项

2.4 边界与冲突

• 模型与提示语配置在 source/live2d/（模型静态化）与 waifu-tips 相关文件中，独立于主题配置管理。
• 菜单项里的 class: menu-2d-*（如 menu-2d-home）是看板娘提示文字框的定位选择器（见「导航菜单与首页」篇）。
• 模型添加/删除/切换的完整操作见博客的 live2d 维护文档。
• 双运行时：Cubism 2（live2d.min.js）与 Cubism 5（live2dcubismcore.min.js）并存，autoload.js 按模型版本分别加载（cubism2Path / cubism5Path）。
• 本地模型：模型与清单位于 source/live2d/model/ 与 source/live2d/model_list.json。
• 真实配置键：主题配置仅 live2dWidget.enable 一个开关；自动加载脚本路径为 libs.js.live2dAutoload → /libs/live2d/autoload.js，运行时资源（autoload.js / waifu-tips.js / waifu.css）在 themes/matery/source/libs/live2d/。
• 提示语可配置：是——autoload.js 以 waifuPath 指向 waifu-tips.json，改该文件即可自定义提示语。
• 暗色适配：waifu.css 同时支持手动暗色（[data-user-color-scheme="dark"]）与系统偏好（prefers-color-scheme: dark）。
• 加载门槛：layout/_partial/script/live2d.ejs 仅在窗口宽度 > BP.fun 且访问计数 > 2 时加载。

2.5 小结

• 最小可用：live2dWidget.enable: true
• 换角色：改 model_list.json + model/
• 改台词：改 waifu-tips.json
• 不显示：先看窗口宽度与访问计数门槛

3. 音乐播放器（music / musics）

用途：基于 APlayer + Meting 的音乐播放器，支持网易云/QQ 音乐等平台歌单。分两处：

• music：首页（非吸底模式，可自动隐藏）
• musics：独立音乐页 /musics/（吸底模式，全站悬浮）

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

3.1 如何启用

效果：首页出现一个音乐卡片（标题「听听音乐」+ 播放按钮 + 歌单），滚动时可自动隐藏；打开 /musics/ 则出现悬浮在页面底部的播放条，切页不断播。

对应配置（主题配置，首页）：

music:
  enable: true
  title:
    enable: true
    show: 听听音乐
  server: netease
  type: playlist
  id: 4965675848

对应配置（主题配置，独立音乐页）：

musics:
  enable: true
  server: netease
  type: playlist
  id: 4965675848

3.2 常用选项

① 选平台与内容类型

效果：server + type + id 三者决定播放什么。例如 netease + playlist + 4965675848 播该网易云歌单；tencent + song + 歌曲 ID 播单曲。

对应配置：

music:
  server: netease
  type: playlist
  id: 4965675848

② 吸底模式（仅 musics）

效果：fixed: true 时播放器悬浮在视口底部，滚动不消失；false 时随页面滚动。

对应配置：

musics:
  fixed: true

③ 自动播放

效果：true 时进入页面即尝试播放（受浏览器自动播放策略限制）。

对应配置：

musics:
  autoplay: true

④ 主题色

效果：播放器按钮与进度条变成指定颜色。

对应配置：

musics:
  theme: '#42b983'

⑤ 循环与顺序

效果：loop 控制单曲/列表循环/不循环；order 控制顺序播放或随机。

对应配置：

musics:
  loop: 'all'
  order: 'random'

⑥ 预加载与音量

效果：preload 决定页面加载时是否预取音频；volume 是初始音量（用户手动调过之后失效）。

对应配置：

musics:
  preload: 'auto'
  volume: 0.7

⑦ 列表展示

效果：listFolded: true 时歌单默认收起；listMaxHeight 限制展开后列表高度，超出滚动。

对应配置：

musics:
  listFolded: true
  listMaxHeight: "525px"

⑧ 首页自动隐藏 / 隐藏歌词

效果：autoHide: true 时首页播放器向下滚动自动收起；hideLrc: true 时不显示歌词。

对应配置：

music:
  autoHide: true
  hideLrc: true

3.3 全部可调项

3.4 边界与冲突

• id 填对应平台的歌单/歌曲 ID（网易云歌单 ID 可直接在网页 URL 中看到）。
• 播放器会记忆用户设置——用户手动调过音量后，volume 默认值即失效。
• 首页 music 与音乐页 musics 是两套配置，互不继承；改一处不影响另一处。
• title 仅在非吸底模式有效（吸底条没有标题栏）。

3.5 小结

• 最小可用：enable + server + type + id
• 全站背景音乐：musics.fixed: true
• 不想自动响：autoplay: false
• 音量不生效：用户手动调过，属预期行为

4. 其他首页小部件

用途：首页与关于页可挂载的其余小部件（梦想语录、视频、推荐、相册/项目/技能、说说、广告）。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

4.1 如何启用

效果：首页依次出现「梦想语录」卡片、视频区块、推荐文章位；关于页出现相册/项目/技能卡片；侧边栏出现说说与广告。

对应配置：每个部件各有一段配置，见 4.2 与 4.3。

4.2 常用选项

① 梦想语录

效果：首页出现一句引言，可带标题。

对应配置（主题配置）：

dream:
  enable: true
  showTitle: false
  title: 追梦
  text: "凡我所失，皆非我所有……"

② 首页视频

效果：首页出现视频播放器（url 或 iframeUrl 二选一）。

对应配置（主题配置）：

video:
  enable: true
  url: https://example.com/video.mp4

③ 推荐文章

效果：首页出现推荐位，展示指定文章。

对应配置（主题配置）：

recommend:
  enable: true
  showTitle: true
  useConfig: false

④ 关于页相册/项目/技能

效果：/about/ 出现图片墙、项目网格、技能进度条。

对应配置（主题配置）：

myGallery:
  enable: true
myProjects:
  enable: true
mySkills:
  enable: true

⑤ 说说（Artitalk）

效果：/bb/ 页面出现短动态列表（当前未启用）。

对应配置（主题配置）：

artitalk:
  enable: false

⑥ 广告卡片

效果：侧边栏出现广告卡片。

对应配置（主题配置）：

post:
  advertisements:
    - id: "ad-1"
      text: "广告文案"
      enable: true

4.3 全部可调项

themes/matery/layout/_partial/widget/ 还包含以下可挂载组件，启用方式见对应 layout 模板：

4.4 边界与冲突

• 各部件只在对应 layout 上渲染：首页部件不会出现在文章页，关于页部件不会出现在首页。
• video 的 url 与 iframeUrl 至少填一个，否则播放器无内容。
• 关于页三个部件（§6–§8）各有独立 enable，不要只开一个就期待三者都出现。

4.5 小结

• 最小可用：按需只开一个部件
• 首页太满：关 video 或 recommend
• 关于页空：检查 myProjects / mySkills / myGallery 的 enable 与 data

5. 关于页个人信息（profile）

用途：/about/ 关于页顶部的个人信息卡片——头像、职业、个人介绍。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

5.1 如何启用

效果：关于页顶部左侧出现圆形头像，右侧是职业标签与多行个人介绍。

对应配置（主题配置）：

profile:
  avatar: /medias_webp/avatar.webp
  career: IIoT | TI方案 | 安防
  introduction: 嵌入式领域专家：
  introDetail:
    - 做遍安防前端、后端所有产品线……

5.2 常用选项

① 换头像

效果：关于页顶部头像换成指定图片（建议正方形，圆形裁切）。

对应配置：

profile:
  avatar: /medias_webp/my-avatar.webp

② 职业标签

效果：每个 | 分隔的片段显示为一个独立标签。

对应配置：

profile:
  career: Linux | Docker | 嵌入式

③ 多行介绍

效果：列表每项渲染为一行，顺序与列表一致。

对应配置：

profile:
  introDetail:
    - 第一行介绍
    - 第二行介绍

5.3 全部可调项

5.4 边界与冲突

• introDetail 为列表，每项一行介绍；career 用 | 分隔多个职业标签。
• 头像放 source/ 下用绝对路径引用；外链需完整 URL。

5.5 小结

• 最小可用：avatar + introduction
• 多标签：career 用 | 分隔
• 多行介绍：往 introDetail 加列表项

6. 关于页项目（myProjects）

用途：/about/ 关于页的"我的项目"卡片网格。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

6.1 如何启用

效果：关于页出现项目卡片网格，每张卡有图标、图标底色、项目名、描述，点击跳转链接。

对应配置（主题配置）：

myProjects:
  enable: true
  data:
    LinuxPTTools:
      icon: fab fa-linux
      iconBackground: 'linear-gradient(to bottom right, #66BB6A 0%, #81C784 100%)'
      url: https://github.com/appotry/PTtool
      desc: 为PT用户设计，方便同时刮削和做种。

6.2 常用选项

① 增加一个项目

效果：网格里多一张卡片；键名即项目名。

对应配置：

myProjects:
  data:
    MyTool:
      icon: fab fa-github
      url: https://github.com/you/my-tool
      desc: 一句话描述

② 换图标与底色

效果：卡片图标变成指定 Font Awesome 图标，图标背景变成指定渐变/纯色。

对应配置：

myProjects:
  data:
    MyTool:
      icon: fas fa-tools
      iconBackground: 'linear-gradient(to bottom right, #29B6F6 0%, #1E88E5 100%)'

③ 关闭整个区块

效果：关于页不再出现项目网格。

对应配置：

myProjects:
  enable: false

6.3 全部可调项

6.4 边界与冲突

• data 下每个键是一个项目（键名即项目名，可用 : 分组如 Docker:hexo）。
• 不需要展示时把 enable 设为 false 或删除整段。
• icon 必须是 Font Awesome 已加载的 class，写错则图标空白。

6.5 小结

• 最小可用：enable: true + 一个项目
• 加项目：往 data 加键
• 换图标：icon + iconBackground
• 整块不要：enable: false

7. 关于页技能（mySkills）

用途：/about/ 关于页的"我的技能"进度条列表。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

7.1 如何启用

效果：关于页出现若干条技能名 + 彩色进度条，进度长度等于 percent。

对应配置（主题配置）：

mySkills:
  enable: true
  data:
    C语言:
      background: 'linear-gradient(to right, #2196F3 0%, #42A5F5 100%)'
      percent: 90%

7.2 常用选项

① 增加技能

效果：列表多一行技能，键名即技能名。

对应配置：

mySkills:
  data:
    Python:
      background: 'linear-gradient(to right, #FF0066 0%, #FF00CC 100%)'
      percent: 80%

② 调熟练度

效果：进度条长度按百分比变化；percent 越大条越长。

对应配置：

mySkills:
  data:
    Python:
      percent: 60%

7.3 全部可调项

7.4 边界与冲突

• data 下每个键是一项技能（键名即技能名），percent 控制进度条长度。
• percent 需要带 %；写成纯数字可能不渲染（其他写法未验证）。

7.5 小结

• 最小可用：enable: true + 一项技能
• 加技能：往 data 加键
• 调长度：改 percent
• 别忘 %：90% 而不是 90

8. 关于页相册（myGallery）

用途：/about/ 关于页的"我的相册"图片墙。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

8.1 如何启用

效果：关于页出现图片网格，每张图等宽排列，点击可看大图（单图，无标题描述）。

对应配置（主题配置）：

myGallery:
  enable: true
  data:
    - /medias_webp/featureimages/0.webp
    - /medias_webp/featureimages/1.webp

8.2 常用选项

① 加图/删图

效果：网格图片数量与 data 数组长度一致，顺序即展示顺序。

对应配置：

myGallery:
  data:
    - /medias_webp/my/1.webp
    - /medias_webp/my/2.webp

② 关闭图片墙

效果：关于页不再出现相册区块。

对应配置：

myGallery:
  enable: false

8.3 全部可调项

8.4 边界与冲突

• data 为图片路径数组，每项一张图；图片放 source/ 下用绝对路径引用。
• 与 /galleries/ 独立相册页的区别：myGallery 是关于页的简单图片墙（仅 data 路径数组，无标题/描述）；独立相册页数据在 source/_data/galleries.yml（含封面/描述/灯箱，见「布局与页面」篇 §4），两者数据源不同、互不影响。

8.5 小结

• 最小可用：enable: true + data 数组
• 要标题/描述：用独立相册页，不要用 myGallery
• 图片不显示：检查路径是否在 source/ 下

9. 归档页文章日历（postCalendar）

用途：/archives/ 归档页是否显示"文章日历"控件（按日期高亮发文日）。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

9.1 如何启用

效果：归档页顶部出现月历，发文日期带高亮标记；点击日期可跳转对应文章。

对应配置（主题配置）：

postCalendar: true

9.2 常用选项

① 关闭日历

效果：归档页只剩时间线，不再显示月历。

对应配置：

postCalendar: false

9.3 全部可调项

9.4 边界与冲突

• 布尔开关，true 时归档页顶部显示日历，发文日期高亮。
• 只影响 /archives/，不影响文章页或首页。

9.5 小结

• 最小可用：postCalendar: true
• 归档页太满：设 false

10. 哔哔时间（bbtime）

用途：侧边栏"哔哔"（说说/动态）组件，基于 LeanCloud 存储。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

10.1 如何启用

效果：侧边栏出现"哔哔"卡片，列出最近的短动态，可展开输入框发布。

对应配置（主题配置）：

bbtime:
  enable: true
  appId: your-app-id
  appKey: your-app-key
  serverURLs: https://your-api.example.com

10.2 常用选项

① 填 LeanCloud 凭据

效果：动态能读能写；凭据错误则卡片空白或报错。

对应配置：

bbtime:
  appId: your-app-id
  appKey: your-app-key

② 填 API 地址

效果：连到你的 LeanCloud 应用节点（国际版域名不同）。

对应配置：

bbtime:
  serverURLs: https://your-api.example.com

10.3 全部可调项

10.4 边界与冲突

• 需在 LeanCloud 创建应用获取 appId/appKey；serverURLs 填你的 LeanCloud API 地址（国际版为 https://appid前八位.api.lncldglobal.com）。
• 与 §12 Artitalk 是两套说说方案，不要同时开。

10.5 小结

• 最小可用：enable + 两个凭据 + serverURLs
• 国内版/国际版：注意 serverURLs 域名不同
• 和 Artitalk 二选一

11. 推荐文章（recommend）

用途：首页推荐位——展示指定文章列表，可配置标题与数据来源。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

11.1 如何启用

效果：首页出现"推荐文章"区块，列出若干篇指定文章（标题 + 封面）。

对应配置（主题配置）：

recommend:
  enable: true
  showTitle: true
  useConfig: false

11.2 常用选项

① 用配置文件指定文章

效果：推荐位内容改为 source/_data/recommends.json 里的列表，不动主题配置即可换推荐。

对应配置（主题配置）：

recommend:
  useConfig: true

数据源（useConfig: true 时）：主题侧无模板文件，需自行创建 source/_data/recommends.json（结构：{"recommends": [...]}）：

{
  "recommends": [
    { "title": "推荐文章标题", "url": "/posts/xxx/", "cover": "/medias_webp/cover/xxx.webp" }
  ]
}

② 隐藏区块标题

效果：推荐位不再显示"推荐文章"标题，只剩卡片。

对应配置：

recommend:
  showTitle: false

11.3 全部可调项

11.4 边界与冲突

• useConfig: false（默认）时推荐文章由主题配置的 top 属性决定；useConfig: true 时改 source/_data/recommends.json 即可，无需动主题。
• 数据文件改动后需清缓存重建（rm -f db.json && hexo generate 或 tools/cicd.sh -d），否则读到旧数据。

11.5 小结

• 最小可用：enable: true
• 频繁换推荐：useConfig: true + JSON
• JSON 不生效：先清 db.json

12. 说说（artitalk）

用途：动态"说说"组件（类似微博/朋友圈短动态），基于 LeanCloud 存储，独立页面 /bb/ 展示。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

12.1 如何启用

效果：打开 /bb/ 出现说说列表与发布框，发布后即时显示。

对应配置（主题配置）：

artitalk:
  enable: true
  appId: your-app-id
  appKey: your-app-key

还需创建页面（见 12.4）。

12.2 常用选项

① LeanCloud 凭据

效果：说说能读写；凭据错误时列表空白。

对应配置：

artitalk:
  appId: your-app-id
  appKey: your-app-key

② 创建 /bb/ 页面

效果：站点多出 /bb/ 路由，用 Artitalk 布局渲染。

对应配置（页面 front-matter）：

layout: bb

12.3 全部可调项

12.4 边界与冲突

• 当前未启用（enable: false）。启用需：① LeanCloud 创建应用，建 content Class（含 content 列，String 类型）；② 记录 appid/appKey；③ hexo new page bb 创建 /bb/ 页面，front-matter 设 layout: bb。
• 官方文档见 artitalk.js.org。

12.5 小结

• 最小可用：enable + 两凭据 + /bb/ 页面
• 只差页面：hexo new page bb + layout: bb
• 没建 Class：先去 LeanCloud 建 content

附：侧边栏组件速查表

阅读顺序建议：先配 profile / myProjects / mySkills / myGallery 把关于页填满，再决定首页部件（dream / video / recommend），最后按需开全站组件（live2dWidget / music / musics）。每个部件的 enable 都是独立开关，关掉即可排除故障。