换肤 + 节假日配置

节日期间可以让系统自动换一套「节日装」：首页欢迎卡换成节日文案和装饰图，菜单高亮、按钮、链接等全站配色一起换成配套的节日色，节日过了自动恢复原样。

整套效果由一条后台参数控制，换节日只需要改这一行参数，不用改代码、不用发版、不用建表。

元旦、春节、清明、劳动节、端午、中秋、国庆七个法定节日的素材和配色都已随版本内置，直接复制预设库里的一段 JSON 即可，不用自己准备图片。

本页讲的是节日期间的临时换肤（自动生效、自动恢复）。如果你要的是给客户固化一套长期主题和菜单布局，见 个性化主题菜单布局。

1. 效果预览

中秋

国庆（同一套代码，只改了一条参数）

未配置 / 关闭后

装饰图不是盖在卡片上的一张图，而是融进卡片底色、从右往左渐隐的背景层，所以没有生硬的边界：

鼠标移到卡片上，右上角会出现关闭按钮。点掉之后装饰收成一个节日小图标（中秋是月饼，国庆是国旗），点图标可以再展开。这个选择记在浏览器本地，只影响当前用户、当前浏览器。

2. 配置入口

所有配置都在一条参数里：system.festival.welcome。

方式一：在页面里改（推荐）

1. 进入 基础设施 → 配置管理（路由 /infra/config）
2. 搜索参数键名 system.festival.welcome
3. 点「修改」，把「参数键值」换成目标节日的 JSON（写法见下一节）
4. 保存后刷新浏览器页面即可看到效果

页面保存会自动清掉后端缓存，不需要重启服务。

老用户什么时候能看到新主题

主题只在页面加载时套用一次，不做轮询，避免给系统增加负担。所以：

• 已登录、停在页面不动：不会变
• 按 F5 刷新：生效
• 退出登录再登录：生效

不需要让用户清浏览器缓存。 参数在前端只有 60 秒的内存缓存，刷新即失效；浏览器本地只存了主题色备份和「装饰收起」状态，不影响读取新参数。

实际推广时不用通知用户做任何操作：第二天重新登录的人自然就看到了，挂着页面不关的人下次刷新会看到。

方式二：执行 SQL（适合升级包、批量环境）

直接改数据库的话，必须额外清一次后端缓存，否则读到的还是旧值：

# 参数走 Redis 缓存，key 格式：infra_config:{租户ID}:{参数键名}
redis-cli del "infra_config:1:system.festival.welcome"

# 不确定有哪些租户时，先列出来再逐个删
redis-cli keys "infra_config*festival*"

也可以改完库之后到配置管理页面对这条参数做一次「修改并保存」（内容不变也行），同样会触发缓存失效，这样就不用碰 Redis。

Windows PowerShell 下的注意点

redis-cli --scan 在 PowerShell 里管道输出可能为空，用 redis-cli keys "模式" 更稳。

3. 参数怎么写

参数值是一段 JSON：

{
  "code": "mid_autumn",
  "name": "中秋",
  "start": "2026-09-20",
  "end": "2026-09-27",
  "primary": "hsl(28 72% 48%)",
  "title": "中秋团圆，阖家安康",
  "subtitle": "月满中秋",
  "banner": "/static/festival/mid-autumn-banner.webp",
  "icon": "/static/festival/mid-autumn-icon.webp"
}

字段	必填	说明
code	是	节日标识，英文下划线。换节日时必须换掉，前端靠它识别「换了一个节日」并重置用户的收起状态
name	否	中文名，仅作备注，不显示在界面上
start	否	生效开始日，yyyy-MM-dd，含当天。留空表示不限开始
end	否	生效结束日，yyyy-MM-dd，含当天。留空表示不限结束
primary	否	节日主题色，必须是 hsl(色相 饱和度% 亮度%) 写法。留空则全站配色保持用户自己的偏好、欢迎卡维持默认蓝底 —— 但装饰素材是按浅色卡片设计的，这时几乎看不出来，所以填了 banner 就建议一并填 primary
title	否	欢迎卡主标题。留空则显示默认的「时段问候，用户名」
subtitle	否	欢迎卡副标题
banner	否	卡片右侧装饰图。留空则不显示装饰
icon	否	装饰收起后显示的小图标

参数值长度上限 500 字符

infra_config.value 字段是 varchar(500)。上面这段 JSON 约 250 字符，留有余量，但文案不要写得太长。

主题色 primary 怎么填

只需要给一个主色，其余颜色都是自动推导的：

• 全站：菜单高亮、按钮、链接、页签、日期选择器等，由主题体系按这个主色自动派生，走的就是「偏好设置」那一套逻辑，不是硬写样式
• 侧边栏 / 顶栏 / 内容底色：自动取同色系的极淡色调（只在浅色模式生效）
• 欢迎卡：浅色模式取主色的浅调配深色文字，暗色模式取深调配白色文字

七个法定节日的配色已经调好，直接抄下一节的预设即可。自己配色时注意两点：亮度（第三个值）建议留在 40%~52%，太深会让浅底卡片上的文字发闷；饱和度别拉满，超过 80% 在大面积淡色层上容易显脏。

4. 节日预设库

元旦、春节、清明、劳动节、端午、中秋、国庆七个法定节日的素材、配色、文案都已经做好并随版本发布，换节日只要复制对应的一段 JSON 粘到参数里，不用再准备图片。

4.1 一览表

节日	code	主色	标题 / 副标题
元旦	new_year	hsl(215 68% 50%) 靛蓝	元旦启新，万象更新 / 新年第一天
春节	spring_festival	hsl(0 72% 50%) 中国红	新春大吉，万事顺遂 / 恭贺新春
清明	qingming	hsl(160 30% 42%) 青绿	清明时节，慎终追远 / 春和景明
劳动节	labor_day	hsl(24 76% 50%) 暖橙	致敬劳动，向阳而行 / 五一假期愉快
端午	dragon_boat	hsl(155 42% 40%) 竹青	端午安康，粽叶飘香 / 五月初五
中秋	mid_autumn	hsl(28 72% 48%) 桂黄	中秋团圆，阖家安康 / 月满中秋
国庆	national_day	hsl(4 72% 50%) 国旗红	普天同庆，盛世华诞 / 祝您假期愉快

清明和端午的文案不要随手改

清明是祭扫节气，装饰做成了柳枝细雨的素雅风格，没有灯笼、烟花之类的庆祝元素，文案也避开了一切祝福用语。

端午只说「安康」，不要改成「快乐」。

这两处是客户投诉的高发点，改文案前先想清楚。

4.2 完整 JSON

复制即用。生效期按 2027 年写，要提前在测试环境看效果，把 start 改成今天即可。

点开查看七段 JSON

元旦

{"code":"new_year","name":"元旦","start":"2026-12-31","end":"2027-01-03","primary":"hsl(215 68% 50%)","title":"元旦启新，万象更新","subtitle":"新年第一天","banner":"/static/festival/new-year-banner.webp","icon":"/static/festival/new-year-icon.webp"}

春节

{"code":"spring_festival","name":"春节","start":"2027-02-04","end":"2027-02-12","primary":"hsl(0 72% 50%)","title":"新春大吉，万事顺遂","subtitle":"恭贺新春","banner":"/static/festival/spring-festival-banner.webp","icon":"/static/festival/spring-festival-icon.webp"}

清明

{"code":"qingming","name":"清明","start":"2027-04-04","end":"2027-04-07","primary":"hsl(160 30% 42%)","title":"清明时节，慎终追远","subtitle":"春和景明","banner":"/static/festival/qingming-banner.webp","icon":"/static/festival/qingming-icon.webp"}

劳动节

{"code":"labor_day","name":"劳动节","start":"2027-04-30","end":"2027-05-05","primary":"hsl(24 76% 50%)","title":"致敬劳动，向阳而行","subtitle":"五一假期愉快","banner":"/static/festival/labor-day-banner.webp","icon":"/static/festival/labor-day-icon.webp"}

端午

{"code":"dragon_boat","name":"端午","start":"2027-06-08","end":"2027-06-11","primary":"hsl(155 42% 40%)","title":"端午安康，粽叶飘香","subtitle":"五月初五","banner":"/static/festival/dragon-boat-banner.webp","icon":"/static/festival/dragon-boat-icon.webp"}

中秋

{"code":"mid_autumn","name":"中秋","start":"2027-09-14","end":"2027-09-17","primary":"hsl(28 72% 48%)","title":"中秋团圆，阖家安康","subtitle":"月满中秋","banner":"/static/festival/mid-autumn-banner.webp","icon":"/static/festival/mid-autumn-icon.webp"}

国庆

{"code":"national_day","name":"国庆","start":"2027-10-01","end":"2027-10-08","primary":"hsl(4 72% 50%)","title":"普天同庆，盛世华诞","subtitle":"祝您假期愉快","banner":"/static/festival/national-day-banner.webp","icon":"/static/festival/national-day-icon.webp"}

同样的七段也整理成了 SQL，在数据库仓库的 update/202609/20260917_update/04_note_说明勿执行/213000_festival_presets_全节日预设.sql，按需复制其中一段，不要整个文件跑一遍（后面的会覆盖前面的）。

4.3 农历节日日期表

元旦、劳动节、国庆是固定日期（1-1、5-1、10-1）。春节、清明、端午、中秋每年公历日期都不同，换年份时改 start 和 end 两个值：

节日	2026	2027	2028	2029	2030	2031
春节	02-17	02-06	01-26	02-13	02-03	01-23
清明	04-05	04-05	04-04	04-04	04-05	04-05
端午	06-19	06-09	05-28	06-16	06-05	06-24
中秋	09-25	09-15	10-03	09-22	09-12	10-01

预设库里的 JSON 生效期写的是 2027 年。现在就要看效果，把 start 改成今天——装饰只在 start 和 end 之间出现，日期不覆盖今天就什么都不会变。

预设里的生效期取「节前一两天到假期结束」，让装饰在放假前就出现。结束日是按常规假期长度推算的，等国务院放假通知发布后，按通知改一下 end 更准。

5. 自己做一套新素材

预设库里没有的节日（比如公司周年庆、行业节日），按下面的规格自己做。

5.1 准备两张素材

素材	要求
横幅（banner）	纯白底、不要透明通道；宽高比 3.4:1；主体高度占整幅约 58%；主体右缘落在整幅约 64% 的位置；整幅 70% 往右必须是纯白（含淡影、飘带、丝带都要淡掉）
小图标（icon）	正方形，白底，就是节日主体的特写

两张都用 WebP。横幅宽 1600 左右即可（上屏实际只显示 500 多像素宽），单张控制在 30KB 以内；图标 120×120，几 KB。

上面几个数字不是随便定的，是装饰层的 CSS 反推出来的，照着做能一次成型：

• 比例 3.4 —— 装饰层按 background-size: auto 132% 按高缩放，只有这个比例缩放后刚好铺满装饰层宽度。更方的图会缩成右侧一小块，显得局促。
• 主体占高 58% —— 乘上 132% 的放大，上屏后主体约占卡片高四分之三。再大会顶到卡片上下边缘，像被切掉；再小则因为主体位置落在装饰层的渐隐区，看着发虚。
• 主体右缘 64% —— 素材按高缩放后铺在卡片的 9.8%~76% 区间，64% 换算到卡片约 52%，刚好停在天气卡左缘（约 57%）之前。
• 70% 往右必须纯白 —— 这是最容易漏的一条。70% 换算到卡片约 56%，只要还有一丝内容越过它，就会被天气卡的底色截断成一条竖直亮线。

三个最容易踩的坑

必须白底，不能是透明图。 前端用 mix-blend-mode: multiply 把素材融进卡片底色，白色部分乘出来正好等于底色、自动「消失」，这才是没有硬边界的原因。给透明图反而会露出灰底。

光看主体位置不够，要看「最后一丝墨」的位置。 主体本身收在 64% 了，但 AI 出图常在主体右侧留一片淡影或飘带（国庆的天安门剪影、中秋的祥云），它们很淡、肉眼在原图上几乎注意不到，上屏后却正好压在天气卡边缘，形成一条竖线。判断标准是整幅 70% 往右逐列检查，只要还有偏离纯白的像素就要处理。

渐隐要从主体一出头就开始。 只把「画面内容末端」淡一成是不够的——内容往往一直铺到画布边缘，那一成落在 90% 开外，越界的部分完全没被处理。正确做法是从主体右缘（64%）稍往右起渐隐，到 70% 彻底变白，70% 之后整列涂白。

5.2 放素材

做法 A：放进前端包（随版本发布，适合固定节日）

ruoyi-office-vben/apps/web-antd/public/static/festival/
├── new-year-banner.webp          # 元旦
├── new-year-icon.webp
├── spring-festival-banner.webp   # 春节
├── spring-festival-icon.webp
├── qingming-banner.webp          # 清明
├── qingming-icon.webp
├── labor-day-banner.webp         # 劳动节
├── labor-day-icon.webp
├── dragon-boat-banner.webp       # 端午
├── dragon-boat-icon.webp
├── mid-autumn-banner.webp        # 中秋
├── mid-autumn-icon.webp
├── national-day-banner.webp      # 国庆
└── national-day-icon.webp

参数里写相对路径 /static/festival/xxx.webp（不要写成 /web/static/...）。前端会按部署子路径自动拼接 BASE_URL（本地 /，演示/生产 /web/，客户路径部署如 /oa/）。这种方式需要把素材打进前端包并部署。

做法 B：传到文件服务 / 对象存储（不用发版，适合临时活动）

banner 和 icon 支持填完整 URL：

{ "banner": "https://你的域名/files/festival/spring-banner.webp" }

这样换素材只改参数，前端不用重新打包。

5.3 改参数

把 JSON 里的 code、生效期、primary、文案、两张图地址替换掉，保存，刷新页面。现成的写法见第 7 节。

6. 关闭、还原与保护规则

怎么关掉

把参数值改成 {} 即可，也可以直接把这条参数删掉，两种做法效果一样。用户刷新页面后：欢迎卡回到默认蓝色渐变、装饰消失、全站主题色还原成该用户原本的配色。

「原本的配色」取的是最近一次套用节日色之前该用户的颜色。举例：用户平时用绿色主题，节日期间变成节日橙，节日结束后回到绿色，而不是回到系统默认蓝。

三条自动保护

1. 节日过期自动还原：过了 end 的第二天，主题色自动回到套用节日前的样子，不需要人工干预，也不需要再执行任何脚本。
2. 不抢用户的选择：如果用户在节日期间自己去「偏好设置」换了主题色，之后刷新不会被节日色抢回去。
3. 暗色模式自适应：暗色模式下欢迎卡转成深色调、文字保持白色，侧边栏和顶栏不做染色，装饰图呈现为低调的暗纹。

作用范围

• 这条参数全平台统一，所有租户看到同一个节日主题
• 节日文案和装饰只出现在登录后的首页；登录页没有节日元素，但因为主题色存在用户本地偏好里，登录页的按钮等也会显示节日配色
• 生效期按用户浏览器的本地日期判断
• 当前版本只作用于 Web 管理端，移动端不受影响

7. 常用 SQL

7.1 初始化（新环境执行一次）

节日参数本体，幂等，可重复执行：

INSERT INTO `infra_config` (
  `category`, `type`, `name`, `config_key`, `value`, `visible`, `remark`,
  `creator`, `create_time`, `updater`, `update_time`, `deleted`
)
SELECT
  'ui', 2, '首页节日主题', 'system.festival.welcome',
  '{"code":"mid_autumn","name":"中秋","start":"2027-09-14","end":"2027-09-17","primary":"hsl(28 72% 48%)","title":"中秋团圆，阖家安康","subtitle":"月满中秋","banner":"/static/festival/mid-autumn-banner.webp","icon":"/static/festival/mid-autumn-icon.webp"}',
  b'1', '首页欢迎卡节日主题；value 置 {} 即恢复默认，不影响任何功能',
  '1', NOW(), '1', NOW(), b'0'
FROM DUAL
WHERE NOT EXISTS (
  SELECT 1 FROM (
    SELECT `config_key`, `deleted` FROM `infra_config`
  ) AS `existed`
  WHERE `existed`.`config_key` = 'system.festival.welcome'
    AND `existed`.`deleted` = b'0'
);

visible 必须是 1

前端通过 /infra/config/get-value-by-key 读这条参数，只有 visible = 1 的参数才会返回。如果在页面里手工新建这条参数，记得把「是否可见」勾上。

7.2 切换到其他节日

把 value 换成预设库里对应的那一段，语句本身不变。以国庆为例：

UPDATE `infra_config`
SET `value` = '{"code":"national_day","name":"国庆","start":"2027-10-01","end":"2027-10-08","primary":"hsl(4 72% 50%)","title":"普天同庆，盛世华诞","subtitle":"祝您假期愉快","banner":"/static/festival/national-day-banner.webp","icon":"/static/festival/national-day-icon.webp"}',
    `update_time` = NOW()
WHERE `config_key` = 'system.festival.welcome'
  AND `deleted` = b'0';

七个节日的完整语句已经整理成一个文件，见数据库仓库 update/202609/20260917_update/04_note_说明勿执行/213000_festival_presets_全节日预设.sql。

7.3 新增一个自定义节日

法定节日之外的场合（公司周年庆、行业展会等），素材按第 5 节的规格自备，语句照抄：

UPDATE `infra_config`
SET `value` = '{"code":"anniversary","name":"周年庆","start":"2027-03-18","end":"2027-03-22","primary":"hsl(265 60% 52%)","title":"十周年，感谢同行","subtitle":"一起走过十年","banner":"/static/festival/anniversary-banner.webp","icon":"/static/festival/anniversary-icon.webp"}',
    `update_time` = NOW()
WHERE `config_key` = 'system.festival.welcome'
  AND `deleted` = b'0';

7.4 只换文案、不改全站配色

去掉 primary 字段，菜单和按钮就保持用户自己的配色：

UPDATE `infra_config`
SET `value` = '{"code":"mid_autumn","name":"中秋","start":"2027-09-14","end":"2027-09-17","title":"中秋团圆，阖家安康","subtitle":"月满中秋","banner":"/static/festival/mid-autumn-banner.webp","icon":"/static/festival/mid-autumn-icon.webp"}',
    `update_time` = NOW()
WHERE `config_key` = 'system.festival.welcome'
  AND `deleted` = b'0';

7.5 关闭 / 重置为默认

UPDATE `infra_config`
SET `value` = '{}',
    `update_time` = NOW()
WHERE `config_key` = 'system.festival.welcome'
  AND `deleted` = b'0';

7.6 测试环境提前预览

想在节日之前先看效果，把开始日往前挪。正式环境不要执行，会导致节日装饰提前出现：

-- 以春节预设为例，把开始日挪到 2026-01-01
UPDATE `infra_config`
SET `value` = REPLACE(`value`, '"start":"2027-02-04"', '"start":"2026-01-01"'),
    `update_time` = NOW()
WHERE `config_key` = 'system.festival.welcome'
  AND `deleted` = b'0';

在页面里改更省事：把 JSON 里的 start 直接写成今天，看完再改回去。

7.7 欢迎组件配置项扩展（可选）

与节日无关的一条增强：给首页设计器里的欢迎组件补上主标题、背景图、背景渐变、文字色四个可配项，这样非节日期间也能单独定制欢迎卡外观。节日参数的优先级高于这里的配置。

展开完整 SQL

UPDATE `system_home_component`
SET `config_schema` = '{
  "properties": [
    {
      "key": "greetingTitle",
      "type": "string",
      "label": "主标题",
      "default": "",
      "placeholder": "留空则显示「时段问候，用户名」",
      "required": false
    },
    {
      "key": "greeting",
      "type": "string",
      "label": "提示语",
      "default": "欢迎回来，开始您的工作吧！",
      "required": false
    },
    {
      "key": "backgroundImage",
      "type": "string",
      "label": "背景图地址",
      "default": "",
      "placeholder": "留空则使用背景渐变，建议 WebP 且不超过 200KB",
      "required": false
    },
    {
      "key": "backgroundGradient",
      "type": "string",
      "label": "背景渐变",
      "default": "",
      "placeholder": "如 linear-gradient(135deg, #3b82f6 0%, #1d4ed8 100%)",
      "required": false
    },
    {
      "key": "textColor",
      "type": "color",
      "label": "文字颜色",
      "default": "",
      "required": false
    },
    {
      "key": "showWeather",
      "type": "boolean",
      "label": "显示天气",
      "default": true,
      "required": false
    },
    {
      "key": "paddingTop",
      "type": "number",
      "label": "内边距-上(px)",
      "default": 0,
      "min": 0,
      "max": 100,
      "required": false
    },
    {
      "key": "paddingRight",
      "type": "number",
      "label": "内边距-右(px)",
      "default": 0,
      "min": 0,
      "max": 100,
      "required": false
    },
    {
      "key": "paddingBottom",
      "type": "number",
      "label": "内边距-下(px)",
      "default": 0,
      "min": 0,
      "max": 100,
      "required": false
    },
    {
      "key": "paddingLeft",
      "type": "number",
      "label": "内边距-左(px)",
      "default": 0,
      "min": 0,
      "max": 100,
      "required": false
    },
    {
      "key": "marginTop",
      "type": "number",
      "label": "外边距-上(px)",
      "default": 0,
      "min": 0,
      "max": 100,
      "required": false
    },
    {
      "key": "marginRight",
      "type": "number",
      "label": "外边距-右(px)",
      "default": 0,
      "min": 0,
      "max": 100,
      "required": false
    },
    {
      "key": "marginBottom",
      "type": "number",
      "label": "外边距-下(px)",
      "default": 0,
      "min": 0,
      "max": 100,
      "required": false
    },
    {
      "key": "marginLeft",
      "type": "number",
      "label": "外边距-左(px)",
      "default": 0,
      "min": 0,
      "max": 100,
      "required": false
    }
  ]
}',
    `update_time` = NOW()
WHERE `code` = 'workbench_welcome'
  AND `deleted` = b'0';

8. 常见问题

改了参数但页面没变化

按顺序排查：① 是否刷新了浏览器页面；② 参数的「是否可见」是否为是；③ 是不是直接改库没清 Redis 缓存；④ 当前日期是否在 start ~ end 区间内；⑤ JSON 是否写错（写错时前端按「没配置」处理，不会报错也不会白屏）。

装饰图不显示

检查 banner 地址能不能直接在浏览器打开。如果填的是 /static/festival/xxx.webp 相对路径，素材必须已经打进前端包并部署；前端会自动拼上部署子路径，浏览器实际请求的是 /web/static/festival/xxx.webp（或客户路径下的等价地址）。若请求落在站点根路径 /static/festival/... 却返回文档站 HTML，说明 nginx 还没把这条转到管理端静态目录，或前端包还是旧的。临时活动建议改用文件服务的完整 URL。

装饰图看得见，但主体被右边的天气卡挡住

素材主体太靠右了。在图片右侧补白扩宽，让主体右缘落到整幅约 64% 的位置，重新导出即可，不用改代码。

装饰图和天气卡之间有一条竖直亮线

素材在整幅 70% 往右还有内容没淡干净，被天气卡的底色截断了。常见来源是主体右侧那些很淡的陪衬（淡影、飘带、祥云），在原图上不显眼但会一路铺到画布边缘。把 70% 往右整列涂白、并从主体右缘起做一段渐隐即可，见 5.1。

节日过了（或参数已删除），颜色还是节日色

正常情况刷新一次就会自动还原。还原依赖浏览器里存的一份备份，记着「套节日色之前该用户是什么颜色」；如果用户清空过浏览器数据、或换了浏览器，这份备份会丢，系统就不知道该还回什么颜色，于是保守地不动——表现就是欢迎卡回到默认样式，但菜单、按钮还是节日色。

这种情况让用户点右上角齿轮打开「偏好设置」，抽屉右上角有个重置按钮，点一下即回到默认主题；也可以在「外观 → 内置主题」里直接选回想要的颜色。

想让某个用户不看节日装饰

点欢迎卡右上角的关闭按钮，该选择记在这个用户的浏览器里。主题配色属于全站设置，单个用户如果不喜欢，可以在「偏好设置」里自己改主题色，系统不会再覆盖。

9. 相关源码位置

有源码的客户如果要做更深的定制，可以从这几个文件入手：

用途	路径
节日主题逻辑（读参数、套主色、备份还原）	ruoyi-office-vben/apps/web-antd/src/store/festival.ts
欢迎组件（文案、装饰层、收起交互）	ruoyi-office-vben/apps/web-antd/src/views/dashboard/home/components/welcome/workbench-welcome.vue
初始化时机	ruoyi-office-vben/apps/web-antd/src/layouts/basic.vue
节日素材	ruoyi-office-vben/apps/web-antd/public/static/festival/