vivo 妙玩组件设计师 PSD 规范指导文档

1. 适用范围

本规范用于 PSD 自动校验、切图、组件 XML 生成和 vivo 妙玩组件包打包。

强制项用于工具校验；可选项不满足时不阻塞构建，但可能影响效率、体积或后续扩展。

2. 输入资源（单 PSD 必须，其他资源可选）

PSD 是静态结构源，无法表达动效；动效预览与组件内动图只能由设计师另行交付 GIF。

类型	要求
强制	一个规范化 PSD 对应一个组件资源包；不再提供或上传 `lite_2x2.psd`
强制	PSD 内只保留最终会进入资源包的组件、预览图、封面图和必要说明
强制	不得保留废弃方案、参考截图、草稿图层、无意义隐藏层
可选	GIF 集中放在 PSD 同级 `dt/`（动图）目录，无则按纯静态处理
可选	特殊字体放在 PSD 同级目录或 `zt/`（字体）目录
可选	授权材料放在 `sq/`（授权）目录
可选	高级效果使用非默认参数时提供 `dhpz.json`（动效参数文档，见 §12.4）

推荐目录：

组件资源名/
├── sjg.psd                          # 强制：设计稿、切图与结构源
├── dt/                              # 可选：所有 GIF 集中存放
│   ├── 1-2x2-sj.gif                 #   A 预览/封面动图：文件名 == ylt 子组名
│   ├── 2-4x4-tz.gif
│   └── 2-4x4-tz/                    #   B 组件内动图：子目录名 == 组件子组名
│       └── hudie.gif                #     文件名 == PSD 占位层 dtt-hudie 的标识
├── zt/                              # 可选：字体
├── sq/                              # 可选：授权材料
└── dhpz.json                        # 可选：高级效果非默认参数

旧流程曾要求 lite_2x2.psd，原因是当时的切图 PSD 会栅格化文字，工具需要第二个轻量 PSD 读取字体、颜色等文字样式。现在工具优先读取单 PSD 内的 zd-* 母版；母版样式不可读时按组件类型使用内置默认样式，因此不再把内部技术拆分转嫁给设计师。

GIF 有两类完全不同的用途，命名约定如下（沿用「图层命名驱动自动化」原则）：

用途	文件位置	命名映射	关键约束
A 预览/封面动图	`dt/<序号>-<尺寸>-<类型>.gif`	与 `ylt` 子组同名；首个 2x2 同时用作组件库封面	PNG 必选，GIF 可与 PNG 同时提供；尺寸=画布、≤1MB、直角、不透底、推荐 ≤3s
B 组件内动态元素	`dt/<组件子组名>/<标识>.gif`	配 PSD 占位层 `dtt-<标识>`（动态图；包围盒决定位置/尺寸）	<5MB 才动显（≥5MB 静显）、≤3s、需提供动效结束的静态兜底帧

工具按上述命名自动发现 GIF。preview/、thumb/、widget/ 是 vivo 包结构的固定英文目录，不属于 PSD 命名规则。

3. 组件尺寸

尺寸	画布	要求
`2x2`	`432 * 432 px`	强制；首个组件必须是 2x2
`4x2`	`924 * 432 px`	可选
`4x4`	`924 * 924 px`	可选

项目	要求
强制	每个组件必须有完整背景；普通背景或可调透明背景的默认状态均须完全不透明
强制	组件外轮廓直角制作，系统负责圆角裁切
强制	预览图尺寸必须与对应组件尺寸一致
强制	封面图固定 `432 * 432 px`

重要内容左右安全距离：

尺寸	左右安全距离	要求
`2x2`	左右各 `42px`	强制
`4x2`	左右各 `52px`	强制
`4x4`	左右各 `62px`	强制

上下方向不做安全距离要求。

4. PSD 顶层结构

sjg.psd
├── ylt
├── fmt
├── zj-2x2
├── zj-4x2
└── zj-4x4

顶层组	要求
`ylt`	强制；预览图来源
`fmt`	强制；封面图来源
`zj-2x2`	强制；2x2 组件来源
`zj-4x2`	可选；有 4x2 组件时提供
`zj-4x4`	可选；有 4x4 组件时提供

禁止根目录散落组件图层。组件相关名称统一使用中文拼音首字母。

5. 组件命名

格式：

[排序序号]-[尺寸]-[组件类型]

示例：

1-2x2-sj
2-2x2-dl
3-2x2-kjfs
4-4x2-sj
5-4x2-bs
6-4x4-rl

规则	要求
强制	序号从 `1` 开始连续递增
强制	首个组件必须是 `1-2x2-xxx`
强制	单资源包组件数最少 2 个，最多 10 个
强制	`ylt`、`fmt`、`zj-*` 中同一组件必须同名
强制	组件名称中的尺寸必须与所在 `zj-*` 组一致

6. 组件类型

类型	简写
时间/时钟	`sj`
天气	`tq`
日历	`rl`
闹钟	`nz`
设备电量	`dl`
步数/健康	`bs`
屏幕使用时间	`pmsj`
音乐	`yy`
倒计时	`djs`
倒数日	`dsr`
打卡	`dk`
快捷方式	`kjfs`
贴纸/静态图	`tz`
趣味互动	`qwhd`

组件类型只允许使用上表中的拼音首字母简写；禁止继续使用 time、bat、shortcut 等英文类型名。

7. `ylt` 预览图规范

项目	要求
强制	子组命名使用 `[排序序号]-[尺寸]-[组件类型]`
强制	每个 `ylt` 子组必须在对应 `zj-*` 中有同名组件
强制	每个组件必须输出静态 PNG
可选	同一组件可同时提供静态 PNG 和动态 GIF；二者不是互斥关系
可选	动态 GIF 放在 `dt/<子组名>.gif`，并与 `ylt` 子组同名

输出映射示例：

ylt/1-2x2-sj -> preview/widget_2x2_1.png
dt/1-2x2-sj.gif -> preview/widget_2x2_1.gif   # 可选，可与上方 PNG 同时存在
ylt/4-4x2-sj -> preview/widget_4x2_1.png

预览/封面 GIF 约束（vivo 平台硬性要求）：

项目	要求
尺寸	与组件画布完全一致（2x2=432×432，4x2=924×432，4x4=924×924）
体积	≤ 1MB（超限阻塞，工具报 ERROR）
圆角/透明	直角、不透底（禁止圆角与透明通道）
时长	推荐 ≤ 3 秒
内容	必须与组件实际运行效果一致，禁止装饰广告 / 真机隐私截图

8. `fmt` 封面图规范

项目	要求
强制	只能有 1 个封面子组
强制	命名必须与排序第一的 `ylt` 子组一致
强制	尺寸固定 `432 * 432 px`
推荐	封面优先提供精美 GIF 动图（即首个 2x2 的预览 GIF，工具自动复制到 `thumb/`）

示例：

fmt
└── 1-2x2-sj

封面 GIF 无需单独提供：工具会把 dt/<首个2x2子组名>.gif 同时复制为 thumb/widget_2x2_1.gif。

9. 组件内部图层

组件子组内部不得再建立静态、动态、热区等分类组，所有图层和功能资源直接平铺：

1-2x2-sj
├── bj                 # 普通背景；支持透明度调节时改为 bj-tm
├── zs-hua             # 静态装饰（命名不限，此处仅示例）
├── zd-sj              # 自动补全的时间母版
├── dtt-hudie          # 组件内动图占位层
├── rq-jsq             # 计时器点击热区
└── sm-jiaohu          # 可选说明层，不导出

功能图层用拼音前缀表达用途，工具靠前缀识别并自动处理；静态装饰类图层不限定命名。

图层	用途
`bj` / `bj-tm`	背景：普通 / 可调透明度；尺寸=组件画布，二者选一
`zd-*`	自动补全的动态文本母版（见 §11）
`rq-*`	点击热区（见 §12）
`dtt-*`	组件内动图占位层：用 GIF 首帧占位，其包围盒决定动图的位置与尺寸；GIF 文件放 `dt/` 目录靠标识配对（见 §9.2）
`sm-*`	说明层，不进入最终包
静态装饰、图标、人物等	普通静态层，命名不限，能正常进包即可

坐标以每个组件的 bj 或 bj-tm 左上角为 (0,0)。

平铺规则	要求
强制	组件子组内只允许直接图层，不允许再建任何子图层组
强制	功能图层通过拼音前缀表达用途，不通过文件夹分类
强制	同一组件内所有直接图层名称唯一

9.1 可调背景透明度

需要支持用户在组件设置中调节背景透明度时，将背景图层命名为：

bj-tm

项目	要求
命名	普通背景使用 `bj`；支持透明度调节的背景使用 `bj-tm`
数量	一个组件只能有一个 `bj-tm`，且不能同时存在 `bj`
层级	`bj-tm` 必须是组件内最底层图层
尺寸	必须覆盖完整组件画布，左上角坐标为 `(0,0)`
默认状态	必须完全不透明；生成的 `widgetBackgroundAlpha` 固定为 `255`
引擎版本	资源包 `description.xml` 的 `extra_engineVersion` 必须为 `11`

工具识别 bj-tm 后，应生成：

<Image x="0" y="0" align="left" alignV="top"
       src="bj_tm.png" widgetBackgroundAlpha="255"/>

widgetBackgroundAlpha 只用于标记可调透明背景，不用于设置设计稿的初始透明度。

9.2 组件内动态 GIF（可选）

组件内需要循环动效（如背景动图、动态贴纸）时，用「PSD 占位层 + GIF 文件」配对声明：

步骤	要求
① 占位层	在组件子组内直接放置图层，命名 `dtt-<标识>`，如 `dtt-hudie`。标识使用拼音，其包围盒决定动图位置与尺寸，可用静态首帧占位
② GIF 文件	放在 `dt/<组件子组名>/<标识>.gif`，如 `dt/2-4x4-tz/hudie.gif`
③ 体积	< 5MB 才会动态播放；≥5MB 平台只显示静态首帧
④ 时长	≤ 3 秒
⑤ 兜底	GIF 末帧应是动效结束后的稳定静态画面（vivo 硬性要求，否则动画错乱）

工具会把 GIF 打进单组件包，并按占位层几何自动生成：

<Image name="hudie" x="占位层x" y="占位层y" w="占位层w" h="占位层h" src="hudie.gif" loop="true"/>

若缺少占位层，GIF 仍会被打包，但位置回退到整画布左上角 (0,0)，工具会给出 WARN。

10. 静态资源命名

项目	要求
强制	最终导出的资源名只使用小写拼音、数字、连字符 `-`
强制	不使用空格和非法文件字符
强制	同级资源不得重名
推荐	装饰层合并，减少资源数量

命名规则只约束以上几条；功能图层的拼音前缀见 §9，其余静态层命名不限。

示例（仅参考，静态层命名不限）：

bj
zs-hua
tb-nz
rw-xiaoxin
mb-jdt
jdt

10.1 图片状态资源

有些状态是图片而非文字（如电量图标、音乐播放/暂停键），工具无法用文本母版自动补全。设计师为每个状态各画一张图，平铺并按下表命名，工具会按状态变量自动切换显示对应图片。

场景	状态变量	各状态图片
电量图标	`#battery_state`	`dl-tb-0` 默认 / `dl-tb-1` 充电中 / `dl-tb-2` 低电 / `dl-tb-3` 已充满
电量图标	`#battery_type`	`dl-tb-sd` 省电模式（覆盖默认状态，充电/低电优先）
音乐	`#is_music_playing`	`yy-zt-0` 暂停 / `yy-zt-1` 播放

同一组的几张图请保持尺寸和位置一致，切换时才不会跳动。

电量状态表示

电量组件可选择文字、颜色、图标中的一种或多种表示方式；工具统一按以下优先级生成：

状态	条件	文字资源	推荐颜色	图标资源
默认	`#battery_state=0` 且 `#battery_type=1`	`dl-wz-0`（正常）	设计主色	`dl-tb-0`
充电中	`#battery_state=1`	`dl-wz-1`（充电中）	`#34C759`	`dl-tb-1`
低电	`#battery_state=2`	`dl-wz-2`（电量低）	`#FF3B30`	`dl-tb-2`
已充满	`#battery_state=3`	`dl-wz-3`（已充满）	`#34C759`	`dl-tb-3`
省电	`#battery_type=2` 且非充电/低电	`dl-wz-sd`（省电模式）	`#FFCC00`	`dl-tb-sd`

文字状态可只提供一个 zd-dl-zt 母版，由工具自动生成上述五种文案。
颜色状态无需设计师复制图层；工具对同一文字/进度资源自动切换颜色。
自定义图标时提供 dl-tb-*；缺失某状态时工具复用 dl-tb-0，不得生成空白。

10.2 图片混合

多张图片叠加做混合效果时，平铺命名 hh-<组号>-<层序>[-m<模式号>]，工具生成 XML <Group layered="true">：

hh-1-1
hh-1-2
hh-1-3-m6       # 最后一层使用 dst_in

模式号	`xfermode`	模式号	`xfermode`
`m0`	`clear`	`m6`	`dst_in`
`m1`	`src`	`m7`	`src_out`
`m2`	`dst`	`m8`	`dst_out`
`m3`	`src_over`	`m9`	`src_atop`
`m4`	`dst_over`	`m10`	`dst_atop`
`m5`	`src_in`	`m11`	`xor`

规则	要求
强制	同组层序从 `1` 连续递增，PSD 层叠顺序与层序一致
强制	只有最后一层允许 `-m<模式号>`，其余层不得设置混合模式
强制	工具按所有成员联合包围盒生成必填的 `Group w/h`，并设置 `layered="true"`
可选	需要裁剪组边界时由开发配置启用 `clip="true"`
支持	图片与 §10.3 几何图形可加入同一混合组

10.3 几何图形

Photoshop 矢量形状图层命名为 tx-<序号>-<类型>：

图形	类型	XML
矩形	`jx`	`Rectangle`
圆角矩形	`yjjx`	`Rectangle cornerRadius`
圆形	`yx`	`Circle`
椭圆	`ty`	`Ellipse`
扇形	`sx`	`Arc closure="true"`
弧线	`hx`	`Arc closure="false"`
直线	`zx`	`Line`

能力	要求
几何参数	工具从矢量形状读取位置、尺寸、半径、圆角、起始角和扫描角
填充/描边	支持纯色、描边宽度、线帽和虚线；颜色可为 6/8 位十六进制或 `argb`
填充渐变	支持 `FillGradient` 的线性、放射、扫描渐变及多个颜色节点
描边渐变	支持 `StrokeGradient` 的线性、放射、扫描渐变及多个颜色节点
平铺模式	支持 `stretch/mirror/loop`；无法从 PSD 确认时默认 `stretch`
图形混合	需要 `hybridMode` 时按 §10.2 加入 `hh-*` 混合组，由模式号映射
错误处理	普通位图冒充 `tx-*`、无法识别的形状或无效渐变参数均报错

11. 动态切图补全

系统数据（时间、天气、电量、星期……）在运行时会变。设计师不必逐个画所有数字/文字，只需放一个文本母版，工具按场景自动补全整套切片。能力范围以 autocut_wn 插件提供的场景为准，工具用自有 ExtendScript 实现同等效果。

11.1 用法

在组件子组内直接平铺一个文本图层作「母版」，按 §11.2 用 zd- 前缀命名。
母版里写一个示例内容（如 08:08、2025年08月23日、晴、80），并设好字体、字号、颜色、对齐方式。
工具读母版样式与对齐，自动识别其格式并补全该场景整套切片。

项目	说明
样式来源	切片沿用母版自身的字体、字号、颜色，不继承父组
格式识别	数字/中文、分隔符、补零等格式由工具按母版示例内容自动识别
对齐识别	左/中/右按母版文本图层自身属性自动识别，不需要命名后缀
识别失败	母版内容无法识别为任何已知格式时，检测不通过并报错
不支持	位图自动改字、多图层组合补全、父组样式继承

11.2 场景速查表

母版前缀统一 zd-，命名只标场景；数字/中文、分隔符、补零、单复行、简称/全称等格式由工具按母版示例内容自动识别。产物前缀 = 去掉 zd- 后的场景名。

分类	场景（含可自动识别的格式）	文本母版	自动补全产物
时间	数字 / 中文小写 / 中文大写	`zd-sj`	`sj_0..9` 与母版内符号 / 零一二… / 零壹贰…
日期	月日 / 年月日 / 中文日期（按示例识别）	`zd-rq`	数字、母版内符号或中文日期（一~三十一日）
年份	四位年份	`zd-nf`	`nf_0..9`
星期	中文 / 英文	`zd-xq`	`xq_1..7`（1=周日，7=周六）
月份	中文 / 英文	`zd-yf`	`yf_1..12`
农历	农历月 / 农历日	`zd-nl-yf` / `zd-nl-rq`	正月… / 初一…
农历	天干 / 地支	`zd-tg` / `zd-dz`	`tg_` / `dz_`
日历	日历日期（1-31，是否补零按示例识别）	`zd-rl`	`rl_1..31` 或 `rl_01..31`
天气	天气现象（单行 / 换行按母版排版识别）	`zd-tq`	`tq_*`（33 种天气）
温度	温度	`zd-wd`	`wd_0..9`、负号、母版内温度符号
空气质量	优 / 良 / 污染等	`zd-kqzl`	`kqzl_1..7`
电量	电量数字	`zd-dl`	`dl_0..9` 及母版内非数字符号
步数	步数	`zd-bs`	`bs_0..9`
步速	配速	`zd-bsu`	`bsu_0..9` 及母版内 `'` `"` `.` `/` 等符号
计时	倒计时 / 今年·今月·本周·今日剩余	`zd-djs` / `zd-jnsy` `zd-jysy` `zd-bzsy` `zd-jrsy`	对应拼音前缀数字
生日	生日设置 / 生日剩余	`zd-srtc` / `zd-srsy`	对应拼音前缀
生肖	生肖（简称 / 全称按示例识别）	`zd-sx`	鼠… / 子鼠…
星座	星座（简称 / 全称按示例识别）/ 守护神	`zd-xz` / `zd-xz-shs`	射手… / 射手座… / 阿瑞斯…
数字	通用数字	`zd-sz`	`sz_0..9`
字母	小写 / 大写 / 大小写	`zd-zmxx` / `zd-zmdx` / `zd-zm`	小写字母 / 大写字母 / 大小写字母
喝水	喝水次数 / 不限次	`zd-hsdk`	`hsdk_0..8`、`hsdk-bx`

11.3 异常与兜底补全

系统数据可能因未安装、未授权或无网络而取不到。设计师不再为每种异常手工提供 zd-*-dd；工具按组件类型自动生成兜底文案、显隐条件和默认样式。设计师若提供 zd-*-dd，仅用于覆盖默认视觉样式。

场景	触发条件（vivo 变量）	兜底内容	兜底母版 → 产物
天气	`#weather_code` = 1/2/3/4	使用 `@weather_exception_text`；同步隐藏温度、空气质量等正常数据	`tq-dd`
温度/空气质量	天气异常	`--` 或隐藏，由所属天气组件统一控制	`wd-dd` / `kqzl-dd`
步数/步速	步数 < 0 或无数据	`--`	`bs-dd` / `bsu-dd`
屏幕时间	`#screen_state=0`	使用 `@screen_off_text`，隐藏小时/分钟	`pmsj-dd`
闹钟	无临近闹钟	使用 `@next_alarm_empty_text`	`nz-dd`
日历	`#calendar_uninstall_status=1`	使用 `@calendar_uninstall_text`	`rl-dd`
电量	状态变量缺失	显示 `--%`，图标回退 `dl-tb-0`	`dl-dd`
音乐	未播放或数据缺失	显示默认封面和暂停图标	`yy-dd`

同一个组件包含日历、日期和星期时，三者视为一个显示单元。日历未安装时，必须同步隐藏 zd-rl、zd-rq、zd-xq 的正常内容，只显示 rl-dd。
自动兜底样式默认继承对应 zd-* 母版；没有母版时使用系统字体、设计主色和安全区内居中布局。
设计师提供的 zd-*-dd 只覆盖样式，不改变工具生成的条件与内置文案。

12. 点击热区与动效

热区是透明矩形图层，统一 rq- 前缀，可用于跳转 App 或触发点击动效；没有点击行为则不需要热区。

12.1 跳转热区

命名 rq-<目标>，点击跳转到对应系统功能或 App。简写取应用名拼音首字母缩写；表外 App 自行按此规则命名。

图层名	目标	图层名	目标
`rq-nz`	系统闹钟	`rq-wx`	微信
`rq-jsq`	计时器	`rq-wb`	微博
`rq-rl`	系统日历	`rq-dy`	抖音
`rq-tq`	系统天气	`rq-xhs`	小红书
`rq-bs`	运动步数	`rq-blbl`	哔哩哔哩
`rq-pmsj`	屏幕使用时间	`rq-zfb`	支付宝
`rq-bj`	组件编辑页	`rq-tb`	淘宝
`rq-yy`	系统音乐	`rq-jd`	京东
`rq-dhyy`	系统电话	`rq-mt`	美团
`rq-qqyy`	QQ 音乐	`rq-wyy`	网易云音乐

12.2 点击动效

一次点击可触发一个或多个目标动画。热区与目标用「事件号」关联，所有图层直接平铺：

1-2x2-qwhd
├── rq-dh-1             # 事件 1 的触发热区
├── dh-1-1-dd           # 目标 1：抖动
├── dh-1-2-xlz          # 目标 2：序列帧
└── dh-1-3-xz           # 目标 3：旋转

触发热区 rq-dh-<事件号>；动画目标 dh-<事件号>-<目标号>-<类型>。
同一事件号下的目标同时开始；某图层既是触发又是目标时，rq-dh-x 与 dh-x-1-lx 用相同包围盒。

动画类型 lx 取值：

类型	`lx`	外部资源
序列帧	`xlz`	`xlz-<x>-<y>.zip`（独立上传；只从 ZIP 读帧，PSD 不放帧）
GIF 单次 / 循环	`dt` / `dtxh`	`dt/<组件名>/dh-<x>-<y>.gif`
抖动 / 位移 / 旋转 / 透明	`dd` / `wy` / `xz` / `tm`	无

高级效果：命名 rq-gj-<x> + gj-<x>-<lx>（主资源）+ gj-<x>-<lx>-1..n（附加图片），一个组件最多一种：

高级效果	`lx`	资源
水波纹	`sbw`	`gj-x-sbw`
网格位移/旋转/水波/缩放/透明	`wgwy` / `wgxz` / `wgsb` / `wgsf` / `wgtm`	`gj-x-<lx>`
下落	`xldh`	`gj-x-xldh-1..n`
粒子化散落 / 粒子散落	`lzsl` / `lzzy`	`gj-x-lzsl` / `gj-x-lzzy-1..n`

网格位移/旋转/缩放可各自叠加网格透明度，合法组合写 gj-x-wgwy-tm、gj-x-wgxz-tm、gj-x-wgsf-tm；水波不与其他网格组合。

两个简单热区（单一动作，不走事件号）：

机制	热区	资源
切换图片	`rq-qh-tp-<x>`	`qh-tp-<x>-1`、`qh-tp-<x>-2`…（≥2 张同序号，点击在它们间切换；可包含背景）
单序列帧	`rq-xlz-<x>`	`xlz-<x>.zip`（独立上传，与热区同序号）

序列帧 ZIP 内平铺帧，建议三位连号 -001、-002。

切换图片、背景与快捷方式

背景参与切换时命名 qh-tp-<x>-<状态>-bj；工具保证当前状态只有一个背景可见。
普通前景图使用 qh-tp-<x>-<状态>-<标识>；同一状态的多个图层一起切换。
某个切换状态需要快捷方式时，在对应图片旁平铺 rq-qh-tp-<x>-<状态>-<目标>，例如 rq-qh-tp-1-2-wyy。
快捷方式热区只在对应状态可见，切换状态后必须同步更新热区，不能保留上一状态的跳转。
切换组内仍不创建 PSD 子文件夹，所有图片、背景和热区直接平铺。

12.3 通用规则

规则	要求
强制	有点击行为必须用 `rq-` 热区命名；无点击则不需要
强制	单次动画 ≤ 3 秒，不得无限循环；动态图片/动画必须有播放结束后的静态兜底帧
强制	高级效果一个组件只能有一种（水波 / 网格 / 下落 / 粒子互斥）
强制	事件号 / 资源号从 `1` 连续递增；序号重复、目标缺失、类型未知、序列帧 ZIP 缺失 → 报错阻塞
强制	未在上表登记的 `lx` 必须报错，不得猜测生成；新增类型先登记
强制	`kjfs`（快捷方式）组件禁止动态图片与动画
推荐	热区点击区域不小于 `46dp * 46dp`，不允许无意义重叠

12.4 动效参数文档（`dhpz.json`）

图层名只决定「用哪种动效、配哪些资源」。动效的数值参数（时长、网格数、粒子样式等）写不进图层名，统一放在 PSD 同级的 dhpz.json：键 = 目标图层名，值 = 该效果的参数。不配置就用官方默认值。

{
  "gj-1-sbw": {"xmesh": 20, "ymesh": 20, "torsion": 2},
  "gj-2-lzsl": {"duration": 1000, "style": 7, "shape": 0, "radius": 6}
}

各效果可配的参数与取值范围：

效果	参数（取值范围）
变量动画	`duration` 时长（≤3 秒，必填，需有结束静态帧）
GIF	`loop` 单次/循环；文件 `<5MB` 才动
水波纹	`xmesh`/`ymesh` 网格数（≤20）；`torsion` 扭曲度（1–10）；`color` 可选
网格·公共	`mesh` 网格数；`center_point` 中心点；`sensor` 是否响应传感器
网格·位移	`factor` 回弹（0–1）；`values` 运动值（2–5 个）
网格·旋转	`values` 角度（2–5 个）
网格·水波	`a` 振幅；`factor_k` 速度
网格·缩放/透明	`values` 数值（2–5 个）；`duration`/`repeat`/`delay`
下落	`gravityX`/`gravityY` 重力；`airDensity` 空气密度（正数）；分区 `alphaStart/alphaEnd`（0–255）、`sizeStart/sizeEnd`（0–1）
粒子·图片粒子化	`style` 散落方式（1–9）；`duration`（>200ms、≤3 秒）；`shape` 形状（0/1/2）；`radius` 半径（>4，且 ≤短边 1/6）
粒子·图片散落	`style`（推荐 1/2/7）；每个 `Item` 的 `number`（>4）
透明组件	背景层 `bj-tm`；输出 `widgetBackgroundAlpha="255"`、`extra_engineVersion=11`

规则	要求
互斥	水波 / 网格 / 下落 / 粒子，一个组件只能选一类
默认值	未配置的参数用官方默认值；无默认又无法从图层推导时报错
键匹配	每个键必须对应唯一图层；未知键、未知参数、越界值均报错

13. 可编辑组件

倒数日、打卡等需要用户自定义文字的组件，用 bjx- 前缀标记可编辑文本图层：

bjx-dsr-[默认事件名]      # 倒数日
bjx-dk-[默认打卡名]       # 打卡

项目	要求
可选	非倒数日/打卡组件不需要
强制	`2x2`、`4x2` 最多 2 个编辑项
强制	`4x4` 最多 4 个编辑项
推荐	默认事件名使用小写拼音标识

13.1 喝水不限次

喝水属于打卡类型。#water_countdown=99999 表示不限次：

正常次数：显示目标次数和当前次数。
不限次：隐藏目标次数数字，显示 hsdk-bx（不限次）；当前次数继续正常累计。
设计师只需提供 zd-hsdk 母版；工具补全 0..8 和 hsdk-bx。

13.2 倒数日两种状态

倒数日必须同时支持：

状态	条件	显示规则
还未到	`#*_countdown >= 0`	显示 `dsr-wd`（还有）和原始天数
已过	`#*_countdown < 0`	显示 `dsr-yg`（已过去），天数使用 `abs(#*_countdown)`

两种状态共用数值母版，工具自动生成显隐表达式；不得把负号直接展示给用户。

14. 字体与字重

项目	要求
可选	使用系统默认字体时不需要提供字体文件
强制	使用特殊字体时必须提供字体文件和授权
强制	字体文件名使用小写拼音、数字、连字符
可选	字体放 PSD 同级目录或 `zt/` 目录

需要指定字重或自定义字体时，文本图层在原业务名后增加格式后缀：

wz-bt-zz-65                 # 系统默认字体，字重 65
wz-bt-zk-xiaozujian         # 使用 zt/xiaozujian.ttf
zd-sj-zz-65                 # 动态母版同样可带字重

项目	要求
字重后缀	`-zz-<值>`，值只能是 `35/45/55/65/75/85/95`
字体后缀	`-zk-<字体标识>`，标识对应 `zt/<字体标识>.ttf`
后缀顺序	`<业务名>[-zz-<值>][-zk-<字体标识>]`
默认字体	多档 `textWeight` 仅对系统默认字体生效
自定义字体	工具生成 `typeface="etc/<字体文件>"`；字体文件与授权必须同时交付
校验	非法字重、字体文件缺失、同标识多文件均报错

15. 深色模式

项目	要求
可选	不做深色模式时默认 `supportdark=false`
强制	做深色模式时浅色/深色资源必须成对
推荐	使用 `-q`（浅）、`-s`（深）命名

16. 文件名限制

最终进入包的资源文件名只允许小写拼音、数字和以下必要符号：

a-z 0-9 - / .

.gif、.png、.zip、.json 等格式扩展名保留；组件内动图标识同样只用小写拼音、数字和连字符，并与占位层 dtt-<标识> 一致。

禁止	原因
空格	XML 和脚本处理风险
中文文件名	打包和跨环境风险
`\ : * ? " < > \|`	文件系统非法或高风险
`拷贝`、`副本`、`图层 1`	无语义，易冲突

17. 合格结构示例

sjg.psd
├── ylt
│   ├── 1-2x2-sj
│   ├── 2-2x2-dl
│   └── 3-4x2-bs
├── fmt
│   └── 1-2x2-sj
├── zj-2x2
│   ├── 1-2x2-sj
│   │   ├── bj
│   │   ├── zd-sj
│   │   ├── zd-xq
│   │   ├── rq-jsq
│   │   └── rq-rl
│   └── 2-2x2-dl
└── zj-4x2
    └── 3-4x2-bs

18. 工具自动检测项（第 5 步）

以下项由工具在第 5 步自动检测：强制项不通过会阻塞构建，条件项在使用对应功能时检测。

工具检测项	级别
PSD 根目录只有规范顶层组	强制
`ylt`、`fmt` 存在	强制
组件数 2-10 个	强制
第一个组件是 2x2	强制
`ylt` 与 `zj-*` 同名匹配	强制
`fmt` 与第一个预览图同名	强制
组件类型使用 §6 规定的拼音首字母简写	强制
组件子组内部所有图层直接平铺，不存在子图层组	强制
每个组件有且只有一个完整背景：`bj` 或 `bj-tm`	强制
`bj-tm` 位于最底层、默认不透明，且引擎版本为 11	使用可调透明背景时强制
动态文本补全对象是文本图层	强制
切图补全覆盖 §11 中 `autocut_wn` 的全部功能场景	强制
每个自动补全场景存在且仅存在一个合法 `zd-` 文本母版	强制
步数补全包含 `bs_0..9` 与兜底资源 `bs_dd`	使用步数组件时强制
异常/无数据场景按 §11.3 由工具自动生成条件、文案和兜底资源	使用对应组件时强制
日历未安装时日历、日期、星期正常内容同步隐藏	单组件同时包含三者时强制
电量文字、颜色和图标状态按 §10.1 自动生成；缺图标状态回退默认图标	使用电量组件时强制
喝水 `99999` 自动显示不限次；倒数日负数自动显示已过去和绝对值	使用对应组件时强制
点击热区使用 `rq-`	有点击时强制
多目标动画热区 `rq-dh-x` 至少匹配一个 `dh-x-y-lx`	使用多目标动画时强制
动画类型已登记，事件和目标序号连续且唯一	使用多目标动画时强制
`dh-x-y-xlz` 能匹配唯一的 `xlz-x-y.zip`	多目标中使用序列帧时强制
`dh-x-y-dt`、`dh-x-y-dtxh` 能匹配 `dt/<组件名>/dh-x-y.gif`	多目标中使用 GIF 时强制
所有动画时长不超过 3 秒，并具有结束静态状态	使用动画时强制
高级效果非默认参数已在 `dhpz.json` 中按图层名配置	使用高级效果且需调参时强制
高级效果使用 `rq-gj-x`、`gj-x-lx`，且一个组件只有一种高级效果	使用高级效果时强制
网格动画组合符合 §12.2 允许列表	使用组合网格动画时强制
高级效果附加资源 `-1..n` 连续且不缺号	使用多资源高级效果时强制
`kjfs` 组件不包含动态图片或动画效果	强制
切换图片热区 `rq-qh-tp-x` 与平铺图片 `qh-tp-x-*` 序号一致	有切换图片功能时强制
切换背景 `qh-tp-x-z-bj` 与状态同步，且每个状态只有一个背景可见	背景参与切换时强制
切换状态快捷方式 `rq-qh-tp-x-z-mb` 只在对应状态可见	切换组含跳转时强制
序列帧热区 `rq-xlz-x` 能匹配唯一的 `xlz-x.zip`	有序列帧动画时强制；缺失时报错
序列帧图片只从独立 ZIP 读取，不从 PSD 图层组读取	有序列帧动画时强制
常用应用快捷方式使用 `wx`、`wb`、`dy`、`qqyy`、`wyy` 简写	有对应快捷方式时强制
可编辑项数量不超限	有编辑项时强制
`-zz-` 字重属于 `35/45/55/65/75/85/95`	使用自定义字重时强制
`-zk-` 字体标识能匹配唯一字体文件和授权	使用自定义字体时强制
图片混合 `hh-*` 层序连续，且仅末层设置合法 `m0..m11`	使用图片混合时强制
几何图层使用 `tx-<序号>-<类型>` 且为可解析矢量形状	使用几何图形时强制
几何填充、描边、渐变节点和平铺模式参数有效	使用几何样式时强制
水波、网格、下落、粒子参数符合 §12.4 边界	使用对应高级效果时强制
下落动效的透明度/尺寸区域、方向和 Item 资源完整	使用下落动效时强制
粒子散落场景、样式、半径、数量和资源尺寸合法	使用粒子散落时强制
`dhpz.json` 中每个键和参数均能匹配目标图层与官方字段	提供动效参数文档时强制
特殊字体已提供授权和文件	用特殊字体时强制
无草稿、废弃图层、无意义隐藏层	强制
预览静态 PNG 必须存在；同名动态 GIF 可同时存在	PNG 强制，GIF 可选
预览/封面 GIF：尺寸=画布、≤1MB、直角不透底、≤3s	提供预览 GIF 时强制
组件内 GIF：<5MB、≤3s、末帧为静态兜底、配 `dtt-<标识>` 占位层	提供组件内动图时强制
GIF 文件命名与目录符合 §2 映射	提供 GIF 时强制

PSD 规范