@easyv/screen-cli 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -7,14 +7,19 @@ description: 从零搭建一个 EasyV 可视化大屏。先判断用现成组件
7
7
 
8
8
  ## 组件从哪来
9
9
 
10
- 1. `easyv-screen component list` 看平台和当前空间有哪些组件,按中文 `name` 和 `category` 判断用途。
11
- 可以用 `--keyword <中文名>` 缩小范围。
12
- 2. 拿不准某个组件是否合适时,`easyv-screen component schema <module>` 看它的 `dataFields`(需要什么数据)、
13
- `triggers`(能发出什么事件)和 `size`(默认尺寸)。`fields` 很大,不要整份读,改配置时用下面的 `component fields` 查。
14
- 3. `requiresPreset: true` 的组件暂时不能通过 CLI 新增,换一个组件。
15
- 4. 现成组件都表达不好需求时,用 `easyv-component-dev` 技能从零开发并上传,再引用返回的 module 和版本。
10
+ 新增组件前先读 [component-selection.md](references/component-selection.md)。文档里已有对应 module 的,直接用,不再查列表,也不新开发。
11
+
12
+ 文档里没有的,再按这个顺序选型,接口按需调用,不要一次把两类组件都拉下来:
16
13
 
17
- 一个大屏里可以混用平台组件和自己开发的组件,不要为了用现成组件而凑合。
14
+ 1. `easyv-screen component list --keyword <中文名>` 查 EasyV 官方组件。列表只含已发布组件,不含定制组件。
15
+ 按中文 `name` 和 `category` 判断用途。
16
+ 2. 官方组件都不合适时,再 `easyv-screen component list --source space --keyword <中文名>` 查当前空间自己开发、且已发布的组件。
17
+ 3. 拿不准某个组件是否合适时,`easyv-screen component schema <module>` 看它的 `dataFields`(需要什么数据)、
18
+ `triggers`(能发出什么事件)和 `size`(默认尺寸)。`fields` 很大,不要整份读,改配置时用下面的 `component fields` 查。
19
+ 父组件带图层时,先 `easyv-screen component children <module>` 拿到子组件 `module`,再用
20
+ `component schema <module> --child <子组件>` 和 `component fields <module> --child <子组件> --keyword "<意图>"`。
21
+ 4. `requiresPreset: true` 的组件暂时不能通过 CLI 新增,换一个组件。
22
+ 5. 官方组件和空间组件都表达不好需求时,用 `easyv-component-dev` 技能从零开发并上传,再引用返回的 module 和版本。
18
23
 
19
24
  ## 步骤
20
25
 
@@ -30,8 +35,17 @@ description: 从零搭建一个 EasyV 可视化大屏。先判断用现成组件
30
35
  5. `easyv-screen screen apply <id> -f ops.json --if-match <revision>` 一次提交。
31
36
  返回 `COMPONENT_CONFIG_INVALID` 时按 `details.elements[].unknownPaths` 重新查路径再提交。
32
37
  6. `easyv-screen screen validate <id>` 检查。`ELEMENT_OUT_OF_CANVAS`、`ELEMENT_OVERLAP`、`ELEMENT_HIDDEN` 说明布局有问题,调整后再提交。
33
- 7. `easyv-screen screen snapshot <id> -o preview.png` 截图对照需求检查。预览页是布局示意图,用来核对位置和显隐,不是最终渲染效果。
34
- 8. 确认后询问用户是否 `easyv-screen screen publish <id>`。
38
+ 7. `easyv-screen screen snapshot <id> -o preview.png` 截图对照需求检查。这张图用来核对位置和显隐。要看组件真实渲染,按下面的「看实际效果」。
39
+ 8. 确认后询问用户是否 `easyv-screen screen publish <id>`。这是交付时的正式发布。
40
+
41
+ ## 看实际效果
42
+
43
+ 用 `easyv-screen config list` 拿到的 `baseUrl` 拼地址,在浏览器里打开。
44
+
45
+ - 预览链接:`{baseUrl}/preview/{screenId}`。需要登录。优先用已经打开、并且登录过这个工作台的浏览器访问。
46
+ - 发布链接:`{baseUrl}/shareScreen/{shareInfo}`。`shareInfo` 是 `{ screenId: <大屏 id> }` 的 base64,id 为数字时不要加引号。大屏已公开发布时,打开这个链接不用登录。
47
+
48
+ 预览链接要求登录、而当前浏览器没有登录时,改打开发布链接。大屏本来就是公开发布的,直接打开,不要再执行发布或取消发布。只有当前大屏未发布时,才先跟用户确认,再临时公开发布:`easyv-screen screen publish <id>`,看完效果后执行 `easyv-screen screen unpublish <id>` 关掉。这次发布只用于查看。
35
49
 
36
50
  ## 文档要点
37
51
 
@@ -0,0 +1,182 @@
1
+ # 组件选型
2
+
3
+ 新增组件之前先对照这里。命中某一条就用列出的官方 module,不要再开发一个同类组件。这里没有的,再按 `easyv-screen-build` 里的顺序查官方组件和空间组件。
4
+
5
+ 以后增加的选型往下表和后面的分节里追加,一条需求对应一个 module。
6
+
7
+ | 需求 | module | 怎么用 |
8
+ | --- | --- | --- |
9
+ | 图片装饰、背景、图标等静态图 | `imageV2` | 不新开发。相对路径写入配置项「图片上传」,数据 `url` 留空 |
10
+ | 视频 | `videoV2` | 不新开发。相对路径写入配置项「视频」,封面写入「封面」,数据 `url` 留空 |
11
+ | 数字类指标 | `counterV2` | 优先用。标题、前缀、后缀和数值写在数据里,样式写在配置项里 |
12
+ | 一组可切换的选项卡 | `tabV2` | 不新开发。每条数据是一个选项,文案写在 `content`,样式写在配置项里 |
13
+ | 行政区底图、点位、飞线、区域填色、热力 | `basicPlaneMap` | 不新开发。父组件只管范围和视角,业务数据写在子图层 |
14
+ | 立体行政区边界、下钻,以及边界上的柱、点、飞线、区域填色 | `borderMap3dV2` | 不新开发。父组件只定主地图范围,业务数据写在子图层 |
15
+ | 当前时间、日期或时钟 | `nowV2` | 不新开发。不给数据就按当前时间每秒刷新;要固定某个时刻时写在数据第一条的 `time` |
16
+
17
+ 图片、视频、翻牌器和时间组件只使用数据的第一条。选项卡和地图子图层按数据逐条渲染。基础平面地图的父组件不消费数据。3D 边界地图的父组件只读第一条的 `adcode`。时间组件没有有效 `time` 时按当前时间每秒刷新。配置路径不要猜,用 `easyv-screen component fields <module> --keyword "<意图>"` 查到的 `path` 原样写进 `configPatches`。
18
+
19
+ ## 图片 imageV2
20
+
21
+ 装饰图、背景图、图标、示意图用官方图片组件 `imageV2`。不要为了一张图新开发组件。
22
+
23
+ 上传得到的相对路径 `path` 写入配置项「图片上传」(`chart.url`)。数据保持 `[{ "url": "" }]`。数据里的 `url` 非空时会盖掉配置,并直接作为图片地址,不再拼接资源前缀,相对路径放进去会显示不出来。绝对地址可以放在数据 `url` 里,但域名绑死在当时的环境。上传、相对路径和拼接方式见 [assets.md](../../easyv-component-dev/references/assets.md)。
24
+
25
+ 样式在配置项里。要保持比例时把「尺寸」改成「自适应」;默认是「拉伸以充满容器」,会拉变形。圆角、透明度、混合模式、滤镜也在配置项里,用 `component fields imageV2 --keyword "<意图>"` 查。
26
+
27
+ ## 视频 videoV2
28
+
29
+ 视频用官方组件 `videoV2`。不要为了播放一段视频新开发组件。
30
+
31
+ 相对路径写入配置项「视频」(`chart.videoSrc`)。封面图的相对路径写入配置项「封面」(`chart.imageSrc`)。数据保持 `[{ "url": "" }]`。数据里的 `url` 非空时会盖掉配置里的视频地址,并直接作为播放地址,不再拼接资源前缀。封面始终按配置里的相对路径拼接。上传和路径约定与图片相同,见 [assets.md](../../easyv-component-dev/references/assets.md)。
32
+
33
+ 播放和外观在配置项「播放设置」里:控制条、自动播放、循环播放、静音、自动隐藏。静音默认开启。缩放方式默认「填充」,要保持比例时改为「原比例」或「裁切」。透明度、混合模式、旋转、滤镜同样用 `component fields videoV2 --keyword "<意图>"` 查。
34
+
35
+ ## 数值指标 counterV2
36
+
37
+ 数字类指标优先用翻牌器 `counterV2`。标题、前缀、后缀和数值都写在静态数据里,只使用第一条:
38
+
39
+ ```json
40
+ [
41
+ {
42
+ "name": "销售额",
43
+ "value": 1234.56,
44
+ "prefix": "¥",
45
+ "suffix": "万元"
46
+ }
47
+ ]
48
+ ```
49
+
50
+ | 字段 | 含义 |
51
+ | --- | --- |
52
+ | `name` | 标题 |
53
+ | `value` | 数值,必须是有限数字 |
54
+ | `prefix` | 前缀文字 |
55
+ | `suffix` | 后缀文字 |
56
+
57
+ `addComponent` 或 `setComponentStaticData` 的 `data` 传这个数组。配置项里的「内容」只在对应数据字段为空时才显示,文案不要写进配置。
58
+
59
+ 样式写在配置项里,用 `component fields counterV2 --keyword "<意图>"` 查,例如「排列方式」「标题 文本样式」「前缀 文本样式」「数值 字号」。标题默认开启。后缀默认开启。前缀默认关闭,数据里写了 `prefix` 时,要把配置项「前缀」的「开启」设为 `true`,否则前缀不显示。
60
+
61
+ ## 选项卡 tabV2
62
+
63
+ 一组可切换的选项用官方选项卡 `tabV2`。不要为了做页签新开发组件。
64
+
65
+ 每条数据是一个选项,全部渲染。文案写在数据里:
66
+
67
+ ```json
68
+ [
69
+ { "s": "1", "content": "总览" },
70
+ { "s": "2", "content": "销售" },
71
+ { "s": "3", "content": "库存" }
72
+ ]
73
+ ```
74
+
75
+ | 字段 | 含义 |
76
+ | --- | --- |
77
+ | `s` | 选项的类别值,用来匹配单项样式,也会随点击和选中变化抛出 |
78
+ | `content` | 选项上显示的文字 |
79
+
80
+ `addComponent` 或 `setComponentStaticData` 的 `data` 传这个数组。选项文字不要写进配置项「系列」。
81
+
82
+ 样式写在配置项里,用 `component fields tabV2 --keyword "<意图>"` 查。「默认」和「选中」各有一套文字、背景、描边、图标。背景填自定义图片、或打开图标时,图片地址写相对路径。某一项要单独换样式时,在「系列」里加一条,把系列的 `s` 设成该选项数据里的 `s`;对不上的选项用上面的两套全局样式。
83
+
84
+ 默认选中第 1 项。「默认选中」从 1 开始计数,`0` 表示一开始不选中。布局默认固定列数、4 列。选项排成一行时,把「列数」改成选项个数;要竖排时改成固定行数。选项放不下时打开「滚动条」。自动轮播默认关闭。
85
+
86
+ ## 基础平面地图 basicPlaneMap
87
+
88
+ 行政区划底图,以及底图上的点、飞线、区域填色、热力,用官方组件 `basicPlaneMap`。不要新开发地图。
89
+
90
+ 父组件的静态数据保持 `[]`。点位和区域数值不要写进父组件的 `data`。地图范围和视角写在父组件配置项里,用 `component fields basicPlaneMap --keyword "<意图>"` 查。
91
+
92
+ - 来源默认「系统默认」。地图范围 `adcode` 默认 `100000`,即全国。换省、市时改这个行政区编码。自定义边界用来源「自定义」,上传 GeoJSON 压缩包。
93
+ - 坐标系保持 `EPSG3857`。
94
+ - 精准定位默认关闭,按行政区范围自适应,再把几何中心放到「定位中心」。要指定中心经纬度和缩放级别时,先把「精准定位」设为 `true`。
95
+ - 区域名称默认关闭。
96
+
97
+ 业务数据写在子图层上,一条数据一个点或一条线,全部渲染。子图层数据的 `id` 要和该子组件配置的 `id` 相同,才能灌进这一层。经纬度是 `lng`、`lat` 两个字段。
98
+
99
+ | 需求 | 子图层 | 数据 |
100
+ | --- | --- | --- |
101
+ | 点标记 | `VectorScatterLayer` | `lng` `lat` `type` `value`。`type` 和系列里的 type 一致时用该系列样式;对不上的 type,只有系列 type 为空才会按顺序分到这些空系列,否则不画 |
102
+ | 点聚合 | `ClusterLayer` | `lng` `lat` `type`。名称在 `name`,空字符串不显示 |
103
+ | 标牌 | `BubbleLayer` | `lng` `lat` `value`。`value` 是标牌文字 |
104
+ | 热力点 | `HeatmapLayer` | `lng` `lat` `value`。`value` 是权重 |
105
+ | 飞线 | `FlylineLayer` | `fromLng` `fromLat` `toLng` `toLat`。经度相同或纬度相同的线段不画 |
106
+ | 区域填色 | `AreaHeatmapLayer` | `name` `adcode` `value`。用 adcode 或区域名称和底图面要素对齐 |
107
+ | 信息面板 | `InfoPanelLayer` | `lng` `lat` `state`。其余字段要在内容样式里配了键名才显示 |
108
+
109
+ 轨迹和自定义面用 GeoJSON,坐标顺序是 `[lng, lat]`。`PathLayer` 用 `LineString`,`PolygonLayer` 用 `Polygon`,样式按 `properties.type` 匹配系列。
110
+
111
+ 组件预设带出背景、标牌、飞线和矢量散点。区域填色、热力、聚合、信息面板要再挂对应子图层。
112
+
113
+ 子图层不是独立发布的 module。名单用 `easyv-screen component children basicPlaneMap` 查看,返回的 `module` 就是 `--child` 的取值,`id` 用来对齐这一层的数据。查父组件时不要带 `--child`,返回里只有父组件自己的配置。要看某一层时再加上它的 module_name,例如 `easyv-screen component fields basicPlaneMap --child VectorScatterLayer --keyword "尺寸"`。数据字段用 `easyv-screen component schema basicPlaneMap --child VectorScatterLayer`。子组件不存在时接口返回 `COMPONENT_CHILD_NOT_FOUND`。
114
+
115
+ ## 3D边界地图 borderMap3dV2
116
+
117
+ 立体的行政区边界,以及边界上的柱、点、飞线、标牌、区域填色、热力,用官方组件 `borderMap3dV2`。平面底图继续用 `basicPlaneMap`。不要新开发 3D 边界地图。
118
+
119
+ 父组件只读静态数据第一条的 `adcode`,用来指定主地图范围。点位、柱值和区域数值写在子图层。数据为空时,用配置项里的地图范围。
120
+
121
+ ```json
122
+ [{ "adcode": "330000" }]
123
+ ```
124
+
125
+ | 字段 | 含义 |
126
+ | --- | --- |
127
+ | `adcode` | 主地图的区划编码。字符串或数字都可以,只取第一条 |
128
+
129
+ 自定义动作「设置主地图」优先于这条数据,数据又优先于配置项。地图范围、厚度、顶面和视角写在父组件配置项里,用 `component fields borderMap3dV2 --keyword "<意图>"` 查。
130
+
131
+ - 来源默认「系统默认」。地图范围默认 `330000`,即浙江省。换省、市时改这个行政区编码。自定义边界用来源「自定义」,上传 GeoJSON 压缩包。压缩包里的文件名(去掉后缀)就是 adcode,入口文件决定主地图。
132
+ - 投影方式默认「墨卡托」。要按经纬度等距展开时改为「WGS84」。
133
+ - 区域名称默认开启。
134
+
135
+ 双击一块区域会下钻到它的 adcode,能取到下一级 GeoJSON 才会进入。单击聚焦默认开启。
136
+
137
+ 业务数据写在子图层上,一条数据一个点、一根柱或一条线,全部渲染。经纬度是 `lng`、`lat` 两个字段。
138
+
139
+ | 需求 | 子图层 | 数据 |
140
+ | --- | --- | --- |
141
+ | 点标记 | `scatter` | `lng` `lat` `type` `value`。`type` 和数据系列的系列名一致时用该系列;为空或对不上时用第一个系列。`value` 用来做尺寸和颜色映射 |
142
+ | 柱状图 | `column` | `name` `value`,再加上 `lng` `lat` 或 `adcode`。有合法经纬度就落在该点并按经纬度分组;否则用 `adcode` 找当前地图块的几何中心,对不上的不画。同一位置的多条合成一组,按系列绕中心排开。`s` 和柱状系列的系列名一致时用该系列,对不上时用第一个系列。`value` 在配置的最小、最大高度之间插值。`suffix` 可选,`name` 是这组柱子的名称 |
143
+ | 标牌 | `board` | `lng` `lat` `value`。`value` 是标牌上的主文字,前缀和后缀写在配置项里 |
144
+ | 信息面板 | `infoPanel` | `lng` `lat` `state`。`state` 和状态背景的状态值一致时用该背景,对不上时用第一个状态。其余字段要在行配置里配了字段名才显示 |
145
+ | 飞线 | `flyLine` | `fromLng` `fromLat` `toLng` `toLat` |
146
+ | 区域热力 | `areaHeat` | `adcode` `value`。用 adcode 和当前地图块对齐,对不上的区块用空值颜色。`name` 不参与对齐 |
147
+ | 聚合热力 | `clusteringHeat` | `lng` `lat` `value`。`value` 是权重 |
148
+
149
+ 路径、围栏、多边形的形状来自子图层配置里的 GeoJSON,水系来自按 adcode 命名的 shp 压缩包。这几层的数据面板是空的。图片和灯光是装饰层,也不消费数据。
150
+
151
+ 组件预设带出图片、散点、灯光和信息面板。柱状图、飞线、标牌、区域热力、聚合热力、路径、围栏要再挂对应子图层。
152
+
153
+ 子图层不是独立发布的 module。名单用 `easyv-screen component children borderMap3dV2` 查看。查父组件时不要带 `--child`。要看某一层时加上它的 module_name,例如 `easyv-screen component fields borderMap3dV2 --child column --keyword "柱状"`。数据字段用 `easyv-screen component schema borderMap3dV2 --child column`。
154
+
155
+ ## 时间 nowV2
156
+
157
+ 当前时间、日期和时钟用官方时间组件 `nowV2`。不要为了显示时间新开发组件。
158
+
159
+ 不传数据,或数据为 `[]` 时,按配置的时区显示当前时间,每秒刷新。要固定显示某个时刻时,只使用第一条的 `time`。`time` 有值后组件停在该时间,不再每秒刷新:
160
+
161
+ ```json
162
+ [{ "time": 1704067200000 }]
163
+ ```
164
+
165
+ ```json
166
+ [{ "time": "2024-01-01 12:00:00" }]
167
+ ```
168
+
169
+ | 字段 | 含义 |
170
+ | --- | --- |
171
+ | `time` | 要固定显示的时间。毫秒时间戳,或用 `-`、`/`、`.`、空格、`:` 分隔的日期字符串。只取第一条 |
172
+
173
+ `time` 为空或解析失败时,仍按当前时间刷新。日期字符串写成 `2024-01-01 12:00:00`。带 `T` 的写法解析失败,会退回当前时间。`time` 为空时,渲染还会读第一条的 `string_date`,格式和字符串形式的 `time` 相同。停掉每秒刷新只看 `time` 是否有值:只写 `string_date` 时文字停住,到点回调仍按当前时间触发。
174
+
175
+ 时区和显示形式写在配置项里,用 `component fields nowV2 --keyword "<意图>"` 查。
176
+
177
+ - 「时区」默认 `北京`。写入短名,例如 `东九区`、`零时区`,不要写面板上的长标签。偏移以北京时间为基准。西五区到西八区、零时区、东一区在组件内置的夏令时区间内会再加 1 小时。
178
+ - 「显示形式」的存储值就是格式模板,默认 `YYYY-MM-DD HH:mm:ss`。只要时间用 `HH:mm:ss`,只要日期用 `YYYY-MM-DD`,中文星期用 `X`(如 `星期一`),英文星期全称用 `W`。`w` 是英文缩写,结果带句点,周二和周四前面还有一个空格,例如 `Mon.`、` Tues.`。
179
+
180
+ 文字样式在配置项「文字」里。阴影默认开启。对齐默认居中,存储值是 `flex-start`、`center`、`flex-end`。
181
+
182
+ 到点把时间戳写进变量时,在「回调参数」里加一行。「时间点」是 24 小时制的 `HH:mm:ss`,和当前时分秒完全一致时触发一次,写入的值是毫秒时间戳。「变量名」为空时使用 `_time0_` 这类内部名。组件挂载时会先把每个已配置的回调变量写成当时的时间戳,不等到时间点。数据里的 `time` 有值后每秒刷新停止,到点回调不再触发;挂载时的那一次仍会写入,用的是时区当前时间。
@@ -1,12 +1,14 @@
1
1
  ---
2
2
  name: easyv-screen-edit
3
- description: 修改已经搭好的 EasyV 大屏:改组件配置、批量改配置、配置交互事件、调整显隐和图层、升级组件版本。当用户要改大屏、改某个组件、加点击联动或调整布局时使用。
3
+ description: 修改已经搭好的 EasyV 大屏:添加组件、改组件配置、批量改配置、配置交互事件、调整显隐和图层、升级组件版本。当用户要改大屏、往已有大屏加组件、改某个组件、加点击联动或调整布局时使用。
4
4
  ---
5
5
 
6
6
  # 修改大屏
7
7
 
8
8
  先读再写。`easyv-screen screen document get <id> -o doc.json --json` 拿到当前文档和 `revision`。
9
9
 
10
+ 往大屏里新增组件时,先读 [component-selection.md](../easyv-screen-build/references/component-selection.md),再写 `addComponent`。
11
+
10
12
  ## 用原子操作做局部修改
11
13
 
12
14
  把操作写进 `ops.json`,格式 `{ "operations": [ ... ] }`,然后:
@@ -50,6 +52,7 @@ easyv-screen screen apply <id> -f ops.json --if-match <revision> --json
50
52
  `configPatches` 的 `path` 用 `easyv-screen component fields <module> --keyword "<意图>"` 查,例如
51
53
  `--keyword "图例"`、`--keyword "坐标轴 字号"`。返回的 `labelPath` 是中文标签链,按它判断字段含义,`path` 原样填进补丁。
52
54
  不传 `--keyword` 只看分组,再按分组名搜。不要猜路径:路径不存在时整批会被拒绝。
55
+ 子组件的字段同样用这条命令。先 `easyv-screen component children <module>` 确认子组件 module,再加 `--child`。
53
56
 
54
57
  优先用 `setComponentConfig` 和 `setComponentLayout`。`element.update` 的 `config` 是整棵属性树替换,
55
58
  只有确实要重写整棵树时才用,并且先从文档里取出当前 `config` 再改。
@@ -26,6 +26,7 @@ description: 使用 easyv-screen 命令操作 EasyV 大屏时的共用规则:
26
26
  - 写完跑 `screen validate`。有 `error` 先修再继续;`warn` 告知用户即可。
27
27
  - 发布、删除、上传组件会生效到用户的空间。执行前用一句话向用户确认。
28
28
  - 不要编造组件的配置字段。用 `component fields <module> --keyword` 查路径;用自己开发的组件时也可以对照 `main.json` 的 `configuration`。
29
+ - 不要编造子组件。用 `component children <module>` 列出父组件包里的子组件,再把返回的 `module` 传给 `component fields <module> --child <子组件>` 或 `component schema <module> --child <子组件>`。
29
30
 
30
31
  ## 退出码
31
32
 
@@ -0,0 +1,194 @@
1
+ ---
2
+ name: figma-asset-slice
3
+ description: 用于从 Figma 大屏设计稿中导出适配 EasyV 的可复用资产,整合切图与组装规律、Figma 导出限制、EasyV 组件补位及 Fable 5.2 产物中的可借鉴规则。
4
+ ---
5
+ # figma-asset-slice
6
+
7
+ 从可视化大屏 Figma 稿导出可复用资产。规则是通用的,不针对某一份稿。布局在运行时是绝对定位,切出来的应该是风格标本,不是一张烘死的整屏图。
8
+
9
+ ## 前提:不依赖稿面规范
10
+
11
+ 这些规则必须能在不规范的设计稿上执行。不要把「图层已命名、编组完整、尺寸整数对齐、结构清晰」当成前置条件。设计师产出通常层级混乱、图层不命名或错命名、一个 group 装不下该单元的全部元素。
12
+
13
+ 识别一律按画布上看到的内容、位置和视觉关系,不按图层名,不按是否在同一个 group 里。拿不准时在清单里写明判断,不要默默跳过。
14
+
15
+ ## 硬性规则
16
+
17
+ 1. **透明背景**。位图必须是带 alpha 的 PNG,禁止压到白底、灰底或页面背景上。正确的半透明壳在浅底上会发白,这是通道,不是切坏了;验证时要同时衬浅底和深底。
18
+ 2. **SVG 同样必须透明**。导出后若出现铺满画布的实色底板(Figma 常见为 `#F5F5F5` 或其他浅灰/白底 rect),必须去掉,只留字形本身。
19
+ 3. **背景模糊要去掉再导出**。若节点或任何子级有 Background Blur,在副本上移除再导出——Figma 会把当前背后的内容烘进 PNG。把半径记入清单,便于之后补毛玻璃。Layer Blur、Drop Shadow、Inner Shadow、外发光等图形自身的光效要保留。
20
+ 4. **动态文字不能出现在导出图里**。导出前隐藏副本上所有 TEXT,包括标题、标签、数值和单位。品牌 logo 里的字标是 logo 本身的一部分,跟 logo 一起保留。
21
+ 5. **只在画布外的空框里操作副本**。切完恢复隐藏的文字,删掉临时框和副本,不改原稿。
22
+ 6. **图层名和编组不可信**。按可见内容和空间聚类识别模块。同属固定完整视觉单元的字形与自身光效、壳和金角、徽标和条带等兄弟图层,先合组再导出;跨模块复用且需要独立定位的装饰按下文独立,不因分组不同就拆碎,也不一概合并。图表底座、平台、托盘仍按图表规则排除。
23
+
24
+ ## 格式与倍率
25
+
26
+ - **判定为图标的,只导出透明 SVG,不要再附一份 PNG。**
27
+ - 若字形里嵌了栅格图,保留 SVG 内嵌形式,仍不要另存 PNG;按下述规则处理内嵌位图体积,不把“包进 SVG”当成自动变为矢量。
28
+ - **其余位图默认 2x 透明 PNG**。不能为了透明退回 1x;要解决的是导出方法(隔离渲染、不压底),不是降低倍率。
29
+
30
+ ### SVG 内嵌位图的清晰度与体积
31
+
32
+ - 依据该资产的实际显示布局尺寸、内嵌图在其中的变换/占比,以及目标输出与合理放大时的清晰度需求,判断原位图像素是否明显过量。过量时在导出副本中合理降采样,不用原图像素大小直接决定 SVG 包体;不设脱离用途的统一像素或文件体积硬阈值。
33
+ - 只处理内嵌的栅格图,不将 SVG 中的矢量路径、矢量字标、渐变等内容栅格化。保留 SVG 的透明度、蒙版、裁切、变换及自身光效;图标仍为透明 SVG-only,其余位图仍默认 2x 透明 PNG,不能借优化之名改为正式图标 PNG 或降低其他位图的导出倍率。
34
+ - 在 manifest 的 `specialJudgments` 或 `notes` 中记录每个已处理内嵌图的原始/处理后像素尺寸、目标显示尺寸与清晰度依据、处理方式,以及优化前后体积;同时保留资产最终真实文件大小。没有降采样时记录保留原因,不为凑小包体牺牲清晰度或编造压缩结果。
35
+ - 按目标显示尺寸和所需清晰度复核处理前后外观,检查边缘、透明区域、蒙版和光晕;不清楚用途或无法可靠确认清晰度时先说明,不盲目降采样。
36
+
37
+ ## 图标盘点
38
+
39
+ 按整页穷尽收集独立字形,不限于大尺寸指标图标。列表行、图例旁、Tab、指标旁的小图标,以及组合模块标题上随实例变化的小图标,都要收。同一视觉只留一份,不要把同一图标内部的布尔碎片再切一次。打开 SVG 衬深色底检查:只能看到字形,不能有一整块浅灰或白底。
40
+
41
+ **先穷尽盘点独有内容,再对壳去重。** 模块外壳相同,不代表内部或旁边的图标、徽标、箭头、端饰等也相同。比较每个实例的可见内容和空间关系,不能因为已留一份壳就跳过整个实例。源清单中每个独有图标/装饰都要有去向:独立资产、包含它的组合资产,或按图表等现有规则排除的具体原因;不能借盘点之名把图表整体或其平台重新导出。重复内容只导出一份,但保留出现/引用节点、目标复用资产和位置/对齐关系;这些去向与引用可写入 `specialJudgments` / `notes`,并保留清单已有的覆盖/跳过记录。
42
+
43
+ ## Tab / 选项卡:先识别交互,再切页头与装饰
44
+
45
+ - **按视觉与用途识别,不靠图层名字或编组。** 观察并列选项、当前选中提示、导航/内容切换关系;在导出页面外框、header、标题或模块壳之前先盘点 Tab。即使选项嵌在一体的异形页头、与静态装饰同组,仍是可切换的交互单元,不能当成固定装饰整体烤死。
46
+ - **能由 EasyV 选项卡组件直接配置的普通样式不切图。** 对规整矩形、圆角及可通过现有组件配置实现的填充/描边/选中样式,记录组件补位、源节点、占位布局和可配置样式的判断依据,由组件呈现选项及状态。不能仅因图层名叫“矩形”就忽略实际复杂状态装饰,也不能把未切图的组件补位误报为漏项。
47
+ - **真正异形或组件不能直接配置的复杂状态装饰,按单项可替换背景切两态。** 去掉文字,分别导出真实的“默认状态”“选中状态”背景及该状态专属装饰;不导出一整组多个选项和当前高亮的烘死截图。状态专属斜角、描边、光效等随该状态资产走;独立图标仍按既有盘点与 SVG-only 规则处理,不顺便烤入 PNG。需输出的非图标状态位图仍为 2x 透明 PNG。
48
+ - **状态不是尺寸档,也不能被去重折叠。** 按同结构、同用途、同实际布局档位及端型,默认/选中每态各留一份真实标本;复用时记录来源与引用。左右不对称、首尾不同端型等确有视觉差异时保留相应变体,不镜像猜造;不能因为同尺寸就把两个状态去重成一份,也不能把“默认/选中”填写成布局档位。
49
+ - **两态使用统一的逻辑布局基准,光晕分别记 overflow。** 为可相互替换的两态确认同一按钮占位、锚点/基线和组装尺寸基准,分别测量实际导出尺寸与四边溢出;切换时按共同布局位置减去各态自己的 overflow 对齐,不因高亮外接框较大而挪动按钮或缩放裁掉光晕。若两态取自不同源实例,保留各自真实来源位置,在 `specialJudgments` / `notes` 中说明统一组装基准和对应偏移,不伪造源坐标。无法可靠确定共同基准时记录问题并沟通,不硬凑。
50
+ - **切页头/标题/壳时排除完整 Tab,但不挖掉真实共享结构。** 在副本中剥离 Tab 自有的整块底图、所有状态装饰与文字;不只隐藏文字而留下选中高亮,也不把始终存在的 Tab 自有底图误当作 header 共享底。真正静态共用的 header 结构留在 header,Tab 专属装饰跟状态走。按视觉归属而非矩形区域一刀抠除;若共用路径或边界模糊,指出具体范围、共享关系和疑问后沟通确认,其他可确定内容继续处理,不能随意挖掉共享底或无说明地把 Tab 烤入 header。
51
+ - **缺态不自行设计。** 原稿缺少某结构/档位/端型的一种状态时,记录已存在的真实状态、缺失的状态及来源范围,沟通确认;不靠改色、删光效、镜像等手段伪造另一态,也不以空白文件充数。未补齐前不能宣称两态齐全;预览脚本的资源校验通过,也不等于已完成 Tab 状态覆盖。
52
+ - **清单与预览明确标态。** 在 manifest 的 `specialJudgments` 或 `notes` 中记录导航/切换用途、默认/选中状态、来源、结构/端型与尺寸档位、互换/组装关系、统一布局基准及各态 overflow 对齐、重复引用、组件补位依据或缺态/边界疑问。资产的可见命名及说明要让 `index.html` 清楚区分状态;参考图不代替状态资产。无需出图的组件补位,以及缺态/边界疑问,可放入清单已有的跳过/覆盖判断记录并在其中用 `notes` 说明,不能伪造正式图片条目来凑数。沿用现有说明字段与已有记录即可在预览查看,不强制新 schema,不修改预览 helper,也不把状态当尺寸档。
53
+
54
+ ## 不要切的:图表
55
+
56
+ 有坐标轴、刻度、网格、数据系列(柱、线、面积、点、扇区、环形、仪表盘、进度条、数据条等)的区域判定为图表,不切图,到目标产品里用图表组件补位。
57
+
58
+ 看起来是图表底座、平台、托盘的装饰,也算图表的一部分,不要单独切。图例色块不切。
59
+
60
+ **贴在装饰模块上的图表同样不切。** 环形图、仪表盘、扇形、进度条等即使和这一组模块视觉上连在一起,也不要切进组合模块里。进度条要整条去掉,轨道和填充都不要留,留给组件补位。去掉这块图表之后,把剩下的装饰壳(行槽、侧沿、色标、异形卡壳、标题装饰等)按组合模块整段切。判断看画面结构,不看图层是否叫「图表」。
61
+
62
+ **不要因为卡片里有数字或进度条,就把整张内容卡当成图表跳过。** 自带异形外壳和标题装饰的内容卡(进度卡、内层指标卡等)按组合模块切。
63
+
64
+ ## 组合模块
65
+
66
+ 组合模块是去字、且不含图表的完整装饰单元。中间镶徽标的横条、带侧沿的多行槽、自带异形外壳和标题装饰的内容卡,都算。按画布上的视觉单元识别,不按是否在同一个 group 里。
67
+
68
+ - 导出前隐藏全部动态文字。
69
+ - 贴着的环形图、仪表盘、进度条等整块去掉,剩下的壳继续切。进度条不要只去填充、留下轨道。
70
+ - **固定一体的装饰默认合图**(如固定中心徽标、端饰、行色标、侧沿、标题栏斜切及固定造型槽托),作为完整视觉单元整段切,不把所有东西拆成碎片。若某装饰确实跨不同模块复用,并需要独立的位置/尺寸控制,则作为独立装饰资产导出,从相应壳副本中移除;记录来源、复用实例与相对布局/对齐关系。仅仅图层分组独立或在一张图里出现过,不足以作为拆分依据。标题内纹理仍随标题保留,不另切 tile。
71
+ - 可变位数的数字/字母槽不因与壳同组就固定烤入整排,按「数字 / 字母槽」处理;有依据的固定完整造型例外也须记录。图表、进度条及其平台排除规则优先,不能把它们改称“复用装饰”保留。
72
+ - 随实例变化的标题小图标,以及多处复用的趋势箭头,单独出透明 SVG,不要烤进壳里;不随数据位数变化的固定装饰槽托可以留,但图表底座/平台不能留。
73
+ - 同一结构按布局档位分套,每一档一份标本。某一档在稿里没有实例,就不要空造。
74
+ - Tab 不按静态固定一体装饰合入壳;先按「Tab / 选项卡」规则剥离交互区域,再判断剩余固定结构的合图。Tab 默认/选中是独立的状态维度,不因同结构同尺寸档位而互相去重。
75
+
76
+ ### 数字 / 字母槽:先分用途,再分尺寸档
77
+
78
+ - 先按源稿实际用途区分数字槽、字母/评级槽等语义与造型变体,再在同用途、同结构内归布局尺寸档。不能仅凭宽高把字母槽当成数字槽的放大档,也不能靠名字叫“数字牌”就合并不同用途。
79
+ - 位数随数据变化时,以去字后的**单格**为重复单元,提供相应数字/字母变体及拼装规则,不按某次示例数据的字符数烤死整排。manifest 的 `specialJudgments` 或 `notes` 中写明单格资产、适用字符/用途、实测尺寸与档位、横向/纵向间距、起点/对齐和字符变化时的重复排列方式;单位、数值等动态文字仍由目标组件承载,不烤图。
80
+ - 只有造型和排列本身确为固定完整装饰单元,且有源稿结构和复用用途的明确依据,才保留整组例外;不能仅因当前数据恰好有固定几位就当成固定造型。记录例外依据、固定范围和装配方式,避免与单格方案重复叠加。
81
+
82
+ ### 整壳与独立标题:明确互斥的替代装配方案
83
+
84
+ - 整壳已经包含标题装饰时,不得再把同一独立标题叠上去。如果同时提供整壳与独立标题,必须明确是**替代方案**而不是让使用方猜:整壳方案使用已含标题的壳;拆分方案必须使用实际存在的去标题空壳与匹配标题资产。没有去标题空壳,就不能宣称该整壳可同时作为拆分方案的底图。
85
+ - 在 manifest 的 `specialJudgments` 或 `notes` 中列明涉及的资产文件、包含/替代关系、各方案应同用和不可同用的项、相对布局与含 overflow 的对齐方式、可复用实例及对应真实布局档位。已有其他关系字段可保留,不强制新增预览脚本不认识的 schema;关键说明必须在这些明确可显示字段中可见。
86
+ - 各方案仍按实际存在的布局档位选择标本,不通过拉伸或九宫格把异形标题/壳变成另一档;没有证据的档位或去标题资产不空造。不为“提供更多选择”重复烤入相同装饰而不交代装配关系。
87
+
88
+ ## 不要另切:已烘进其他资产的纹理
89
+
90
+ 只出现在标题栏、模块壳等已经要导出的资产里面的点阵、纹理、底纹,不要再把原始 tile 单独切一份。它已经跟那个标题或壳一起被切走了。
91
+
92
+ 只有这块纹理会被独立平铺、且还没被任何已切资产包进去时,才保留原始 tile。
93
+
94
+ ## 页面大背景
95
+
96
+ 大背景 = 把画布上所有前景内容去掉之后剩下的东西:模块、标题、图表、文字、图标、页面外框(左右栏、底栏、页头装饰)都算前景。
97
+
98
+ 不要只切名为「背景」的图层。背景常常分散在多个未命名或错命名的层里(大面积色块、渐变、光斑、网格、底纹等)。按视觉从画板底层往上收集这些层,在副本上隐藏全部前景后导出一张「页面背景」(默认 2x)。漏切或误把前景烘进去都不行。
99
+
100
+ ## 泛光与对齐
101
+
102
+ 投影、外发光、图层模糊会撑大视觉外接矩形,导出尺寸可能大于设计稿上的布局框。
103
+
104
+ - **保留光晕**,按视觉外接矩形导出,不要为了对尺寸把光效裁掉。
105
+ - 清单里必须同时记:设计稿布局框 `(x, y, width, height)`,导出画布尺寸,以及四边溢出 `overflow.left / top / right / bottom`(布局单位,不受导出倍率影响)。
106
+ - 上传到绝对定位画布时:`left = layout.x - overflow.left`,`top = layout.y - overflow.top`;贴图宽高用导出画布尺寸(若是 2x,再按倍率折算回布局单位)。
107
+ - 没有溢出时,四边记 `0`,不要省略这三组数据。
108
+
109
+ ## 异形标题 / 模块壳的多尺寸
110
+
111
+ 结构看起来一样、但跨了不同布局档位的标题装饰或模块背景,因为常是异形(斜切、端饰、不等比装饰),不能靠拉伸或九宫格变成另一档,必须按档各出一份。
112
+
113
+ 按布局倍数分档,不要用固定像素差去切:
114
+
115
+ 1. 先按用途与结构分族(尤其数字槽与字母/评级槽不能混为一族),并确认整壳/独立标题的装配方案,再在画布上找到该族最小的那一档,作为 **1x 基准**。看可见的模块宽度(高度若在变则看高度),以及模块之间的间距;不要依赖名为「布局」的图层是否存在。
116
+ 2. 预设档位:**1x、1.5x、2x**。若还有明显更大的,按同样节奏继续加 2.5x、3x。
117
+ 3. **2x 的预期尺寸通常是「两个 1x 加上中间那条模块间距」**,不是 1x 的精确两倍。1.5x 按「一档半」去靠,同样要把间距算进去,不要用精确乘法去卡。
118
+ 4. 把每个实例归到最近的一档:落在两档中点及以内算当前档,超过中点进下一档。档内的小数、几个像素偏差、以及「2x 并不等于 1x×2」这类误差,都还算同一档,只留一份标本。
119
+ 5. 同一结构每一档出一份;清单里注明该标本的布局档位(1x / 1.5x / 2x …)和实测宽高。某一档在稿里没有实例,就不要空造。
120
+
121
+ 这里的 1x / 2x 是布局档位,和位图默认按 2 倍分辨率导出不是一回事。
122
+
123
+ ## 品牌 logo 与页面外框
124
+
125
+ 品牌 logo(徽标、字标,或两者组合在一起的那一块)始终单独作为品牌资产切出来。
126
+
127
+ - **切底栏、侧栏等页面外框时,要把 logo 藏掉,不要烘进外框图里。** 外框只留装饰条、端饰、分割线这些边框专属部分。
128
+ - **logo 只出画布上看到的那一份:** 颜色、蒙版、裁切都以画布呈现为准。不要再切一份未蒙版、未着色的源图——源图常常是另一套颜色,在稿上并不是最终样子。
129
+ - 同一视觉只留一份。
130
+ - **先识别 Tab,再切 header / 页头外框。** 即使 Tab 位于异形页头结构内,也要在副本中剥离其整块自有底图、状态装饰和文字,不能只去字留选中高亮;真正静态共享的 header 结构仍保留。Tab 专属装饰随状态导出,普通组件可配置的样式记录组件补位。边界不清时指出疑问并沟通,不随意挖掉共享底,详见 Tab 专节。
131
+
132
+ ## 切图类型
133
+
134
+ | 类型 | 切什么 | 说明 |
135
+ | --- | --- | --- |
136
+ | 页面背景 | 去掉全部前景后剩下的画布底 | 按视觉收集,不按图层名。 |
137
+ | 模块背景 | 空的模块 / 卡片外壳 | 固定一体的兄弟金角一起切;跨模块复用且需独立定位的装饰见组合模块规则。去掉背景模糊。按 1x / 1.5x / 2x 布局档位,每档各出一份。 |
138
+ | 大标题 | 页头装饰,不带字 | 常有泛光,必须记溢出。按布局档位,每档各出一份。 |
139
+ | 一级标题 | 面板标题栏装饰,不带字 | 含角标、端饰。按布局档位,每档各出一份。栏内纹理跟标题一起切,不另存 tile。 |
140
+ | 二级标题 / 三级标题 | 标题装饰,不带字 | 只切装饰。按布局档位,每档各出一份。 |
141
+ | Tab / 选项卡 | 按视觉识别的单项可替换状态背景,不含文字 | 普通矩形/圆角及组件可直接配置的样式不切,记录 EasyV 选项卡补位;真正异形/复杂状态装饰默认、选中各出一份,保留真实端型差异,缺态不造。两态统一布局基准、各记 overflow;先从 header/标题/壳剥离完整 Tab,自有装饰跟状态,真实共享结构仍保留。 |
142
+ | 组合模块 | 去字、且不含图表的完整装饰单元 | 固定一体装饰默认整段切;跨模块复用且需独立定位的装饰按规则独立,其他不碎拆。贴着的环形图、仪表盘、进度条等整块除掉,留下的壳继续切。随实例变化的标题图标、复用趋势单独出 SVG。可变数字槽按单格及拼装规则;整壳/独立标题同时提供时写明互斥装配方案。 |
143
+ | 图标整体 | 固定一体的图标 + 自身光晕 / 非图表平台的装饰,作为一个单元 | 独特字形和自身装饰可能是兄弟层,按视觉合组;图表底座、平台、托盘仍排除。只出透明 SVG,内嵌位图按用途控制体积。 |
144
+ | 图标 | 独立小字形 | 只出透明 SVG。壳去重前穷尽盘点独有图标;保留去向与重复引用,不把壳相同当成内容相同。 |
145
+ | 页面外框 | 左右边框、底栏等画布边框 | 按完整视觉单元整图切,不要拆成角标、花饰、分割线。**不包含 logo。** 左右镜像可只出一份并注明可翻转。 |
146
+ | 品牌 logo | 画布上呈现的 logo | 只出看到的那份,不另出源图。 |
147
+ | 装饰背景 | 独立平铺贴图等 | 仅当该纹理会被独立平铺、且未被其他已切资产包含时才保留原始 tile。图表底座不算此类。已烘进标题或模块壳的纹理不另切。 |
148
+
149
+ ## 导出步骤
150
+
151
+ 1. 先按整帧盘点,按可见内容而不是图层名:页面大背景、模块壳(按 1x / 1.5x / 2x 布局档位)、各级标题装饰(同样按档)、组合模块(含自带异形壳的内容卡;去掉贴着的图表和进度条)、全部独立图标(含组合模块标题上随实例变化的小图标)、页面外框(不含 logo)、画布上的 logo、其余确实独立的非图表装饰。先逐实例盘点独有图标/装饰,记录其去向与重复引用,再对填充、描边、装饰和布局档位均相同的壳/资产去重;不能跳过仍含独有内容的整个模块。先按用途分清数字/字母槽,再分档。跳过图表及其底座、平台、托盘、进度条整条,以及已被标题或壳包含的纹理 tile。 在页头、标题和壳切图之前,先按视觉与导航/切换用途识别 Tab,不以层名或分组为前置;区分组件可配置样式与需切的复杂状态背景,盘点默认/选中及端型变体。Tab 底图、状态装饰和文字也属于页面背景导出时须去掉的前景。
152
+ 2. 在画布外建一个无填充、`clipsContent: false` 的临时框,把目标克隆进去。
153
+ 3. 隐藏所有 TEXT(logo 字标除外);去掉 BACKGROUND_BLUR;隐藏贴在组合模块上的图表和进度条(轨道与填充整条去掉)。固定一体装饰按视觉合组;跨模块复用且需独立定位的装饰、随实例变化的标题图标及复用趋势,从壳副本移除后另出。可变位数槽取去字单格并记录拼装;固定整组例外须有依据。确认整壳/独立标题的互斥替代方案,避免把同一标题重复烤入待叠加的两张图。切外框时隐藏 logo。 对 Tab,不只去文字:从 header/标题/壳副本中排除完整自有底图及状态装饰,保留真实静态共享结构;复杂 Tab 单项分别提取真实默认/选中状态,普通可配置样式留给选项卡组件。归属边界不明或缺态时记录问题并沟通,不随意拆共享底或补造状态。
154
+ 4. 记录每个目标的布局框,以及视觉外接矩形相对布局框的四边溢出;在 `specialJudgments` / `notes` 中记录独有项去向、重复引用、独立装饰的位置/对齐、单格用途与间距/拼装、固定整组例外依据,以及整壳/标题的包含和互斥替代关系。 Tab 另外在这些说明字段中写明用途、状态、真实来源、结构/端型/档位、统一组装基准及各态 overflow、互换/复用关系、组件补位或缺态疑问;不改为强制新 schema。
155
+ 5. 图标只出透明 SVG(去掉导出器加的实色底板);内嵌位图按显示尺寸和清晰度合理降采样并记录原/后尺寸、体积与处理依据,不栅格化矢量内容。其余走隔离透明渲染的 2x PNG。页面背景在隐藏全部前景后导出。禁止把图层压到页面背景或灰底上再导出。
156
+ 6. 校验:位图 alpha 不能全部是 255;标题和组合模块里不能出现动态文案,也不能夹进图表或进度条;外框里不能出现 logo;SVG 打开后没有整块浅底;清单里布局框、导出尺寸、溢出三项齐全;同用途同结构在稿里出现过的布局档位都有标本。逐个核对独有图标/装饰有去向、重复实例有复用引用;拆分后不漏固定一体装饰,同一装配方案内不重复烤入/叠用相同的独立装饰;互斥方案按记录选择。检查数字/字母槽分类、可变位数拼装与间距,固定整组例外依据;检查整壳/标题各方案可实际组装、互斥项不叠加、异形不被跨档拉伸;检查 SVG 内嵌位图处理前后清晰度/透明度/光效和真实文件体积记录。 Tab 另验收:header/标题/壳内无残留 Tab 自有底图或选中高亮,真实共享底未误删;复杂状态背景单项去字、默认/选中覆盖及端型变体有据,同档状态未被去重;两态按共同基准和各自 overflow 对齐不跳动;组件补位/缺态/边界问题有说明。index.html 中状态标记清楚,缺态不能宣称齐全。
157
+ 7. 删掉临时框,确认原稿未被改。
158
+
159
+ ## 切完之后
160
+
161
+ - 清单里记录:类型、来源节点、格式与导出倍率、布局框、导出尺寸、四边溢出、去掉的背景模糊半径;多尺寸标本注明布局档位(1x / 1.5x / 2x …)和该档宽高。这份清单是给后续对齐和组装用的机器可读记录,不是要上传的素材本身。
162
+ - 独有项去向与重复引用、独立装饰的关系/对齐/复用、单格用途/间距/拼装及固定整组例外、整壳与标题的互斥替代方案、内嵌位图的尺寸/清晰度依据/处理与前后体积,写入清单中明确可展示的 `specialJudgments` 或 `notes`。不要求改预览脚本或强制引入新 schema;不得只有生成者脑中知道的装配约定。
163
+ - 图表区域和进度条留给图表组件,不要用切图去贴。
164
+ - Tab 的用途/状态/来源/尺寸档位、组装对齐与引用、组件补位及其依据、缺态/边界疑问,同样写入 `specialJudgments` / `notes` 并在固定 index.html 预览中可查看。状态不可代替布局档位;资源校验通过不替代人工核对状态齐全与切换对齐。
165
+
166
+ ## 固定交付与离线切图预览(每次必做)
167
+
168
+ 每次切图必须在**本次正式导出目录**同时交付 `index.html`、`manifest.json`、`README.md`;不能用聊天里的几张截图、临时自主编写的页面或仅提供文件列表替代。预览采用本技能固定脚本 `scripts/build_preview.py`,不得每次依赖模型重新发挥实现。
169
+
170
+ ### 固定执行步骤
171
+
172
+ 本节接在「导出步骤」的源稿恢复确认之后执行:
173
+
174
+ 1. 完成本次 `manifest.json`、`README.md` 和全部正式素材。清单必须逐项登记真实文件路径、类型、源节点、布局框、实际导出尺寸、格式与导出倍率、布局档位、四边溢出、移除的背景模糊记录及特殊说明;不适用/无值应有明确记录(如 `layoutTier: "not-applicable"`、空说明或空模糊数组),不能为了通过校验编造字段。`counts.total` 应与逐项记录一致;PNG/SVG及分类统计如已记录也必须一致。没有跳过项时显式记录 `skipped: []`,否则保留跳过/去重及其原因。
175
+ 2. 使用 **Skill 返回的本技能目录** 中的脚本,不调用来源不明的项目脚本。设置以下变量后运行:
176
+
177
+ ```bash
178
+ SKILL_DIR="<当前 Skill 返回的技能目录>"
179
+ EXPORT_DIR="<本次正式导出目录的绝对路径>"
180
+ python3 "$SKILL_DIR/scripts/build_preview.py" "$EXPORT_DIR"
181
+ ```
182
+
183
+ 脚本只依赖 Python 3 标准库,只读取清单与素材,写入该导出目录的 `index.html` 和 `preview-validation.json`,不改素材、清单或README,不生成图标PNG。不要对历史导出目录运行以免改写它的预览;回归测试使用复制的清单/README及只读素材副本或软链接。
184
+ 3. 原稿参考图可选。有时仅需切图目录,不必强行添加原稿截图。若已具备参考图,放在本次导出目录内,使用 `--reference "refs/source-reference.png"`(可重复),或在清单 `referenceImages` 中显式登记 `{ "file": "refs/source-reference.png", "label": "原稿参考" }`。必须标为参考、不计正式资产,不能靠猜文件名把未登记的素材排除出统计。
185
+ 4. 检查脚本退出码及 `preview-validation.json`。**退出0仅表示资源/元数据机械校验通过,不代表切法及画面已经验收。** 缺资源、重复记录、未登记图片、尺寸/格式/hash/统计不一致、未知schema或必需metadata缺失时,脚本返回非0,并生成显著标红的诊断页;不得以“生成了HTML”为由宣布完成,不能静默省略错误记录,也不能自动补造旧清单字段。先核实并补全本次清单/导出,再重跑。
186
+ 5. 用浏览器直接双击本次 `index.html`,离线验收:正式卡片数与清单一致;分类和搜索可用;深色/浅色/棋盘底切换有效;缩略图保持比例;点击可放大并打开原图;所有图片加载成功;可查看文件名、类型、实际像素或SVG视口、布局尺寸、格式/倍率、布局档位、四边溢出、真实体积、源节点及特殊说明;跳过/去重判断与参考图区分清楚。没有浏览器测试条件时如实记录“未做浏览器交互/视觉验收”,不能声称已验证这些UI。
187
+
188
+ ### 预览约束与固定验收
189
+
190
+ - 页面必须可本地离线打开:内置CSS/JS,不使用CDN,不通过 `fetch` 读取manifest,不依赖服务器。素材图片用相对路径;有真实fileKey/nodeId才生成Figma源链接(只有主动点击才访问Figma),不能伪造外部服务或大屏工程。
191
+ - 深浅/棋盘衬底、缩略显示及放大都**仅作用于预览**,不得烤入素材;不输出图标的正式PNG伴随文件。原稿参考图不计正式资产。
192
+ - 支持当前清单的 `type/sourceNodeIds/backgroundBlurRemoved/specialJudgments` 及旧版 `kind/sourceNode/blurRemoved/notes` 等明确别名;对无法识别的schema明示失败,不静默少图。缺失metadata在卡片上明确标记“未记录”,不按文件名、颜色或像素大小猜测。
193
+ - 固定验收顺序是:脚本返回0 → 核对文件/统计/错误报告 → 离线浏览器逐项检查 → 原有透明度、动态内容剥离、切法、覆盖与源稿恢复等验收。预览脚本不代替原有切图规则和人工判断。
194
+ - 发布/维护本技能时,`scripts/build_preview.py` 必须与本节一起交付到技能目录。缺脚本、缺必交文件、清单缺字段或预览缺图,均不能视为本次切图完成。