加载中...

交互与视觉

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

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

1. 代码块增强

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

配置（主题配置 code 块）：

code:
  shrink: true                # 代码块可收缩（折叠小箭头）
  break: false                # 超长行是否折行
  show_full: true             # 超长代码显示"展开全部"按钮
  height_limit: "450px"       # show_full 高度阈值（超过显示展开按钮）
  show_expand: true           # 全屏查看按钮
  copy_btn: true              # 复制代码按钮
  language:
    enable: true              # 显示语言标签
    default: "TEXT"           # 无语言标识时的默认标签

示例（标准 Markdown 代码块自动增强，无需额外标记）：

```bash
echo "Hello Matery"
```

效果：右上角语言标签；hover 显示复制/全屏按钮；超过 height_limit 的代码块折叠并显示"展开"按钮。

2. 图片灯箱 lightGallery

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

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

post:
  image_zoom:
    enable: true            # 文章图片可点击放大
    img_url_replace: ['', '']  # 放大时链接替换规则（如 ['-slim', ''] 去压缩后缀；正则用 're:' 前缀）

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

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

效果：文章渲染时图片自动被包装为 .img-item（含 data-src 原图链接与字幕），点击弹出 .lg-outer 灯箱；hover 有阴影边框。

3. 打字机 Typed

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

配置（主题配置，两处独立）：

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

# 副标题打字机开关/范围（fun_features 块内，另一入口）
fun_features:
  typing:
    enable: true
    typeSpeed: 70
    cursorChar: "_"
    loop: false
    scope: []           # 指定页面开启：home | post | tag | category | about | links | page | 404（空=全部）

# 文章页 H2 标题打字机（post 块内）
post:
  typed:
    enable: true
    loop: false
    showCursor: true
    cursorChar: "_"
    startDelay: 50
    typeSpeed: 70
    backSpeed: 50

效果：首页 Banner 副标题逐字打出并轮播切换；文章页标题（H2）打字动画；光标闪烁。

4. 页面特效

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

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

effects:
  enable: true            # 总开关：悬浮面板"页面特效"区是否显示
  desktop_only: true      # 是否只在桌面端注入（移动端关闭，保性能）
  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 }
  mouse:                  # 鼠标/点击特效（互斥，选一个）
    default: off
    available:
      clicklove:      { label: 爱心,     lib: clicklove }
      popupText:      { label: 弹出文字, lib: popupText }
      mouseStar:      { label: 星星,     lib: star }
      fireworks:      { label: 爆炸,     lib: fireworks }

读者侧控制：右侧悬浮面板 → "页面特效"区，可选 关闭 / 随机 / 具体特效，无需改代码。

注：旧版独立的 sakura/ripples/clicklove 等 enable 配置段已删除，不再参与注入；增删特效改 available 清单即可，面板与运行时自动适配（lib 对应 theme.libs.js.* 路径键）。

效果：樱花飘落、水波荡漾、雪花、彩带等背景动画；点击爱心/星星/烟花等交互反馈。

5. 繁简转换

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

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

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

效果：页脚"繁/简"切换按钮（#translateLink），点击全局转换文字并记忆选择。旧配置 footer.translate.enable 仍保留兼容读取，但修改请用 preference.translate。

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

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

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

fun_features:
  progressbar:
    enable: false       # 加载进度条（默认关闭）
    height_px: 3
    color: "#29d"
    options: { showSpinner: false, trickleSpeed: 100 }   # nprogress 参数

返回顶部：无独立配置键——#backTop 按钮内置于右侧浮动面板（layout/_partial/right-floating.ejs），默认启用。

效果：进度条随页面加载/滚动增长；右下角圆形返回顶部按钮，平滑滚动，移动端尺寸自适应。

7. 打赏弹窗

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

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

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

单篇控制（文章 front-matter）：

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

效果：文章底部显示"赏"按钮；点击弹出二维码 dialog（支付宝/微信 tabs），支持关闭按钮与点击遮罩关闭。

8. 打印样式

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

配置：无需配置——打印样式内置在主题 CSS（source/css/_pages/_base/print.styl + color-schema.styl 的 @media print 规则），始终生效，打印时自动切换为浅色变量。

效果：Ctrl+P 打印时仅保留正文，链接旁显示完整 URL，留白与字号针对打印优化。

9. 音乐播放器 APlayer

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

配置（主题配置 music 块；另有 musics 块用于独立音乐页面）：

music:
  enable: false           # 是否启用（默认关闭）
  server: netease         # 平台：netease | tencent | kugou | xiami | baidu
  type: playlist          # 类型：song | playlist | album | search | artist
  id: 4965675848          # 歌单/歌曲 ID
  fixed: true             # true = 吸底模式（页面底部悬浮）
  autoplay: false
  theme: '#42b983'
  loop: 'all'             # 循环：all | one | none
  order: 'random'         # 顺序：list | random
  preload: 'auto'         # 预加载：none | metadata | auto
  volume: 0.7             # 默认音量（播放器会记忆用户设置）
  listFolded: true        # 列表默认折叠
  hideLrc: true           # 隐藏歌词

效果：音乐卡片（封面 + 播放控制 + 进度条 + 歌单）；fixed: true 时吸底悬浮；暗色模式自动适配。

10. 视频播放器 DPlayer

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

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

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

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

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

带封面、弹幕与 HLS 的完整写法：

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

效果：播放/暂停/进度/音量/倍速控制，支持弹幕（danmaku）与 HLS 直播流。

11. Bilibili 视频卡片

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

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

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

{% bilicard BV1oa4y1L7mw %}

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

12. ECharts 图表

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

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

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

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

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

效果：文章内渲染 ECharts 交互图表（echarts 容器标记），支持悬停数据提示、图例切换等交互。

附：交互视觉功能速查表

功能配置位置参数要点说明
代码块增强主题 codeshrink/break/show_full/copy_btn/language语言标签 + 复制/展开/全屏
图片灯箱主题 post.image_zoomenable/img_url_replace文章图片自动 wrap .img-item
打字机主题 subtitle.typed / fun_features.typing / post.typedloop/showCursor/typeSpeed副标题轮播 + 文章标题
页面特效主题 effectspage/mouse 各 9/4 项，default: off/random/id悬浮面板运行时切换
繁简转换主题 preference.translateenablefooter.translate 兼容读取
进度条主题 fun_features.progressbarheight_px/color默认关闭
返回顶部内置（右浮动面板）无配置键#backTop 默认启用
打赏主题 post.rewardwechat/alipay 二维码图front-matter reward 单篇覆盖
打印样式内置 CSS（print.styl）无配置键@media print 自动生效
音乐 APlayer主题 music / musicsserver/type/id/fixedMetingJS 解析，可吸底
视频 DPlayernpm 插件 hexo-tag-mmediaurl/pic/id/api{% mmedia dplayer %}
Bilibili 卡片npm 插件 hexo-bilibili-card-newBV 号{% bilicard BV... %}
ECharts主题 echarts + npm 插件 hexo-tag-echartsenable/version{% echarts %} JSON 配置
评论
数据加载中 ...