安和鱼文档

{
  "name": "theme-example",
  "version": "1.0.0",
  "settings": [
    {
      "group": "style",
      "label": "外观设置",
      "fields": [
        {
          "name": "primaryColor",
          "label": "主题色",
          "type": "color",
          "default": "#3b82f6",
          "description": "网站的主要颜色"
        }
      ]
    }
  ]
}

配置分组（Group）

字段	类型	必需	说明
`group`	string	✅	分组标识，用于内部识别
`label`	string	✅	分组显示名称，展示在标签页
`fields`	array	✅	该分组下的配置字段列表

配置字段（Field）

字段	类型	必需	说明
`name`	string	✅	字段唯一标识，用于存储和读取
`label`	string	✅	字段显示名称
`type`	string	✅	字段类型，见下方支持的类型
`default`	any	❌	默认值
`description`	string	❌	字段描述，显示在输入框下方
`placeholder`	string	❌	输入框占位文字
`validation`	object	❌	验证规则
`options`	array	❌	选项列表（select 类型必需）
`condition`	object	❌	显示条件，用于字段联动

支持的字段类型

类型	说明	示例值
`text`	单行文本输入	`"Hello World"`
`textarea`	多行文本输入	`"多行\n文本"`
`number`	数字输入	`10`
`select`	下拉选择	`"option1"`
`color`	颜色选择器	`"#3b82f6"`
`switch`	开关	`true` / `false`
`image`	图片上传/URL	`"https://..."`
`code`	代码编辑器	`"<div>HTML</div>"`

字段类型详细示例

text - 单行文本

{
  "name": "siteName",
  "label": "网站名称",
  "type": "text",
  "default": "我的博客",
  "placeholder": "请输入网站名称",
  "validation": {
    "maxLength": 50,
    "message": "名称不能超过50个字符"
  }
}

select - 下拉选择

{
  "name": "defaultTheme",
  "label": "默认主题",
  "type": "select",
  "default": "system",
  "options": [
    { "label": "跟随系统", "value": "system" },
    { "label": "浅色模式", "value": "light" },
    { "label": "深色模式", "value": "dark" }
  ]
}

number - 数字输入

{
  "name": "articlesPerPage",
  "label": "每页文章数",
  "type": "number",
  "default": 10,
  "validation": {
    "min": 5,
    "max": 50,
    "message": "每页文章数应在 5-50 之间"
  }
}

color - 颜色选择

{
  "name": "primaryColor",
  "label": "主题色",
  "type": "color",
  "default": "#3b82f6",
  "description": "网站的主要颜色"
}

switch - 开关

{
  "name": "enableAnimation",
  "label": "启用动画",
  "type": "switch",
  "default": true,
  "description": "是否启用页面过渡动画效果"
}

textarea - 多行文本

{
  "name": "customFooterHtml",
  "label": "自定义页脚内容",
  "type": "textarea",
  "default": "",
  "placeholder": "支持 HTML 代码",
  "description": "在页脚添加自定义内容，如备案号、版权声明等"
}

验证规则

{
  "validation": {
    "required": true,
    "min": 1,
    "max": 100,
    "minLength": 1,
    "maxLength": 200,
    "pattern": "^[a-zA-Z0-9]+$",
    "message": "验证失败时显示的错误信息"
  }
}

条件显示

使用 condition 实现字段联动，当条件满足时才显示该字段：

{
  "name": "animationSpeed",
  "label": "动画速度",
  "type": "select",
  "default": "normal",
  "options": [
    { "label": "慢速", "value": "slow" },
    { "label": "正常", "value": "normal" },
    { "label": "快速", "value": "fast" }
  ],
  "condition": {
    "field": "enableAnimation",
    "operator": "eq",
    "value": true
  }
}

支持的操作符：

操作符	说明
`eq`	等于
`neq`	不等于
`gt`	大于
`lt`	小于
`contains`	包含

在主题中读取配置

前端获取配置（公开接口）

主题前端可以通过以下 API 获取当前主题的配置值：

GET /api/public/theme/config

返回示例：

{
  "code": 200,
  "data": {
    "primaryColor": "#3b82f6",
    "defaultTheme": "system",
    "enableAnimation": true,
    "sidebarPosition": "right",
    "articlesPerPage": 10
  }
}

在主题代码中使用

以 Next.js 主题为例：

// lib/api/services.ts
export async function getThemeConfig() {
  const response = await fetch(`${API_BASE_URL}/api/public/theme/config`);
  const data = await response.json();
  return data.data;
}

// app/layout.tsx
export default async function RootLayout({ children }) {
  const themeConfig = await getThemeConfig();
  
  return (
    <html style={{ '--primary-color': themeConfig.primaryColor }}>
      <body>{children}</body>
    </html>
  );
}

完整配置示例

以下是 Nova 主题的完整配置示例：

{
  "name": "theme-anheyu-nova",
  "displayName": "Nova",
  "version": "2.0.0",
  "settings": [
    {
      "group": "style",
      "label": "外观设置",
      "fields": [
        {
          "name": "primaryColor",
          "label": "主题色",
          "type": "color",
          "default": "#3b82f6",
          "description": "网站的主要颜色"
        },
        {
          "name": "defaultTheme",
          "label": "默认主题",
          "type": "select",
          "default": "system",
          "options": [
            { "label": "跟随系统", "value": "system" },
            { "label": "浅色模式", "value": "light" },
            { "label": "深色模式", "value": "dark" }
          ],
          "description": "访客首次访问时使用的主题模式"
        },
        {
          "name": "enableAnimation",
          "label": "启用动画",
          "type": "switch",
          "default": true,
          "description": "是否启用页面过渡动画效果"
        }
      ]
    },
    {
      "group": "layout",
      "label": "布局设置",
      "fields": [
        {
          "name": "sidebarPosition",
          "label": "侧边栏位置",
          "type": "select",
          "default": "right",
          "options": [
            { "label": "左侧", "value": "left" },
            { "label": "右侧", "value": "right" },
            { "label": "隐藏", "value": "none" }
          ],
          "description": "文章页面侧边栏的显示位置"
        },
        {
          "name": "articlesPerPage",
          "label": "每页文章数",
          "type": "number",
          "default": 10,
          "validation": {
            "min": 5,
            "max": 50,
            "message": "每页文章数应在 5-50 之间"
          },
          "description": "文章列表每页显示的文章数量"
        }
      ]
    },
    {
      "group": "footer",
      "label": "页脚设置",
      "fields": [
        {
          "name": "showRuntime",
          "label": "显示运行时间",
          "type": "switch",
          "default": true,
          "description": "是否在页脚显示网站运行时间"
        },
        {
          "name": "customFooterHtml",
          "label": "自定义页脚内容",
          "type": "textarea",
          "default": "",
          "placeholder": "支持 HTML 代码",
          "description": "在页脚添加自定义内容，如备案号、版权声明等"
        }
      ]
    }
  ]
}

常见问题

Q: 配置修改后前端没有生效？

可能的原因：

前端页面有缓存，尝试强制刷新（Ctrl+F5）
如果是 SSR 主题，可能需要等待缓存过期或手动清理缓存

Q: 如何重置配置到默认值？

目前可以手动将每个配置项改回默认值，或在主题管理中卸载后重新安装主题。

Q: 主题配置是否会在主题更新后保留？

是的，用户的主题配置存储在数据库中，与主题文件分离。更新主题时配置会保留。

Q: 不同用户的主题配置是否独立？

主题配置绑定到安装记录，通常情况下整个站点共享同一份主题配置。

Q: 官方主题是否支持自定义配置？

官方内置主题不支持自定义配置（settings 为空）。用户安装的第三方主题可以定义自己的配置项。

技术支持

如果您在主题配置过程中遇到问题，可以通过以下方式获取帮助：

GitHub Issues：anheyu-pro
官方文档：docs.anheyu.com

主题配置

On this page