Hero 图片取色

主题可以自动从首页 hero 图片中提取主色调，并动态应用到站点的多个视觉区域。

默认行为（heroImageColor: false）

heroImageColor 默认为 false，此时主题使用预设的紫蓝品牌色：

• Hero 背景光晕 — 使用 VitePress 默认的紫蓝渐变
• Hero 标题渐变 — linear-gradient(120deg, #bd34fe, #41d1ff)
• 代码块光束边框 — CSS 变量 --fx-beam-c1: 189, 52, 254（紫色）、--fx-beam-c2: 65, 209, 255（蓝色）

启用

在 themeConfig 中设置 heroImageColor: true：

// .vitepress/config.mts
import { defineConfig } from "vitepress"
import type { DefaultTheme } from "vitepress"
import fxConfig from "@fuxishi/vitepress-theme/config"
import type { FxThemeCustomConfig } from "@fuxishi/vitepress-theme"

type ThemeConfig = DefaultTheme.Config & FxThemeCustomConfig

export default defineConfig<ThemeConfig>({
  extends: fxConfig,
  themeConfig: {
    heroImageColor: true,
  },
})

无需手动配置图片路径，主题会自动读取首页 frontmatter 中的 hero.image：

---
layout: home
hero:
  image:
    light: /hero-light.png
    dark: /hero-dark.png
---

颜色应用区域

提取的颜色会自动应用到以下区域：

区域	说明
Hero 背景光晕	提取所有色相按顺序排列，构建 conic-gradient 旋转渐变
Hero 标题渐变	选取色相差最大的两个颜色，构建 linear-gradient 文字渐变
代码块光束边框	通过 --fx-beam-c1 / --fx-beam-c2 CSS 变量动态覆盖光束颜色
导航光束边框	同上，hover 时的光束旋转边框也使用相同颜色
音乐球	进度环渐变、旋转光环、播放发光、滑块等颜色同步变化

亮色/暗色模式

主题会分别从亮色和暗色模式对应的图片中提取颜色：

• 亮色模式 → 从 hero.image.light 提取
• 暗色模式 → 从 hero.image.dark 提取

如果只配置了一张图片，则两种模式共用同一组颜色。

缓存机制

提取的颜色会缓存到浏览器 localStorage 中，避免每次访问都重新计算：

• 缓存 key：fx-hero-colors
• 按亮色/暗色模式分别存储
• 自动失效：缓存中记录了图片来源路径，页面加载时自动对比当前图片路径与缓存记录，路径不同时立即清除旧缓存并重新提取颜色
• 模式切换时立即从缓存中恢复，无需等待重新提取

原理

主题使用 node-vibrant 库从图片中提取 6 种主色调（Vibrant、DarkVibrant、LightVibrant、Muted、DarkMuted、LightMuted），然后根据色相信息构建渐变。

颜色提取通过客户端组件 FxHeroImageBg 在浏览器端完成，不依赖 Node.js 文件系统。