ai-kefu-jc/docs/2026-08-31-dynamic-theme-changelog.md

2026-08-31 动态主题色 + 头像图片化

嵌入方用法

• 品牌色:<script src=".../static/widget.js" data-color="#1a73e8">(3/6 位 hex,# 可选;缺省=默认橙 #f08a31)
• 注意:独立聊天页用 URL 参数时 # 必须编码为 %23,如 /?color=%231a73e8——?color=#1a73e8 会在 # 处截断而静默回退默认橙
• 自定义头像:data-avatar="https://.../logo.png"(完整 URL)或 data-avatar="/static/xxx.png"(本服务路径,自动拼挂件源);缺省=内置客服头像 kefu-small.png
• 非法/畸形色值:console.warn + 回退默认橙,页面功能不受影响
• 已知限制:极浅品牌色(亮度>65)配白字对比度低

实现要点

• 单品牌色 HSL 派生 7 语义槽位(primary/primary-rgb/gradient-end/deep-text/caption-text/soft-bg/border-soft),CSS 变量注入(widget Shadow DOM :host / 独立页 :root)
• 派生函数两份(theme.js + widget.js 内联,pytest 源码级同步强制);亮度钳制保证任意色相可读
• 4 层兜底:属性缺失→默认 / 非法→warn+默认 / 派生异常→静态色板 / 结构性(:root 字面量+同字符串注入)
• 头像:图片绝对定位覆盖 + emoji 底层兜底(load 隐藏 emoji/error 移除);断线重连加 host.isConnected 守卫
• 默认视觉:与改造前一致(肉眼不可辨级),唯一可见变化=Send/Start 按钮渐变统一为近纯色(spec §9.1 已批准)
• 回归网:tests/test_theme_static.py 12 项(槽位完整/橙残留/双份同步/跨域头像/:root↔DEFAULT_PALETTE 一致/横幅/独立页槽位)
• 测试页:/static/widget-test.html(换色预览+断言面板)