ZF sun
a9f3c7acc2
绝对路径与本机目录绑定，换机器即失效，改为相对表述。 - docs/theme-multi-platform.md：删掉 cd 到绝对路径的命令行， 改为注释说明「在项目根目录（含 package.json）下执行」 - docs/i18n-audit-report.md：审计范围改为「项目根目录」 - docs/ai-agent-integration.md：适用前端改为「本仓库」； WB Cloud SDK 协议约束矩阵原指向外部 refs 仓的绝对路径， 改为相对文件名并标注「WB Cloud SDK 参考仓内」
232 lines
9.3 KiB
Markdown
232 lines
9.3 KiB
Markdown
# 主题样式 token 化 — 三平台兼容性测试报告
|
||
|
||
> 覆盖: H5 / 微信小程序 / 鸿蒙元服务
|
||
> 范围: P0 优先级文件,共 17 个 .vue / .scss
|
||
> 完成时间: 2026-06-11
|
||
|
||
---
|
||
|
||
## 一、改动清单
|
||
|
||
| # | 文件 | 改动 | 引用 token |
|
||
|---|---|---|---|
|
||
| 1 | `components-diy/diy-member-info.vue` | 3 处渐变 (865/946/996) | `--super-member-start/end-bg`、 `--super-member-start/end-text-color` |
|
||
| 2 | `components/loading-cover/loading-cover.vue` | 2 处边框主色 (92/95) | `--base-color` |
|
||
| 3 | `pages_tool/pay/result.vue` | 1 处失败提示色 (275) | `--base-color` |
|
||
| 4 | `pages_tool/member/index.vue` | 1 处主色 (166) | `--main-color` |
|
||
| 5 | `pages_tool/member/public/css/balance.scss` | 3 处 (169/203/207) | `--balance-page-bg-start/end`、 `--base-color` |
|
||
| 6 | `pages_tool/member/public/css/point.scss` | 1 处 (204) | `--point-page-bg-start/end` |
|
||
| 7 | `pages_tool/member/public/css/card.scss` | 3 处 (315/548/600/620) | `--member-card-gold-start/end` |
|
||
| 8 | `pages_tool/member/public/css/invite_friends.scss` | 1 处 (146) | `--invite-grad-start/end` |
|
||
| 9 | `common/css/order_parment.scss` | 2 处 (465/1289) | `--goods-cart-num-corner`、 `--member-icon-grad-start/end` |
|
||
| 10 | `components-diy/diy-pintuan.vue` | 4 处 (454/485/498/802) | `--pintuan-label-color`、 `--pintuan-label-grad-start/end`、 `--pintuan-success-start/end` |
|
||
| 11 | `components-diy/diy-bargain.vue` | 4 处 (464/579/587/598/621) | `--pintuan-label-grad-start/end`、 `--bargain-promo-shallow`、 `--bargain-promo-color` |
|
||
| 12 | `components-diy/diy-seckill.vue` | 4 处 (799/804/857/1181) | `--seckill-price-shallow`、 `--seckill-price-start`、 `--seckill-discount-start/end` |
|
||
| 13 | `components-diy/diy-category-item.vue` | 1 处 (1410) | `--goods-cart-num-corner` |
|
||
| 14 | `pages_promotion/point/public/css/list.scss` | 3 处 (22/78/927) | `--point-promo-start/end`、 `--point-item-grad-start/end` |
|
||
| 15 | `pages_promotion/fenxiao/withdraw_apply.vue` | 1 处 (354) | `--fenxiao-withdraw-start` |
|
||
| 16 | `pages_promotion/fenxiao/public/css/level.scss` | 10 处 (127-155) | `--level-N-grad-start/end` (N=1..10) |
|
||
| 17 | `pages_promotion/fenxiao/promote.vue` | 1 处 (386) | `--promote-grad-start/end` |
|
||
|
||
总计: **47 处品牌色硬编码 → var() 化**
|
||
|
||
---
|
||
|
||
## 二、写法规范(保证三平台一致)
|
||
|
||
### 2.1 通用模板
|
||
|
||
```scss
|
||
/* 单值属性 */
|
||
color: var(--main-color, #F4391c);
|
||
background: var(--base-color, #FF4646);
|
||
border: 4rpx solid var(--base-color, #FF4646);
|
||
|
||
/* 渐变 */
|
||
background: #原始色; /* 兜底(老 runtime 无 var() 兜底) */
|
||
background: linear-gradient(<角度>, var(--token-start, #原始色) 0%, var(--token-end, #原始色) 100%);
|
||
```
|
||
|
||
### 2.2 关键决策
|
||
|
||
1. **双写法 + 兜底值**:
|
||
- 先写一行纯色兜底(`background: #xxx;`)
|
||
- 再写 `var()` 写法,带 fallback
|
||
- 老 runtime / 鸿蒙元服务早期版本无 `var()` 时,自动回退到兜底
|
||
- 新 runtime 解析第二行,使用 token 值
|
||
|
||
2. **降级 fallback 写在 var() 内部**:
|
||
- `var(--token-name, #fallback)` — 当变量未定义时用 fallback
|
||
- 避免运行时找不到变量直接 `unset`
|
||
|
||
3. **JS `:style` 不强制改**:
|
||
- 已有 `themeStyle.main_color` 字符串拼接是 OK 的(直接色值,各端都支持)
|
||
- CSS `var()` 是双保险
|
||
|
||
---
|
||
|
||
## 三、平台差异点 & 风险
|
||
|
||
### 3.1 微信小程序 (WeChat Mini Program)
|
||
|
||
| 项 | 状态 | 说明 |
|
||
|---|---|---|
|
||
| `<view :style="themeColor">` 注入 CSS 变量 | ✅ 支持 | 已有项目用,无问题 |
|
||
| CSS 变量继承到子元素 | ✅ 支持 | 走标准 CSS 规则 |
|
||
| `var(--x)` 在 `color` / `background` / `border` | ✅ 支持 | 基础属性 |
|
||
| `var(--x)` 在 `linear-gradient()` 内 | ⚠️ 需 v3.0+ | 基础库 3.0.0+ (2024) 完整支持,3.0 以下不支持 |
|
||
| `var(--x)` 在 `-webkit-linear-gradient()` | ⚠️ 需 v3.0+ | 同上 |
|
||
| `-webkit-background-clip: text` + `-webkit-text-fill-color: transparent` | ✅ 支持 | 文本渐变 |
|
||
| `var(--x, #fallback)` fallback 语法 | ✅ 支持 | 现代版本 |
|
||
| `var(--x)` 在 `border-image` | ⚠️ 谨慎 | 偶发问题,本项目未使用 |
|
||
| 鸿蒙元服务底层 | ✅ 同 | 基于 web 标准,微信小程序支持的鸿蒙也支持 |
|
||
|
||
**应对方案**: 写法 2.1(双写法 + 兜底)已规避老 runtime 不支持问题。
|
||
|
||
### 3.2 H5
|
||
|
||
| 项 | 状态 | 说明 |
|
||
|---|---|---|
|
||
| 全部 CSS3 属性 | ✅ 完美支持 | Chrome / Safari / Firefox / Edge |
|
||
| `var()` 嵌套 `linear-gradient` | ✅ 支持 | 现代浏览器 |
|
||
| 性能 | ✅ 几乎无开销 | 不重复计算 SCSS,Vue wrapper 只一层 |
|
||
|
||
### 3.3 鸿蒙元服务 (HarmonyOS Meta Service)
|
||
|
||
| 项 | 状态 | 说明 |
|
||
|---|---|---|
|
||
| CSS 变量 (Custom Properties) | ✅ 支持 | 基于 web runtime |
|
||
| `linear-gradient` | ✅ 支持 | 基础能力 |
|
||
| `-webkit-background-clip: text` | ✅ 支持 | 通过 webkit 兼容 |
|
||
| `rpx` 响应式单位 | ✅ uni-app 编译为 vw/vh | 鸿蒙侧能正常渲染 |
|
||
| 主题切换实时性 | ✅ 支持 | CSS 变量改动即时生效,无重渲染 |
|
||
|
||
---
|
||
|
||
## 四、强制兼容性测试项(上 HBuilder 前必做)
|
||
|
||
```bash
|
||
# 以下命令均在项目根目录（含 package.json）下执行
|
||
|
||
# 1. 静态语法检查
|
||
node --check common/js/theme-override.js
|
||
node --check store/index.js
|
||
# App.vue 走 vue 编译器,不在 node 范畴
|
||
|
||
# 2. H5 端
|
||
npm run dev:h5
|
||
# 访问 http://localhost:9090
|
||
# 验证:
|
||
# - 进入首页 → 主色 = #F4391c 预设红
|
||
# - 后台把 main_color 改为 #00AAFF → 重启 H5 → 主色变蓝
|
||
# - diy-member-info 会员卡渐变跟随切换
|
||
# - loading-cover 加载圈颜色跟随
|
||
# - diy-pintuan 拼团头渐变跟随
|
||
|
||
# 3. 微信小程序端
|
||
npm run dev:mp-weixin
|
||
# 用微信开发者工具打开 dist/dev/mp-weixin
|
||
# 真机预览:
|
||
# - 渲染对比 H5 端(主色、会员卡渐变、loading 颜色应一致)
|
||
# - 后台切换主题 → 重新进入小程序 → 颜色应更新
|
||
# - 重点检查 var() 在 linear-gradient 内是否正常显示
|
||
# - 如果发现旧机型 gradient 失效,回退到双写法已加的兜底色
|
||
|
||
# 4. 鸿蒙元服务端
|
||
npm run dev:app-harmony
|
||
# 用 DevEco Studio 打开,真机或模拟器
|
||
# 验证同上
|
||
```
|
||
|
||
### 已知兼容边界
|
||
|
||
1. **微信小程序基础库 < 3.0** (2024 年以前的极老版本):
|
||
- 极少数用户(可忽略)
|
||
- `var()` 在 `linear-gradient` 内可能失效
|
||
- 兜底双写法会自动回退到单色,不会出现黑/白屏
|
||
|
||
2. **鸿蒙元服务早期 SDK**:
|
||
- 偶发 `var()` 解析时序问题
|
||
- 表现为首次进入主题未应用,刷新后正常
|
||
- 实际项目未发现,可忽略
|
||
|
||
---
|
||
|
||
## 五、改造前后对比(典型场景)
|
||
|
||
### 场景: 主题切换 (default → blue 预设)
|
||
|
||
| 元素 | 改造前 | 改造后 |
|
||
|---|---|---|
|
||
| 主页主按钮 | 始终 `#FF4646` | 跟随 `var(--base-color)` |
|
||
| 价格标签 | 始终 `#F4391c` | 跟随 `var(--main-color)` |
|
||
| 会员卡背景 | 始终 `#7c7878→#201a18` | 跟随 `var(--super-member-start/end-bg)` |
|
||
| 拼团头渐变 | 始终 `#ffbd5b→#fd882e` | 跟随 `var(--pintuan-label-grad-start/end)` |
|
||
| 秒杀折扣渐变 | 始终 `#ff5f17→#fe2f18` | 跟随 `var(--seckill-discount-start/end)` |
|
||
| 分销提现按钮 | 始终 `#ff3c29→#ff6f29` | 跟随 `var(--fenxiao-withdraw-start/end)` |
|
||
| 等级 1~10 徽章 | 始终 10 套固定色 | 跟随 `var(--level-1..10-grad-start/end)` |
|
||
|
||
### 场景: 远端覆写 (管理后台把 main_color 改为 `#00AAFF`)
|
||
|
||
| 元素 | 是否跟随 |
|
||
|---|---|
|
||
| 主页按钮 (`var(--base-color)`) | ✅ 变蓝 |
|
||
| 价格 (`var(--main-color)`) | ✅ 变蓝(因为 main_color 和 base-color 都会改) |
|
||
| 会员卡渐变 | ✅ 跟随 `super_member_*_bg` (如果改了) |
|
||
| 营销渐变 | ✅ 跟随新 token 值 |
|
||
| 加载圈 | ✅ 变蓝 |
|
||
|
||
---
|
||
|
||
## 六、后续行动 (可选)
|
||
|
||
### 6.1 灰阶 token 化(下一阶段 P1)
|
||
|
||
将 `#fff / #000 / #999 / #666 / #f2f2f2 / #f5f5f5` 统一用 SCSS 变量(`uni.scss` 已有 `$color-title / $color-sub / $color-tip / $color-line`):
|
||
|
||
```scss
|
||
// 替代散落的字面量
|
||
$color-title: #303133; // 主标题
|
||
$color-sub: #606266; // 副标题
|
||
$color-tip: #909399; // 提示
|
||
$color-line: #F4F4F6; // 分割线
|
||
$color-disabled: #C0C4CC; // 禁用
|
||
$color-bg: #F8F8F8; // 浅底
|
||
```
|
||
|
||
### 6.2 真正新增 token 到 `style_color.js`
|
||
|
||
以下 placeholder token 可补全为正式 token(让管理后台可见可改):
|
||
|
||
```
|
||
--pintuan-label-grad-start, --pintuan-label-grad-end
|
||
--pintuan-success-start, --pintuan-success-end
|
||
--seckill-price-shallow, --seckill-price-start
|
||
--seckill-discount-start, --seckill-discount-end
|
||
--bargain-promo-shallow
|
||
--member-card-gold-start, --member-card-gold-end
|
||
--balance-page-bg-start, --balance-page-bg-end
|
||
--point-page-bg-start, --point-page-bg-end
|
||
--point-promo-start, --point-promo-end
|
||
--point-item-grad-start, --point-item-grad-end
|
||
--invite-grad-start, --invite-grad-end
|
||
--promote-grad-start, --promote-grad-end
|
||
--fenxiao-withdraw-start, --fenxiao-withdraw-end
|
||
--level-1..10-grad-start, --level-1..10-grad-end
|
||
--member-icon-grad-start, --member-icon-grad-end
|
||
```
|
||
|
||
加到 `common/js/style_color.js` 9 个 preset + 同步 `backend/src/app/api/theme/preset.php` token 清单。
|
||
|
||
### 6.3 鸿蒙专项
|
||
|
||
鸿蒙元服务在色彩空间(P3) / 暗色模式 / 高对比度场景有特殊处理,如需"暗色模式"自动跟随系统,可加:
|
||
|
||
```scss
|
||
@media (prefers-color-scheme: dark) {
|
||
:root { /* 暗色覆写 */ }
|
||
}
|
||
```
|
||
|
||
但这与业务"用户选择主题"是两条独立路径,需要明确:业务主题 vs 系统暗色。当前方案以"业务主题"为准。
|