交互与视觉

本页梳理 matery 主题的交互与视觉功能：代码块增强、图片灯箱、打字机、页面特效、繁简转换、阅读进度、返回顶部、打赏、打印样式、音视频播放器与图表。每个功能给出配置位置与使用方法。

怎么读这页：每个功能都按「效果 → 对应配置」成对展示——先看它产出什么，再抄下面那段 YAML。参数表里的键全部出现在本页或 userConfig/_config.tmp.yml 中，未验证的值一律标注「其他值未验证」。

配置位置均在主题配置 themes/matery/_config.yml（文内简写"主题配置"）。注意：本项目 CI 构建时主题配置文件会被 userConfig/_config.tmp.yml 模板覆盖，修改请同步模板（见「安装与主题配置」篇）。部分功能无独立配置键（返回顶部、打印样式），由主题内置、开箱即用。

1. 代码块增强

用途：代码块自动附加语言标签、复制按钮、展开/折叠、全屏查看；超长代码自动限高。

学习路径：开语言标签 → 配复制与展开 → 调限高 → 全参数表 → 边界与冲突

1.1 如何启用

效果：下面的代码块就是真实渲染结果——右上角有语言标签，hover 出现复制按钮：

echo "Hello Matery"

对应配置（最小可用：语言标签 + 复制按钮，其余保持默认）：

code:
  language:
    enable: true
    default: "TEXT"
  copy_btn: true

标准 Markdown 代码块自动增强，不需要额外标记语法。

1.2 常用选项

① 限高与展开

效果：超过 height_limit（450px）的代码块默认折叠，底部出现"展开"条；点开后完整显示、不再限高。

对应配置：

code:
  height_limit: "450px"   # 超过该高度自动折叠
  show_full: true         # 折叠态底部给"展开"条

② 主动折叠

效果：代码块工具栏出现折叠按钮，读者可手动收起 / 展开整块代码。

对应配置：

code:
  shrink: true

③ 语言标签兜底

效果：未写语言、或语言无法识别时，右上角标签显示 default 指定的文案（默认 TEXT）。

对应配置：

code:
  language:
    enable: true
    default: "TEXT"    # 换成 "CODE" 则标签显示 CODE

④ 复制按钮

效果：hover 出现复制按钮，点击复制整块代码。false 时右上角只剩语言标签。

对应配置：

code:
  copy_btn: true

⑤ 全屏查看

效果：工具栏出现全屏按钮，点击后该代码块铺满视口（这也是 §17 偏好面板之外的另一套代码全屏入口）。

对应配置：

code:
  show_expand: true

⑥ 超宽行换行

效果：break: false 时超宽行不折行，改为横向滚动（本项目按此值使用）；true 则折行显示。

对应配置：

code:
  break: false

1.3 全部可调项

1.4 边界与冲突

• height_limit 落到 CSS 变量 --code-max-height；展开时 JS 把容器 maxHeight 设为 scrollHeight（不再受该值限制），收起时恢复为空、回到 450px。
• copy_btn / show_full / shrink 是三个独立按钮，可任意组合；全关则只剩裸代码块。
• 语言标签只在 language.enable: true 时输出；未识别语言回落 language.default。
• 改本段任一项都必须 clean 构建才生效（缓存不会自动感知配置变更）。

1.5 小结

• 最小可用：language.enable + copy_btn 两行就够。
• 怕长文爆炸：调 height_limit，show_full 负责给"展开"条。
• 改完不生效：先怀疑缓存，clean 构建。

2. 图片灯箱 lightGallery

用途：文章图片点击放大全屏浏览，支持缩放、翻页、下载，自动生成字幕。

学习路径：开灯箱 → 普通图片即可 → 换原图链接 → 全参数 → 边界

2.1 如何启用

效果：文章内的图片变为可点击，点击弹出黑色遮罩灯箱，可缩放 / 左右翻页 / 下载；图片下方显示 image_caption 生成的字幕。

对应配置（主题配置，位于 post 块内）：

post:
  image_zoom:
    enable: true            # 文章图片可点击放大

示例（普通 Markdown 图片即可，自动增强）：

![图片描述](/medias_webp/featureimages/1.webp)

2.2 常用选项

① 链接替换（缩略图 → 原图）

效果：灯箱里加载的是替换后的原图链接，而列表里仍是压缩图——省流量又不牺牲放大画质。

对应配置：

post:
  image_zoom:
    img_url_replace: ['-slim', '']   # 把链接中的 -slim 去掉；正则用 're:' 前缀

② 关闭灯箱

效果：图片不可点击，点击无任何反应；链接照旧显示。

对应配置：

post:
  image_zoom:
    enable: false

2.3 全部可调项

灯箱库本体由 libs.js.lightgallery / libs.css.lightgallery 加载（本地 /libs/lightGallery/...），非 image_zoom 的键；其他值未验证。

2.4 边界与冲突

• 灯箱初始化在文章页（#articleContent / #myGallery）完成；Matery.plugins.lightgallery(selector) 对这两个容器会直接返回、不重复初始化。wiki 页未验证。
• 灯箱依赖 lightgallery-all.min.js 已加载，缺失时函数直接 return，图片点击无反应。
• img_url_replace 是成对替换，写错顺序会把链接改坏；不确定就保留默认 ['', '']（不替换）。

2.5 小结

• 默认就该开：enable: true 一行，普通图片自动获得灯箱。
• 放大糊：用 img_url_replace 换回原图链接。
• 点了没反应：先看 lightgallery 资源是否加载成功。

3. 打字机 Typed

用途：Banner 副标题逐字打字轮播、文章页标题打字动画。

学习路径：开副标题打字 → 配句子列表 → 开文章标题打字 → 限定页面 → 全参数 → 冲突

3.1 如何启用

效果：首页 Banner 副标题从空开始逐字打出，打完停顿后删除、换下一句；文章页 H2 标题同样逐字出现，光标闪烁。

对应配置（主题配置，最小可用——只开副标题打字）：

fun_features:
  typing:
    enable: true

3.2 常用选项

① Banner 副标题打字（subtitle 块，含速度与轮播）

效果：轮播 sub 列表里的句子，循环播放，光标为 _。

对应配置：

subtitle:
  enable: true
  typed:
    loop: true          # 是否循环轮播
    showCursor: true    # 显示光标
    cursorChar: "_"     # 光标字符
    startDelay: 100     # 启动延迟(ms)
    typeSpeed: 80       # 打字速度(ms/字)
    backSpeed: 50       # 删除速度(ms/字)
  sub:                  # 轮播句子列表（逐句打出）
    - 真经一句话，假经传万卷！

② 另一入口：fun_features.typing（含页面范围）

效果：同一套副标题打字效果的第二个开关入口，scope 为空时全站开启；填页面名则只在那些页面打字。

对应配置：

fun_features:
  typing:
    enable: true
    typeSpeed: 70
    cursorChar: "_"
    loop: false
    scope: []           # home | post | tag | category | about | links | page | 404（空=全部）

③ 文章页 H2 标题打字

效果：文章（及其它 layout）的 H2 标题逐字出现；关闭后标题直接显示、无动画。

对应配置：

post:
  typed:
    enable: true
    loop: false
    showCursor: true
    cursorChar: "_"
    startDelay: 50
    typeSpeed: 70
    backSpeed: 50

3.3 全部可调项

3.4 边界与冲突

• subtitle.typed 与 fun_features.typing 是两个独立入口，同属 Banner 副标题；改动前先确认哪个在实际生效（两处都开时以代码读取顺序为准，其他组合未验证）。
• scope 只接受上表 8 个页面名；写错名字等于该页不开启（不会报错）。
• post.typed 作用于 H2，不影响 Banner；loop: false 时打完停在完整标题。
• 改配置后必须 clean 构建。

3.5 小结

• 只要副标题打字：fun_features.typing.enable 一行。
• 要控制在哪几页打字：用 scope，别关总开关。
• 小节标题也在动：那是 post.typed，独立开关。

4. 页面特效

用途：13 种装饰特效分两类——页面/背景特效（自动运行）与鼠标/点击特效（交互触发），运行时可通过右侧悬浮面板切换。

学习路径：开总开关 → 选一个页面特效 → 选一个鼠标特效 → 桌面门控 → 运行时切换 → 全参数 → 冲突

4.1 如何启用

效果：页面出现所选装饰动画（如樱花持续飘落）；鼠标移动/点击时出现所选点击特效；移动端默认不加载。

对应配置（主题配置 effects 块，2026-08-10 重构后的单一配置源）：

effects:
  enable: true            # 总开关：悬浮面板"页面特效"区是否显示
  page:
    default: sakura       # 樱花
  mouse:
    default: off

4.2 常用选项

① 页面/背景特效（单选）

效果：只有 default 指定的那一个生效——写 sakura 见樱花，写 ripples 见水波，写 off 什么都不加，写 random 每次从 available 随机取一个。

对应配置：

effects:
  page:                   # 页面/背景特效（互斥，选一个）
    default: off          # 默认：off | random | 具体 id
    available:
      sakura:         { label: 樱花,     lib: sakura }
      ripples:        { label: 水波,     lib: ripples }
      leaf:           { label: 落叶,     lib: leaf }
      snowdown:       { label: 飘雪,     lib: snowdown }
      snowflake:      { label: 雪花,     lib: snowflake }
      buble:          { label: 冒泡,     lib: buble }
      canvas_nest:    { label: 网络,     lib: canvas_nest }
      ribbon:         { label: 彩带,     lib: ribbon }
      ribbon_dynamic: { label: 动态彩带, lib: ribbon_dynamic }

② 鼠标/点击特效（单选）

效果：点击或移动鼠标时出现对应反馈——clicklove 爱心、mouseStar 星星、fireworks 爆炸、popupText 弹出文字。

对应配置：

effects:
  mouse:                  # 鼠标/点击特效（互斥，选一个）
    default: off
    available:
      clicklove:      { label: 爱心,     lib: clicklove }
      popupText:      { label: 弹出文字, lib: popupText }
      mouseStar:      { label: 星星,     lib: star }
      fireworks:      { label: 爆炸,     lib: fireworks }

③ 只在桌面端注入

效果：true 时移动端完全不加载特效脚本（省电省流量）；false 时移动端也加载。

对应配置：

effects:
  desktop_only: true      # 是否只在桌面端注入（移动端关闭，保性能）

④ 运行时切换（读者侧，不改代码）

效果：右侧悬浮面板 → "页面特效"区，可选 关闭 / 随机 / 具体特效；选择写入 localStorage，刷新后生效，优先级高于配置里的 default。

对应调用（等价于面板操作）：

localStorage.setItem('matery.effect.page', 'sakura');    // 刷新后页面出现樱花
localStorage.setItem('matery.effect.mouse', 'clicklove'); // 刷新后点击出爱心
localStorage.setItem('matery.effect.page', 'off');        // 关闭页面特效

⑤ 手动触发加载

效果：读取 window.Matery.effects（由模板注入的配置元数据）并按 page / mouse 各自的值加载脚本；无配置时是空操作、不报错。

对应调用：

Matery.plugins.effects();   // 立即按当前配置注入特效脚本

4.3 全部可调项

lib 对应 theme.libs.js.* 路径键；canvas_nest / ribbon 还支持 params 子键（颜色、数量等），其余库的 params 未验证。

4.4 边界与冲突

• page 与 mouse 两组各自单选：同组内配多个只有 default 指定的那个生效。
• 两组各自独立持久化：matery.effect.page 与 matery.effect.mouse 互不干扰；面板切换后刷新页面才生效。
• 桌面端门槛：desktop_only: true 时，仅当窗口宽度 > 断点 BP.fun（约 992px）且本地访问计数 > 1 才注入；移动端与首次访客不加载。
• 旧版独立的 sakura / ripples / clicklove 等 enable 配置段已删除，不再参与注入；增删特效改 available 清单即可，面板与运行时自动适配。
• 运行时逻辑在 themes/matery/source/js/plugins.js（Matery.plugins.effects）；配置元数据由 themes/matery/layout/_partial/script/effects.ejs 注入 window.Matery.effects。

4.5 小结

• 最小可用：effects.enable + page.default 一行选特效。
• 同组配多个没用：只有 default 生效。
• 桌面看不到：先看宽度是否超过断点，再看访问计数（首访不注入）。
• 想改主意：用悬浮面板切，别反复改配置。

4.6 节日灯笼（dengbox）

用途：页面左右两侧显示节日灯笼装饰（如"新春/快乐"），属于 fun_features 块（区别于上文的 effects 特效面板）。

效果：开启后页面左右两侧各挂一盏灯笼，文字可自定义；关闭即隐藏。

对应配置（主题配置 fun_features 块）：

fun_features:
  dengbox:
    enable: false   # false | true
    left: 新春      # 左侧灯笼文字
    right: 快乐     # 右侧灯笼文字

与 §4 的 effects 是两套机制：灯笼是静态装饰，不受特效面板控制。

5. 繁简转换

用途：页面内容繁体/简体一键切换，localStorage 记忆用户选择。

学习路径：开开关 → 看按钮 → 用 API 切换 → 全参数 → 冲突

5.1 如何启用

效果：页脚出现"繁/简"切换按钮（#translateLink）；点击后全站正文文字在简体与繁体之间转换，按钮文案同步反转，刷新后保持上次选择。

对应配置（主题配置，2026-08-16 已聚合至 preference 段）：

preference:
  translate:
    enable: true    # 繁简转换开关

5.2 常用选项

① 关闭转换

效果：页脚不再出现繁/简按钮，正文恒为原文。

对应配置：

preference:
  translate:
    enable: false

② 用 API 切换（不点按钮）

效果：调用后立即对正文做转换并翻转按钮文案；编码值同时写入本地存储，后续页面沿用。

对应调用：

Matery.plugins.languageToggle();              // 切换 简 ↔ 繁
Matery.plugins.languageToggle.getEncoding();  // 读取当前编码

5.3 全部可调项

5.4 边界与冲突

• 旧配置 footer.translate 已于 2026-08-10 删除（footer.ejs 注释确认），只读 preference.translate.enable。
• 转换是正文文本替换，不改代码块内文本以外的标记；与 i18n 语言下拉是两个独立机制（语言下拉换的是模板文案）。
• 按钮由 enable 决定是否输出，按钮之外的调用（API）不受 enable 限制。

5.5 小结

• 一行开关：preference.translate.enable。
• 找不到按钮：先确认没写旧的 footer.translate。
• 想脚本化：直接调 Matery.plugins.languageToggle()。

6. 阅读进度条 / 返回顶部

用途：顶部阅读进度条随滚动增长；右下角一键返回顶部。

学习路径：开进度条 → 调高度颜色 → 确认返回顶部 → 全参数 → 冲突

6.1 如何启用

效果：页面顶部出现一条彩色细进度条，随页面加载与滚动增长；右下角圆形按钮出现（滚动后可见），点击平滑回到顶部。

对应配置（主题配置，进度条在 fun_features 块内）：

fun_features:
  progressbar:
    enable: true        # 加载进度条（默认关闭）
    height_px: 3
    color: "#29d"

6.2 常用选项

① 高度与颜色

效果：进度条按 height_px 变粗、按 color 换色，立即体现在页面顶部。

对应配置：

fun_features:
  progressbar:
    height_px: 3
    color: "#29d"

② nprogress 行为参数

效果：showSpinner 关掉右上角转圈指示器；trickleSpeed 调小则进度条走得更快（10–100 量级常见）。

对应配置：

fun_features:
  progressbar:
    options: { showSpinner: false, trickleSpeed: 100 }   # nprogress 参数

③ 返回顶部（无独立配置键）

效果：#backTop 按钮内置于右侧浮动面板，默认启用、无需配置，平滑滚动，移动端尺寸自适应。

对应配置：无。按钮由 layout/_partial/common/right-floating.ejs 输出，见 §15 的另一套箭头入口。

6.3 全部可调项

除 showSpinner / trickleSpeed 外，options 的其余 nprogress 键未验证。

6.4 边界与冲突

• 进度条默认关闭，需要显式 enable: true。
• 返回顶部有两套入口：本节 #backTop（悬浮面板内）与 §15 scroll_top_arrow（独立箭头），可同时存在。
• options 是原样透传对象，写错键名不会报错、只是不生效。

6.5 小结

• 进度条一行开：progressbar.enable: true。
• 返回顶部不用配：内置。
• 两个回顶按钮：想只留一个，就把另一个的开关关掉。

7. 打赏弹窗

用途：文章底部"赏"按钮，点击弹出微信/支付宝二维码弹窗。

学习路径：开打赏 → 换二维码 → 单篇覆盖 → 全参数 → 冲突

7.1 如何启用

效果：文章底部出现"赏"按钮；点击弹出二维码 dialog，内部为支付宝/微信两个 tab，可点关闭按钮或点遮罩关闭。

对应配置（主题配置，位于 post 块内）：

post:
  reward:
    enable: true
    title: 码字辛苦，打赏作者！
    wechat: /medias_webp/reward/wechat.webp
    alipay: /medias_webp/reward/alipay.webp

7.2 常用选项

① 换弹窗标题

效果：弹窗顶部文案变为 title 的内容。

对应配置：

post:
  reward:
    title: 码字辛苦，打赏作者！

② 换二维码图

效果：对应 tab 内显示新图；本地路径或网络图片均可。

对应配置：

post:
  reward:
    wechat: /medias_webp/reward/wechat.webp
    alipay: /medias_webp/reward/alipay.webp

③ 单篇覆盖（front-matter）

效果：本文底部出现"赏"按钮（true）或不出现（false），优先于全局配置。

对应配置：

reward: true    # true 开启本文打赏 / false 关闭（默认按全局配置）

7.3 全部可调项

7.4 边界与冲突

• front-matter reward 覆盖全局 post.reward.enable；不写则跟随全局。
• 二维码图缺失时弹窗仍打开，只是图片加载失败（不报错）。
• 只在文章页输出，独立页面（wiki/about 等）不显示。

7.5 小结

• 最小可用：post.reward.enable + 两张图。
• 单篇关掉：front-matter reward: false。
• 换图不生效：先 clean 构建，再确认路径。

8. 打印样式

用途：打印文章时的排版优化（隐藏导航/侧栏/页脚、正文居中、链接显示 URL）。

学习路径：直接 Ctrl+P 看效果 → 确认无需配置 → 边界

8.1 如何启用

效果：Ctrl+P 打印时仅保留正文，隐藏导航栏、侧栏、页脚与浮动按钮；链接旁显示完整 URL；留白与字号针对纸张优化，且自动切换为浅色变量（暗色模式下打印不会出现黑底）。

对应配置：无需配置——打印样式内置在主题 CSS（source/css/_pages/_base/print.styl + color-schema.styl 的 @media print 规则），始终生效。

8.2 常用选项

① 用浏览器打印预览检查

效果：预览页只看到文章正文与标题，宽度铺满纸张；浮动按钮与背景特效全部消失。

对应操作：

浏览器 Ctrl+P → 预览 → 确认无侧栏/无黑色背景 → 打印或存为 PDF

② 想改打印样式

效果：改动 @media print 内的规则会直接改变打印结果；这属于改源码，不是配置项。

对应位置：

themes/matery/source/css/_pages/_base/print.styl
themes/matery/source/css/color-schema.styl（@media print 段）

8.3 全部可调项

无 YAML 配置键；改样式需改 styl 源码。

8.4 边界与冲突

• 打印样式与屏幕样式是两套规则，改屏幕 CSS 不影响打印，反之亦然。
• @media print 里切浅色变量，是为了暗色模式下打印不出现黑底白字。
• 各浏览器对背景色打印默认关闭，PDF 输出效果以浏览器设置为准。

8.5 小结

• 不用配：内置，Ctrl+P 即生效。
• 要定制：改 print.styl，改完 clean 构建。
• 打印一片黑：确认 color-schema.styl 的 @media print 段还在。

9. 音乐播放器 APlayer

用途：首页/全站吸底音乐播放器，MetingJS 解析网易云等平台歌单。

学习路径：开播放器 → 填平台/类型/ID → 选吸底或卡片 → 全参数 → 冲突

9.1 如何启用

效果：页面出现音乐卡片（封面 + 播放控制 + 进度条 + 歌单），或吸底悬浮条；点击播放开始播放歌单第一首。

对应配置（主题配置 music 块）：

music:
  enable: true            # 是否启用（默认关闭）
  server: netease         # 平台：netease | tencent | kugou | xiami | baidu
  type: playlist          # 类型：song | playlist | album | search | artist
  id: 4965675848          # 歌单/歌曲 ID

9.2 常用选项

① 吸底模式

效果：fixed: true 时播放器固定在页面底部悬浮，滚动不消失；false 时作为卡片嵌在页面里。

对应配置：

music:
  fixed: true             # true = 吸底模式（页面底部悬浮）

② 非吸底模式的标题

效果：卡片模式顶部显示 title.show 的文案；吸底模式该标题无效。

对应配置：

music:
  title:
    enable: true
    show: 听听音乐

③ 自动播放与循环顺序

效果：autoplay: true 进页面即尝试播放（浏览器策略可能拦截）；loop 控制单曲/列表循环，order 控制顺序或随机。

对应配置：

music:
  autoplay: false
  loop: 'all'             # 循环：all | one | none
  order: 'random'         # 顺序：list | random

④ 音量、折叠列表、歌词

效果：volume 设默认音量（用户手动调过后失效）；listFolded: true 歌单默认收起；hideLrc: true 不显示歌词。

对应配置：

music:
  volume: 0.7             # 默认音量（播放器会记忆用户设置）
  listFolded: true        # 列表默认折叠
  hideLrc: true           # 隐藏歌词

⑤ 独立音乐页（musics 块）

效果：单独的音乐页面播放器，配置键与 music 相同但独立；fixed: false 时为页内卡片。

对应配置：

musics:
  enable: true
  fixed: false            # 开启吸底模式
  type: playlist
  id: 4965675848

9.3 全部可调项

9.4 边界与冲突

• music 与 musics 是两套配置：前者全站/首页，后者独立音乐页，互不覆盖。
• title 只在非吸底模式有效。
• volume 只是初始值——播放器会记忆用户设置，改配置对老访客无效。
• autoplay: true 常被浏览器自动播放策略拦截，需用户首次交互。

9.5 小结

• 最小可用：enable + server + type + id 四项。
• 别挡内容：fixed: false 改卡片模式。
• 改音量没反应：清 localStorage，或用隐私窗口验证。

10. 视频播放器 DPlayer

用途：文章内嵌 DPlayer 视频播放器，支持本地视频、HLS 直播流与弹幕。

学习路径：最小标签 → 加封面/弹幕 → 全参数 → 冲突

10.1 如何启用

效果：文章内出现一个带播放控件（播放/暂停/进度/音量/倍速）的视频播放器，尺寸随容器自适应。

对应配置：无需主题配置——由 hexo-tag-mmedia 插件提供（DPlayer 资源路径在 libs.js.dplayer 配置）。

示例（{% mmedia %} 标签，第一参数指定播放器类型）：

{% mmedia dplayer url=/medias_webp/video/demo.mp4 %}

示例路径为示意，请替换为你自己的视频文件地址（本地路径或远程 URL 均可）。

10.2 常用选项

① 封面图

效果：播放前显示 pic 指定的封面，点播放后消失。

对应配置：

{% mmedia dplayer url=/medias_webp/video/demo.mp4 pic=/medias_webp/featureimages/1.webp %}

② 弹幕

效果：播放器出现弹幕输入框与弹幕层，id + api 指定弹幕库后端。

对应配置：

{% mmedia dplayer url=https://example.com/demo.mp4 pic=/medias_webp/featureimages/1.webp id=123456 api=https://api.prprpr.me/dplayer/v3/ %}

③ HLS 直播流

效果：url 指向 .m3u8 时按 HLS 播放（直播/切片流），进度条行为随流类型变化。

对应配置：

{% mmedia dplayer url=https://example.com/live.m3u8 %}

10.3 全部可调项

以上为 hexo-tag-mmedia 的 dplayer 参数；插件还支持其它参数，其他值未验证。

10.4 边界与冲突

• 播放器资源由 libs.js.dplayer 加载；缺资源时标签只留空白容器。
• url 必填，写错路径不会报错，只是播放失败。
• 弹幕需 id + api 成对提供，只给其一时弹幕不可用。

10.5 小结

• 最小可用：mmedia 标签 + dplayer url= 一行。
• 要弹幕：id + api 一起给。
• 直播：直接把 url 换成 .m3u8。

11. Bilibili 视频卡片

用途：嵌入 Bilibili 视频信息卡片（封面、标题、UP 主、播放量、时长）。

学习路径：填 BV 号 → 看卡片 → 边界

11.1 如何启用

效果：文章内渲染一张 Bilibili 视频卡片，含封面、标题、UP 主与播放数据，点击跳转原视频。

对应配置：无需主题配置——由 hexo-bilibili-card-new 插件提供。

示例（{% bilicard %} 标签 + BV 号，构建时拉取 API 渲染卡片）：

{% bilicard BV1oa4y1L7mw %}

11.2 常用选项

① 换视频

效果：换成另一个 BV 号，卡片封面/标题/UP 主随之变化。

对应配置：

{% bilicard BV1xx4y1X7xx %}

② 构建期拉取失败

效果：API 不可达时卡片退化为纯链接或空白区块，构建不中断。

对应配置：无需配置；属插件行为，失败时不影响文章其余内容。

11.3 全部可调项

插件其它参数未验证。

11.4 边界与冲突

• 卡片数据在构建时拉取，之后 B 站数据变化需重新构建才更新。
• 依赖外网可达；构建环境无网络时卡片不完整。
• 与 §10 的 {% mmedia %} 是两套标签，不要混用。

11.5 小结

• 只要 BV 号：{% bilicard BV... %}。
• 数据不更新：重新构建。
• 构建慢/失败：先查外网连通性。

12. ECharts 图表

用途：文章内嵌 ECharts 交互图表（柱状/折线/饼图等），支持缩放与数据提示。

学习路径：开库 → 最小图表 → 全参数 → 冲突

12.1 如何启用

效果：文章内出现一个可交互图表：鼠标悬停显示数据提示，图例可点击切换显示。

对应配置（主题配置 echarts 块，控制图表库加载）：

echarts:
  enable: true       # 是否加载 ECharts 库
  version: "latest"  # 库版本（默认 v6.1.0）

示例（{% echarts %} 标签，内容为 ECharts option JSON，首参为宽度、次参为高度）：

{% echarts '81%' 400 %}
{
  "title": {"text": "示例图表"},
  "xAxis": {"type": "category", "data": ["A", "B", "C"]},
  "series": [{"data": [10, 20, 30], "type": "bar"}]
}
{% endecharts %}

12.2 常用选项

① 图宽高

效果：首参为宽度（'81%' 相对容器、也可写 '600px'），次参为高度（像素）；图表按此尺寸渲染。

对应配置：

{% echarts '81%' 400 %}

② 换图表类型

效果：把 series[].type 从 bar 改成 line / pie，渲染出对应图形，交互能力不变。

对应配置：

{% echarts '81%' 400 %}
{
  "xAxis": {"type": "category", "data": ["A", "B", "C"]},
  "series": [{"data": [10, 20, 30], "type": "line"}]
}
{% endecharts %}

12.3 全部可调项

12.4 边界与冲突

• echarts.enable: false 时图库不加载，标签只留空容器。
• 标签内容必须是合法 JSON（不能写 JS 函数），否则解析失败、图表空白。
• 图表在内容注入后初始化；若在加密/动态插入的内容里使用，需配合刷新回调重新渲染。

12.5 小结

• 两行开库：enable + version。
• 图不显示：先验证 JSON 合法，再确认库已加载。
• 加密文章里不画：需要在解密后重新初始化。

13. 呼吸闪烁（blink）

用途：页面元素的呼吸/闪烁美化效果。

学习路径：开关 → 看效果 → 边界

13.1 如何启用

效果：开启后特定元素（如提示文字、hr 类装饰）带呼吸闪烁动画，明暗渐变循环；关闭则恢复静态。

对应配置（主题配置）：

blink:
  enable: true   # false | true

13.2 常用选项

① 关闭闪烁

效果：所有元素的呼吸动画消失，页面回归静态。

对应配置：

blink:
  enable: false

② 相关：hr 美化

效果：hr 分割线由默认细线变为主题风格的装饰线（与 blink 同为轻量美化开关，彼此独立）。

对应配置：

hr:
  enable: false   # false | true

13.3 全部可调项

13.4 边界与冲突

• 只有开关，无速度/幅度参数；要调节奏得改 styl 源码。
• 与 §4 的 effects 无关：这是元素级动画，不是页面特效。

13.5 小结

• 一个 bool：blink.enable。
• 想调节奏：改源码，不是改配置。

14. 在线客服（daovoice / tidio / tuxiaochao）

用途：三种第三方在线客服/联系组件，互不冲突，可同时启用。

学习路径：选一个平台 → 填凭据 → 看入口 → 冲突

14.1 如何启用

效果：启用后页面右下角出现该平台的客服入口（悬浮气泡/按钮），点击展开对话窗口。

对应配置（以 DaoVoice 为例）：

daovoice:
  enable: true
  app_id: your-app-id   # DaoVoice 应用 ID

14.2 常用选项

① DaoVoice

效果：右下角出现 DaoVoice 悬浮入口；app_id 为空时不加载。

对应配置：

daovoice:
  enable: false
  app_id:          # DaoVoice 应用 ID

② Tidio

效果：右下角出现 Tidio 聊天气泡；public_key 必须是该站点在 Tidio 后台的公钥。

对应配置：

tidio:
  enable: false
  public_key: ki6lsd8zq8isma7plzmwzuxgpnaihind   # Tidio 公钥

③ 腾讯兔小巢

效果：右下角出现兔小巢反馈入口，点开为产品反馈页。

对应配置（见 https://txc.qq.com/）：

tuxiaochao:
  enable: false
  productId: 350806   # 兔小巢产品 ID

14.3 全部可调项

14.4 边界与冲突

• 三者互不冲突、可同时启用，但右下角会叠多个入口（视觉上互相遮挡）。
• 均为第三方服务，需到对应平台注册获取凭据；凭据错误时脚本静默失败。
• 会引入第三方脚本，影响首屏与隐私策略，非必要不开。

14.5 小结

• 默认全关，按需开一个就好。
• 凭据别写错：app_id / public_key / productId 各管各的。
• 别同时开三个：入口会叠在一起。

15. 返回顶部箭头（scroll_top_arrow）

用途：右下角一键返回顶部的箭头按钮。

学习路径：开关 → 与 §6 区分 → 边界

15.1 如何启用

效果：页面右下角出现独立的上箭头按钮，点击平滑回到顶部；与 §6 的 #backTop 是两套入口。

对应配置（主题配置）：

scroll_top_arrow:
  enable: true

15.2 常用选项

① 关闭箭头

效果：该独立箭头消失；若 #backTop 仍在，返回顶部能力不受影响。

对应配置：

scroll_top_arrow:
  enable: false

15.3 全部可调项

15.4 边界与冲突

• 与 §6 的 #backTop 悬浮按钮是两套入口；此配置只控制独立箭头，enable: true 时显示。
• 两者同时开启时右下角可能出现两个回顶控件，需要按视觉取舍关掉一个。
• 无位置/颜色参数，改样式需改 styl。

15.5 小结

• 一个 bool：scroll_top_arrow.enable。
• 两个回顶：留一个即可。

16. 页面背景（background）

用途：全站页面背景——图片背景（可随机）或视频背景，外加加载动画。与 §4 的 effects 页面特效是两套独立机制。

学习路径：开总开关 → 选默认模式 → 配图库随机 → 配视频 → 配加载动画 → 全参数 → 冲突

16.1 如何启用

效果：页面底层出现所选背景（图片或视频），并可将卡片半透明叠在上面；配合加载动画在首次进入时播一段过场。

对应配置（主题配置）：

background:
  enable: true        # 总开关：false 时图片/视频背景都不渲染
  default: off        # 面板未设置时的默认背景：image | video | off

16.2 常用选项

① 图片背景（含随机图库）

效果：random: true 时按明暗主题分别从 lightPath / darkPath 图库随机取一张（数量由 lightNum / darkNum 决定）；false 时固定用 url。

对应配置：

background:
  image:
    enable: true
    url: "{mediaUrl}/medias_webp/sea.webp"   # 首次访问默认背景图
    random: true        # 随机背景：从亮/暗两组图库随机选一张
    lightNum: 45        # 亮色随机图数量（0 开始编号）
    lightPath: /medias_webp/featureimages/   # 亮色图库路径
    darkNum: 22         # 暗色随机图数量（0 开始编号）
    darkPath: /medias_webp/featureimages/dark/  # 暗色图库路径

② 视频背景

效果：按 url 指向的 JSON 列表随机播放一段视频，并叠加 cover 封面；brightness 决定该条视频配亮还是暗主题。

对应配置：

background:
  video:
    enable: true
    url: /video_url.json?v=1.0.0   # 视频列表 JSON（本地静态文件）
                                   # 结构 [{video: webmURL, cover: webpURL, brightness: bright|dark}]

③ 加载动画

效果：首次进入页面时先播指定过场动画（1 吃豆豆 / 2 方块 / 3 圆圈），time 为强制开启时长（ms），off 关闭。

对应配置：

background:
  loading:
    enable: true
    type: "off"         # 默认动画类型：off 关闭 | 1 吃豆豆 | 2 方块 | 3 圆圈
    time: 350           # 强制开启时长 ms（1000=1s）

④ 运行时切换（读者侧）

效果：面板"网页背景"选 off / image / video、"加载动画"选 off / 1 / 2 / 3，选择写入 localStorage，刷新后生效，优先级高于 background.default。

对应调用（等价于面板操作）：

localStorage.setItem('matery.bg', 'image');      // 刷新后启用图片背景
localStorage.setItem('matery.loading', '2');     // 刷新后播方块加载动画
localStorage.removeItem('matery.bg');            // 清除偏好 → 回落 background.default

16.3 全部可调项

16.4 边界与冲突

• 开关层级为 background.enable（总）→ 各子 enable → 面板选择；任一层关闭即不渲染。
• random: true 时按明暗主题从 lightPath / darkPath 图库随机取图，lightNum / darkNum 是可用图片数（从 0 开始编号）。
• 视频背景的 brightness 字段由亮暗主题过滤（封面灰度 ≥90 为 bright / <90 为 dark）。
• 图片与视频互斥（面板单选 matery.bg），加载动画独立单选。
• 与 §4 effects 是两套机制：背景管底层画面，特效管飘落/点击动画。

16.5 小结

• 最小可用：background.enable + default: image。
• 每次换图：random: true + 图库路径与数量。
• 想关掉背景区：background.enable: false（面板里对应区域也消失）。

17. 偏好面板（right-floating）

用途：右下角悬浮按钮组中的齿轮按钮（#fp-toggle）唤出"偏好设置"面板，读者无需改代码即可调整阅读偏好。面板本体恒显示，其中"特效""背景"区分别由 effects.enable / background.enable 控制显隐。

学习路径：字体缩放 → 语言/简繁 → 显示模式 → 特效与背景 → 分区一览

17.1 如何启用

效果：右下角出现齿轮按钮，点击展开面板，内含字体缩放、语言/简繁、显示模式、页面特效、鼠标特效、网页背景、加载动画七个分区；所有选择跨页面持久保留。

对应配置：面板本体恒显示，无 YAML 总开关；其中"特效"区由 effects.enable 控制、"背景"区由 background.enable 控制。

effects:
  enable: true       # false → 面板"页面特效/鼠标特效"区消失
background:
  enable: true      # false → 面板"网页背景/加载动画"区消失

17.2 常用选项

① 字体缩放

效果：A− / A+ / 恢复默认 按 0.1 步进调整（范围 0.85–1.3），全站 rem 字号等比缩放并触发排版重排；选择写入 localStorage matery.font-scale。

对应调用（等价于点按钮）：

document.documentElement.style.setProperty('--font-scale', '1.2');  // 全站字号 ×1.2
localStorage.setItem('matery.font-scale', '1.2');                   // 刷新后保持

② 语言 / 简繁

效果：语言下拉切换全站语言；"简/繁"分段控件与 §5 同一机制（cookie + 正文转换），切换后正文立即变化。

对应调用：

Matery.plugins.languageToggle();               // 简 ↔ 繁
Matery.plugins.languageToggle.getEncoding();   // 当前编码

③ 显示模式

效果：亮 / 自动 / 暗 单选，复用 color-schema.js 的存储与 data-user-color-scheme 属性，切换即时生效、刷新保持；选"自动"则清除本地选择、回到 prefers-color-scheme。

对应调用：

document.documentElement.setAttribute('data-user-color-scheme', 'dark');
localStorage.setItem('Matery_Color_Scheme', 'dark');   // 刷新后保持
document.documentElement.removeAttribute('data-user-color-scheme');  // 回到自动

④ 页面特效 / 鼠标特效

效果：各为 关闭 / 随机 / 具体特效，选择写入 localStorage，刷新后生效（详见 §4）。

对应配置：

localStorage.setItem('matery.effect.page', 'sakura');
localStorage.setItem('matery.effect.mouse', 'clicklove');

⑤ 网页背景 / 加载动画

效果：背景 off / image / video 单选；加载动画 off / 1 / 2 / 3 单选（详见 §16）。

对应配置：

localStorage.setItem('matery.bg', 'image');
localStorage.setItem('matery.loading', '2');

17.3 全部可调项

17.4 边界与冲突

• 面板本体恒显示；只有"特效""背景"两区受 effects.enable / background.enable 控制显隐。
• 字体缩放改的是 <html> 上的 --font-scale，根字号 = calc(--font-size-base × --font-scale)（默认 16px × 1）；直接写死 px 的样式不跟随缩放。
• 显示模式与 color-schema.js 共用同一个 localStorage 键，两处入口（菜单按钮 / 面板）互相同步。
• 涉及文件：模板 themes/matery/layout/_partial/common/right-floating.ejs；字号变量 themes/matery/source/css/_pages/_base/base.styl、color-schema.styl。

17.5 小结

• 读者自助：绝大多数偏好问题先让读者用面板调，不用改配置。
• 两区可藏：effects.enable / background.enable 关掉即从面板消失。
• 直连存储：所有偏好都在 localStorage，清掉即回落配置默认值。

附：交互视觉功能速查表