@easyv/screen-cli 0.1.2 → 0.1.3

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
 
@@ -139,7 +139,7 @@ info:
139
139
 
140
140
  1. `GET /meta` 看 `context` 和 `limits`
141
141
  2. `GET /groups` 取 `groupId`,`POST /screens` 创建空白大屏
142
- 3. `GET /components` 选组件,`GET /components/{module}/config-fields?keyword=...` 按意图查要改的字段
142
+ 3. `GET /components/official` 选官方组件(已发布,不含定制组件)。没有合适的再 `GET /components/space` 查当前空间已发布的自定义组件。父组件包里的子组件用 `GET /components/{module}/children` 列出,再把返回的 `module` 传给 `schema` / `config-fields` 的 `child`。`GET /components/{module}/config-fields?keyword=...` 按意图查要改的字段
143
143
  4. 需要图片时 `POST /assets`,把返回的 `path` 写进组件 `config`
144
144
  5. `GET /screens/{screenId}/document` 拿基线文档和 `revision`
145
145
  6. 改完后 `POST /screens/{screenId}/validate` 预检(不落库)
@@ -770,6 +770,12 @@ paths:
770
770
  required: false
771
771
  description: 为 `true` 时忽略缓存,重新解析组件包。默认 `false`。
772
772
  schema: {type: boolean, default: false}
773
+ - name: child
774
+ in: query
775
+ required: false
776
+ description: 只返回这个子组件。取值是 `GET /components/{module}/children` 返回的 `children[].module`。不传则只返回父组件自己的配置,不包含子组件。
777
+ schema: {type: string, maxLength: 64, pattern: '^[A-Za-z][\\w]*$'}
778
+ example: VectorScatterLayer
773
779
  responses:
774
780
  '200':
775
781
  description: 组件配置结构
@@ -796,6 +802,68 @@ paths:
796
802
  '400': {$ref: '#/components/responses/BadRequest'}
797
803
  '401': {$ref: '#/components/responses/Unauthorized'}
798
804
  '403': {$ref: '#/components/responses/Forbidden'}
805
+ '404':
806
+ description: |
807
+ `COMPONENT_NOT_FOUND`:组件不存在,或该版本不可用。
808
+ `COMPONENT_CHILD_NOT_FOUND`:父组件存在,但 `child` 不是它的子组件。
809
+ content:
810
+ application/json:
811
+ schema: {$ref: '#/components/schemas/Error'}
812
+ '422':
813
+ description: '`COMPONENT_SCHEMA_UNAVAILABLE`:组件包里提取不出配置结构。'
814
+ content:
815
+ application/json:
816
+ schema: {$ref: '#/components/schemas/Error'}
817
+
818
+ /components/{module}/children:
819
+ get:
820
+ operationId: listComponentChildren
821
+ tags: [组件]
822
+ summary: 列出组件包里的子组件
823
+ description: |
824
+ 从父组件包的 `getDefaultChildrenConfig()` 静态提取子组件清单,不执行组件代码。
825
+
826
+ - 子组件不是独立发布的 module。查某一层的配置或数据字段时,把这里的 `children[].module` 传给 `schema` / `config-fields` 的 `child`
827
+ - `children[].id` 是模板 id。给这一层灌数据时,数据的 `id` 要和它相同
828
+ - 没有子组件时 `children` 为空数组,不报错
829
+ - `version` 不传时用该组件当前发布版本
830
+ - 与 `schema` 共用 24 小时缓存;`refresh=true` 强制重新解析
831
+ x-easyv-status: beta
832
+ x-easyv-scope: component:read
833
+ parameters:
834
+ - name: module
835
+ in: path
836
+ required: true
837
+ description: 父组件模块名。
838
+ schema: {type: string}
839
+ example: basicPlaneMap
840
+ - name: version
841
+ in: query
842
+ required: false
843
+ description: 语义化版本,至少 `主.次.修订` 三段数字。不传则取当前发布版本。
844
+ schema: {type: string, pattern: '^\\d+\\.\\d+\\.\\d+'}
845
+ - name: refresh
846
+ in: query
847
+ required: false
848
+ description: 为 `true` 时忽略缓存,重新解析组件包。默认 `false`。
849
+ schema: {type: boolean, default: false}
850
+ responses:
851
+ '200':
852
+ description: 子组件清单
853
+ content:
854
+ application/json:
855
+ schema: {$ref: '#/components/schemas/ComponentChildren'}
856
+ example:
857
+ module: basicPlaneMap
858
+ version: 1.8.0
859
+ children:
860
+ - module: VectorScatterLayer
861
+ id: scatter-1
862
+ name: 矢量散点
863
+ version: 1.0.0
864
+ '400': {$ref: '#/components/responses/BadRequest'}
865
+ '401': {$ref: '#/components/responses/Unauthorized'}
866
+ '403': {$ref: '#/components/responses/Forbidden'}
799
867
  '404':
800
868
  description: '`COMPONENT_NOT_FOUND`:组件不存在,或该版本不可用。'
801
869
  content:
@@ -818,6 +886,7 @@ paths:
818
886
  - 关键词按中文标签链(`labelPath`,如 `['图例', '宽度']`)和路径匹配,空格分隔的多个词需要同时命中
819
887
  - 不传 `keyword` 时 `fields` 为空,只返回 `groups` 分组概览,用来决定下一步搜什么
820
888
  - 字段来自静态解析,`strict: false` 时清单不完整
889
+ - `child` 只查父组件包里的一个子组件。不传时只查父组件自己的字段,不会把子组件配置一起返回
821
890
  x-easyv-status: beta
822
891
  x-easyv-scope: component:read
823
892
  parameters:
@@ -836,6 +905,12 @@ paths:
836
905
  required: false
837
906
  schema: {type: string, maxLength: 100}
838
907
  example: 图例 宽度
908
+ - name: child
909
+ in: query
910
+ required: false
911
+ description: 只查这个子组件的配置。取值是 `GET /components/{module}/children` 返回的 `children[].module`。不传则只查父组件自己的字段。
912
+ schema: {type: string, maxLength: 64, pattern: '^[A-Za-z][\\w]*$'}
913
+ example: VectorScatterLayer
839
914
  - name: limit
840
915
  in: query
841
916
  required: false
@@ -850,6 +925,7 @@ paths:
850
925
  required: [module, version, strict, total, groups, fields]
851
926
  properties:
852
927
  module: {type: string}
928
+ child: {type: string, description: 请求带 `child` 时回显被选中的子组件 module_name。不带则省略。}
853
929
  version: {type: string}
854
930
  strict: {type: boolean, description: 字段是否完整提取。}
855
931
  total: {type: integer, description: 命中总数;不传关键词时是字段总数。}
@@ -882,7 +958,9 @@ paths:
882
958
  '401': {$ref: '#/components/responses/Unauthorized'}
883
959
  '403': {$ref: '#/components/responses/Forbidden'}
884
960
  '404':
885
- description: '`COMPONENT_NOT_FOUND`'
961
+ description: |
962
+ `COMPONENT_NOT_FOUND`:组件不存在,或该版本不可用。
963
+ `COMPONENT_CHILD_NOT_FOUND`:父组件存在,但 `child` 不是它的子组件。
886
964
  content:
887
965
  application/json:
888
966
  schema: {$ref: '#/components/schemas/Error'}
@@ -892,12 +970,14 @@ paths:
892
970
  application/json:
893
971
  schema: {$ref: '#/components/schemas/Error'}
894
972
 
895
- /components:
973
+ /components/official:
896
974
  get:
897
- operationId: listComponents
975
+ operationId: listOfficialComponents
898
976
  tags: [组件]
899
- summary: 组件目录
900
- description: 官方组件与当前空间的私有组件,含最新版本和发布状态。用于选择组件或检查重名。
977
+ summary: 官方组件目录
978
+ description: |
979
+ EasyV 官方提供的组件,用于选型。只返回已发布组件(`isShow = true`),不含定制组件。
980
+ 官方组件没有合适的,再查 `GET /components/space`。
901
981
  x-easyv-status: available
902
982
  x-easyv-scope: component:read
903
983
  parameters:
@@ -907,7 +987,7 @@ paths:
907
987
  description: 按名称或 module 过滤。
908
988
  responses:
909
989
  '200':
910
- description: 组件列表。
990
+ description: 已发布的官方组件。
911
991
  content:
912
992
  application/json:
913
993
  schema:
@@ -919,6 +999,38 @@ paths:
919
999
  items: {$ref: '#/components/schemas/ComponentCatalogItem'}
920
1000
  '401': {$ref: '#/components/responses/Unauthorized'}
921
1001
  '403': {$ref: '#/components/responses/Forbidden'}
1002
+
1003
+ /components/space:
1004
+ get:
1005
+ operationId: listSpaceComponents
1006
+ tags: [组件]
1007
+ summary: 空间组件目录
1008
+ description: |
1009
+ 当前空间自己开发并已发布的组件。只在官方组件没有合适的时候查询。
1010
+ 未发布的空间组件不在此列。
1011
+ x-easyv-status: available
1012
+ x-easyv-scope: component:read
1013
+ parameters:
1014
+ - name: keyword
1015
+ in: query
1016
+ schema: {type: string}
1017
+ description: 按名称或 module 过滤。
1018
+ responses:
1019
+ '200':
1020
+ description: 当前空间已发布的自定义组件。
1021
+ content:
1022
+ application/json:
1023
+ schema:
1024
+ type: object
1025
+ required: [components]
1026
+ properties:
1027
+ components:
1028
+ type: array
1029
+ items: {$ref: '#/components/schemas/ComponentCatalogItem'}
1030
+ '401': {$ref: '#/components/responses/Unauthorized'}
1031
+ '403': {$ref: '#/components/responses/Forbidden'}
1032
+
1033
+ /components:
922
1034
  post:
923
1035
  operationId: publishComponent
924
1036
  tags: [组件]
@@ -2645,11 +2757,42 @@ components:
2645
2757
  value: {type: string, description: 字段映射值。}
2646
2758
  desc: {type: string, description: 字段说明。}
2647
2759
 
2760
+ ComponentChild:
2761
+ type: object
2762
+ required: [module]
2763
+ description: 父组件包里的一个子组件。不含配置树。
2764
+ properties:
2765
+ module:
2766
+ type: string
2767
+ description: 子组件的 `base.module_name`。传给 `schema` / `config-fields` 的 `child`。
2768
+ id:
2769
+ type: string
2770
+ description: 模板 id。给这一层灌数据时,数据的 `id` 要和它相同。没有则省略。
2771
+ name:
2772
+ type: string
2773
+ description: 显示名,来自 `base.name`。没有则省略。
2774
+ version:
2775
+ type: string
2776
+ description: 子组件版本,来自 `base.version`。没有则省略。
2777
+
2778
+ ComponentChildren:
2779
+ type: object
2780
+ required: [module, version, children]
2781
+ description: 父组件包里的子组件清单。
2782
+ properties:
2783
+ module: {type: string, description: 父组件模块名。}
2784
+ version: {type: string, description: 实际解析的父组件版本。}
2785
+ children:
2786
+ type: array
2787
+ description: 按组件包中的顺序排列。没有子组件时为空数组。
2788
+ items: {$ref: '#/components/schemas/ComponentChild'}
2789
+
2648
2790
  ComponentSchema:
2649
2791
  type: object
2650
2792
  required: [module, version, source, strict, fields, dataFields, triggers, actions, requiresPreset, unsupported, cached, stats]
2651
2793
  properties:
2652
2794
  module: {type: string, description: 请求的组件模块名。}
2795
+ child: {type: string, description: 请求带 `child` 时回显被选中的子组件 module_name。不带则省略。}
2653
2796
  version: {type: string, description: 实际解析的版本。}
2654
2797
  source:
2655
2798
  type: string
@@ -2756,7 +2899,7 @@ components:
2756
2899
  category: {type: string, description: 分类。空间组件固定为「空间组件」。}
2757
2900
  thumb: {type: string, description: 缩略图路径,原样返回数据库里的值。没有时省略。}
2758
2901
  source: {type: string, enum: [platform, space], description: platform 官方组件,space 空间私有组件。}
2759
- status: {type: string, enum: [published, unpublished], description: 发布状态。官方组件恒为 published。}
2902
+ status: {type: string, enum: [published], description: 列表只返回已发布组件,因此恒为 published。}
2760
2903
 
2761
2904
  PublishedComponent:
2762
2905
  type: object