@easyv/screen-cli 0.0.0-stage → 0.1.0

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.
@@ -0,0 +1,50 @@
1
+ ---
2
+ name: easyv-component-dev
3
+ description: 从零开发一个 EasyV 组件并上传到平台。按组件规范定义配置项、静态数据、触发事件和接收的动作,打包签名后发布,然后在大屏里使用。当没有合适的现成组件、或需要定制可视化时使用。
4
+ ---
5
+
6
+ # 从零开发 EasyV 组件
7
+
8
+ 组件是 React 组件。配置项、事件和动作都声明在 `config/main.json`,平台据此渲染配置面板和交互选项。
9
+ 完整字段说明见 [component-spec.md](references/component-spec.md)。
10
+
11
+ ## 流程
12
+
13
+ 1. `easyv-screen component init` 在当前目录准备工程 `./easyv-components`(已存在则复用)。
14
+ 2. `easyv-screen component create <名称> --title "<显示名>"` 生成骨架。module 自动加 `ai_` 前缀,
15
+ 例如 `kpi-card` 变成 `ai_kpi_card`,避免和平台组件重名。
16
+ 3. 编辑三个文件:
17
+ - `config/main.json`:`configuration` 写配置项,`triggers` 写组件能触发的事件,`actions` 写组件能接收的动作。
18
+ - `config/main.data.json`:默认静态数据和字段说明。
19
+ - `index.jsx`:用 `props` 里的 `configuration`、`data` 渲染;触发事件调用 `emit('<trigger>', data)`。
20
+ 4. 按下面的「easyv-cli」准备打包工具和签名密钥。没装好、密钥没配好就不要执行打包。
21
+ 5. `easyv-screen component publish <目录名>`。它会打包、签名并上传;如果平台已有同名组件且版本不比本地高,
22
+ 会自动把补丁号加一后重新打包再上传。
23
+ 6. 上传结果里 `status` 为 `published` 就可以用了。在大屏文档里用返回的 `module` 和 `version` 引用它。
24
+
25
+ ## easyv-cli
26
+
27
+ 打包签名依赖全局命令 `easyv`,npm 包名是 `@easyv/cli`。
28
+
29
+ 1. 先执行 `command -v easyv`。没有这个命令就执行 `npm install -g @easyv/cli`,装完再确认 `easyv` 能运行。已经安装就不要重装。
30
+ 2. 用 `easyv config get accessid` 和 `easyv config get secretkey` 检查密钥。两个都有值才算配好。缺任何一个就停下来,把下面的复制位置告诉用户,等用户把两段值发过来。不要编造密钥,不要替用户点「重置」。
31
+ 3. 拿到值之后写入,不要再把 Secret 打印出来:
32
+ - `easyv config set accessid <Accesskey ID>`
33
+ - `easyv config set secretkey <Accesskey Secret>`
34
+
35
+ 密钥保存在用户主目录的 `.easyvrc`。`easyv pack` 在缺少密钥时会进入交互式提问,不要走交互输入,用上面的 `config set` 写入。
36
+
37
+ 复制位置:登录当前要发布到的工作台,从右上角应用菜单进入「开放平台」,打开「组件开发」(地址是 `/development/componentDev`)。页面右上角点「获取Accesskey」。弹窗里的 **Accesskey ID** 就是 Access ID;**Accesskey Secret** 默认是星号,先点「显示」,再点旁边的「复制」,这就是 Secret Key。
38
+
39
+ ## 约定
40
+
41
+ - 只做 React 组件。
42
+ - 配置项的 `name` 要用有意义的英文,渲染时通过 `configuration.<name>` 取值,和声明保持一致。
43
+ - `triggers` 里的 `value` 就是 `emit` 的第一个参数,两者必须一致,否则交互配置了也不会触发。
44
+ - `actions` 里声明的动作要在组件里真正处理(平台把动作转成 props 变化或回调),不要声明做不到的动作。
45
+ - 组件升级后,大屏里已使用的实例不会自动变版本。需要时用 `upgradeComponentVersion` 操作显式升级。
46
+
47
+ ## 参考
48
+
49
+ 官方组件的写法可以对照 `easyv-components/easyvc_new_repos` 里的源码,例如 `basic-bar-v2` 和 `counter-v2`。
50
+ `counter-v2` 的 `counter-simple` 展示了 `emit('click', data)` 的触发方式。
@@ -0,0 +1,123 @@
1
+ # EasyV 组件规范
2
+
3
+ 一个组件目录:
4
+
5
+ ```
6
+ src/components/<module_name>/
7
+ ├── index.jsx 组件实现
8
+ └── config/
9
+ ├── main.json 配置、事件、动作
10
+ └── main.data.json 默认静态数据
11
+ ```
12
+
13
+ ## main.json
14
+
15
+ ```json
16
+ {
17
+ "base": { "name": "指标卡", "module_name": "ai_kpi_card", "version": "1.0.0", "show": 1 },
18
+ "width": 400,
19
+ "height": 200,
20
+ "configuration": [],
21
+ "triggers": [],
22
+ "actions": []
23
+ }
24
+ ```
25
+
26
+ - `base.module_name` 是组件的唯一标识,自定义组件用 `ai_` 前缀。
27
+ - `base.version` 三段式。再次发布必须更高,CLI 会自动加补丁号。
28
+ - `width`、`height` 是拖入画布时的默认尺寸。
29
+
30
+ ### configuration
31
+
32
+ 配置项数组,平台用它生成右侧配置面板,组件从 `props.configuration` 按 `name` 读取。
33
+
34
+ ```json
35
+ {
36
+ "name": "title",
37
+ "displayName": "标题",
38
+ "value": "今日销售额",
39
+ "type": "input"
40
+ }
41
+ ```
42
+
43
+ 常用 `type`:`input` 文本、`number` 数字、`color` 颜色、`select` 下拉、`radio` 单选、
44
+ `range` 滑块、`image` 图片、`boolean` 开关。下拉和单选的选项放在 `config.options`,
45
+ 每项是 `{ "name": "显示名", "value": "值" }`。
46
+
47
+ 分组用一个配置项包住子项:
48
+
49
+ ```json
50
+ {
51
+ "name": "style",
52
+ "displayName": "样式",
53
+ "value": [
54
+ { "name": "color", "displayName": "颜色", "value": "#3ba0ff", "type": "color" }
55
+ ]
56
+ }
57
+ ```
58
+
59
+ ### triggers
60
+
61
+ 组件能发出的事件。`value` 是事件标识,和代码里 `emit` 的第一个参数一致。
62
+
63
+ ```json
64
+ { "name": "鼠标点击", "value": "click" }
65
+ ```
66
+
67
+ ### actions
68
+
69
+ 组件能接收的动作。`value` 是动作标识,`config` 是执行动作时要填的参数。
70
+
71
+ ```json
72
+ {
73
+ "name": "更新数值",
74
+ "value": "setValue",
75
+ "config": [{ "name": "value", "displayName": "数值", "type": "number" }]
76
+ }
77
+ ```
78
+
79
+ ## main.data.json
80
+
81
+ ```json
82
+ {
83
+ "data": [{ "name": "华东", "value": 120 }],
84
+ "fields": [
85
+ { "name": "name", "value": "name", "desc": "类目" },
86
+ { "name": "value", "value": "value", "desc": "数值" }
87
+ ]
88
+ }
89
+ ```
90
+
91
+ `fields` 告诉平台这个组件消费哪些字段,绑数据源时用来做字段映射。
92
+
93
+ ## index.jsx
94
+
95
+ ```jsx
96
+ import React from 'react';
97
+
98
+ export default function (props) {
99
+ const { left, top, width, height, id, data, configuration, emit } = props;
100
+ const title = configuration.title;
101
+
102
+ return (
103
+ <div className="__easyv-component" id={id}
104
+ style={{ position: 'absolute', left, top, width, height }}
105
+ onClick={() => emit && emit('click', data)}>
106
+ <h3>{title}</h3>
107
+ <strong>{data[0] && data[0].value}</strong>
108
+ </div>
109
+ );
110
+ }
111
+ ```
112
+
113
+ - 根节点必须带 `className="__easyv-component"` 和 `id`。
114
+ - `data` 是当前数据,静态或来自数据源,按 `main.data.json` 的结构使用。
115
+ - `emit('<trigger>', payload)` 触发一个在 `triggers` 里声明的事件。
116
+ - 交互的回调数据通过 `onRelative` 上报,参数是 `(id, callbackData)`。
117
+
118
+ ## 打包与发布
119
+
120
+ `easyv-screen component publish <目录名>` 调用 `easyv pack` 签名打包,再上传到当前空间。
121
+ 产物是 `build/<目录名>.<版本>.constant`。签名用的 Access ID 和 Secret Key 来自 `@easyv/cli`,
122
+ 没安装或没配置时按技能正文「easyv-cli」一节处理:缺命令就 `npm install -g @easyv/cli`,
123
+ 缺密钥就让用户从工作台「开放平台 → 组件开发 → 获取Accesskey」复制后再 `easyv config set`。
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: easyv-screen-build
3
+ description: 从零搭建一个 EasyV 可视化大屏。先判断用现成组件还是从零开发组件,再创建大屏、写入文档、校验并检查布局。当用户要新建大屏、做一块看板或可视化页面时使用。
4
+ ---
5
+
6
+ # 从零搭建大屏
7
+
8
+ ## 组件从哪来
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 和版本。
16
+
17
+ 一个大屏里可以混用平台组件和自己开发的组件,不要为了用现成组件而凑合。
18
+
19
+ ## 步骤
20
+
21
+ 1. `easyv-screen screen groups` 拿到分组 id,创建时用 `--group` 指定。
22
+ 2. `easyv-screen screen create --name "<名称>" --group <groupId>` 拿到大屏 id。
23
+ 3. `easyv-screen screen document get <id> -o doc.json` 拿 `revision`。画布宽高、背景要改时,改 `doc.json` 的 `canvas`,
24
+ 再 `easyv-screen screen document put <id> -f doc.json --if-match <revision>`,用返回的新 `revision` 继续。
25
+ 4. 把要新增的组件写成 `ops.json` 的 `addComponent` 操作:
26
+ - `key` 用稳定的名字,如 `c-kpi-1`,会持久化
27
+ - `layout` 给出 `left` `top` `width` `height`,组件之间留间距,都在画布内
28
+ - `configPatches` 只写要改的字段,路径用 `easyv-screen component fields <module> --keyword "<意图>"` 查;其余字段服务端按组件默认配置补齐
29
+ - `data` 给静态数据,结构按 `schema` 的 `dataFields`;不给就用组件自带的示例数据
30
+ 5. `easyv-screen screen apply <id> -f ops.json --if-match <revision>` 一次提交。
31
+ 返回 `COMPONENT_CONFIG_INVALID` 时按 `details.elements[].unknownPaths` 重新查路径再提交。
32
+ 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>`。
35
+
36
+ ## 文档要点
37
+
38
+ - 位置写在组件 `config` 的属性树里,用 `layout` 或 `setComponentLayout`,服务端会写进 `chart.dimension.chartPosition`。
39
+ - 画布宽高、背景色放在 `canvas`。
40
+ - 需要数据时交给 `easyv-screen-data`,需要交互时交给 `easyv-screen-edit`。
@@ -0,0 +1,53 @@
1
+ ---
2
+ name: easyv-screen-data
3
+ description: 给 EasyV 大屏的组件接数据:查已有数据源、新建数据库或 API 连接、看表结构和预览数据、把组件绑定到数据源或静态数据。当用户要给组件接数据、换数据源或填静态数据时使用。
4
+ ---
5
+
6
+ # 给组件接数据
7
+
8
+ ## 先看有没有现成的数据源
9
+
10
+ `easyv-screen data source list --json`。详情用 `data source get <dataId> --json`,密码只会显示为 `******`。
11
+
12
+ ## 新建数据源
13
+
14
+ 密码只能走环境变量或标准输入,不要写进命令参数:
15
+
16
+ ```
17
+ easyv-screen data source create --name "业务库" --type mysql \
18
+ --addr 10.0.0.8 --port 3306 --username app --database biz \
19
+ --password-env DB_PASSWORD --json
20
+ ```
21
+
22
+ `--type` 常用 `mysql`、`postgresql`、`clickhouse`、`oracle`、`mssql`、`api`、`csv`。
23
+ API 类型用 `--base-url`。建完用 `data source test <dataId> --json` 确认连通。
24
+
25
+ 连接测试、表结构和预览依赖数据源服务。如果返回 `DATASOURCE_SERVICE_UNAVAILABLE`,说明服务地址还没配置,
26
+ 告诉用户这一步暂时做不了,数据源本身已经创建。
27
+
28
+ ## 确认字段
29
+
30
+ `data source tables <dataId> --json` 看有哪些表,`data source columns <dataId> --table <表名> --json` 看字段,
31
+ `data source preview <dataId> --sql "select ..." --json` 看样本。用样本核对组件需要的字段。
32
+
33
+ ## 绑定到组件
34
+
35
+ ```json
36
+ {
37
+ "operations": [
38
+ {
39
+ "op": "element.bindData",
40
+ "key": "c-88",
41
+ "dataType": "mysql",
42
+ "data": { "data_id": "<dataId>", "sql": "select name, value from sales" },
43
+ "fields": []
44
+ }
45
+ ]
46
+ }
47
+ ```
48
+
49
+ 用 `easyv-screen screen apply <id> -f ops.json --if-match <revision> --json` 提交。
50
+ `data_id` 必须是当前团队的数据源,否则校验报 `DATA_SOURCE_NOT_FOUND`。
51
+
52
+ 只用静态数据时,用 `setComponentStaticData`,`data` 传对象数组,`fields` 传字段说明。
53
+ 改回静态数据用 `element.unbindData`。
@@ -0,0 +1,35 @@
1
+ ---
2
+ name: easyv-screen-debug
3
+ description: 排查 EasyV 大屏的问题:一个组件为什么不显示、点击为什么没反应、数据为什么没绑上。基于大屏文档做确定性分析并给出结论。当用户反馈大屏显示或交互异常时使用。
4
+ ---
5
+
6
+ # 排查大屏
7
+
8
+ 这些命令只根据大屏文档下结论,能定位配置层面的原因。数据没返回、脚本报错这类运行时问题不在这里,要说明无法从文档判断。
9
+
10
+ ## 命令
11
+
12
+ - `easyv-screen debug inspect <id> <key> --json`:汇总一个组件的显隐、交互和数据状态。
13
+ - `easyv-screen debug why-hidden <id> <key> --json`:为什么不显示。
14
+ - `easyv-screen debug why-no-response <id> <key> --json`:为什么点击没反应。其它触发方式加 `--trigger mouseEnter`。
15
+
16
+ `<id>` 也可以是一份文档 JSON 文件的路径,便于离线分析。
17
+
18
+ ## 怎么读结论
19
+
20
+ 每条 finding 有 `level` 和 `code`:
21
+
22
+ | code | 含义 | 处理 |
23
+ | --- | --- | --- |
24
+ | `SELF_HIDDEN` | 组件自己被隐藏 | 问用户是否改为显示 |
25
+ | `ANCESTOR_HIDDEN` | 被某个上层分组隐藏 | 指出是哪一层,问用户改哪一层 |
26
+ | `NOT_IN_LAYERS` | 不在图层树里,不会渲染 | 需要把它加回图层 |
27
+ | `NO_EVENT` | 没有配置对应的触发事件 | 问用户想要什么效果,再用 `addComponentEvent` 补 |
28
+ | `NO_ACTION` | 事件没有动作 | 补动作 |
29
+ | `NO_TARGET` | 动作没有目标组件 | 补目标 |
30
+ | `TARGET_MISSING` | 动作指向的组件已不存在 | 事件悬空,删除或改指向 |
31
+ | `TARGET_HIDDEN` | 目标组件存在但不可见 | 说明是目标被隐藏,点了也不会有可见变化 |
32
+ | `DATA_ID_MISSING` | 声明了数据绑定但没有数据源 | 交给 `easyv-screen-data` 重新绑定 |
33
+
34
+ 先用 `inspect` 看全貌,再针对用户的具体问题用 `why-hidden` 或 `why-no-response`。
35
+ 把结论用一句人话告诉用户,并给出要不要修复的选项。
@@ -0,0 +1,59 @@
1
+ ---
2
+ name: easyv-screen-edit
3
+ description: 修改已经搭好的 EasyV 大屏:改组件配置、批量改配置、配置交互事件、调整显隐和图层、升级组件版本。当用户要改大屏、改某个组件、加点击联动或调整布局时使用。
4
+ ---
5
+
6
+ # 修改大屏
7
+
8
+ 先读再写。`easyv-screen screen document get <id> -o doc.json --json` 拿到当前文档和 `revision`。
9
+
10
+ ## 用原子操作做局部修改
11
+
12
+ 把操作写进 `ops.json`,格式 `{ "operations": [ ... ] }`,然后:
13
+
14
+ ```
15
+ easyv-screen screen apply <id> -f ops.json --if-match <revision> --json
16
+ ```
17
+
18
+ 支持的操作(元素和图层都用文档 key):
19
+
20
+ | 操作 | 作用 | 关键字段 |
21
+ | --- | --- | --- |
22
+ | `addComponent` | 新增组件,其余用组件默认配置 | `key` `module` `version` `name` `layout` `configPatches` `data` `parentKey` `index` |
23
+ | `removeComponent` | 删除组件 | `key` |
24
+ | `setComponentConfig` | 按路径改配置 | `key` `configPatches`(`[{ path, value }]`) |
25
+ | `setComponentLayout` | 改位置尺寸 | `key` `layout`(`left` `top` `width` `height`) |
26
+ | `element.update` | 改名称或整棵配置树 | `key` `name` `config` |
27
+ | `addComponentEvent` | 新增交互事件 | `key` `event` |
28
+ | `updateComponentEvent` | 替换一个事件 | `key` `eventId` `event` |
29
+ | `deleteComponentEvent` | 删除一个事件 | `key` `eventId` |
30
+ | `setComponentStaticData` | 设置静态数据 | `key` `data` `fields` |
31
+ | `element.bindData` | 绑定数据源 | `key` `dataType` `data`(含 `data_id`) |
32
+ | `element.unbindData` | 改回静态数据 | `key` |
33
+ | `setLayerVisible` | 显隐 | `key` `visible` |
34
+ | `moveLayer` | 移动图层 | `key` `parentKey` `index` |
35
+ | `groupLayers` | 成组 | `keys` `groupKey`(`g-` 开头) `name` |
36
+ | `ungroupLayer` | 解散分组 | `key` |
37
+ | `upgradeComponentVersion` | 升级组件版本 | `key` `version` |
38
+ | `screen.updateMeta` | 改大屏名称 | `name` |
39
+
40
+ 改完跑 `screen validate <id> --json`。
41
+
42
+ ## 交互事件
43
+
44
+ `event` 的结构与编辑器一致:`trigger` 是触发方式(`click`、`mouseEnter`),`actions` 里每一项的
45
+ `action` 是动作类型,`component` 用 `$component(<组件数字id>)` 指向目标。组件数字 id 就是 key 里 `c-` 后面的数字。
46
+ 目标组件的动作要它的 `actions` 声明里支持。
47
+
48
+ ## 改配置
49
+
50
+ `configPatches` 的 `path` 用 `easyv-screen component fields <module> --keyword "<意图>"` 查,例如
51
+ `--keyword "图例"`、`--keyword "坐标轴 字号"`。返回的 `labelPath` 是中文标签链,按它判断字段含义,`path` 原样填进补丁。
52
+ 不传 `--keyword` 只看分组,再按分组名搜。不要猜路径:路径不存在时整批会被拒绝。
53
+
54
+ 优先用 `setComponentConfig` 和 `setComponentLayout`。`element.update` 的 `config` 是整棵属性树替换,
55
+ 只有确实要重写整棵树时才用,并且先从文档里取出当前 `config` 再改。
56
+
57
+ ## 批量修改
58
+
59
+ 多个组件的修改放进同一个 `operations` 数组一次提交,任何一条不通过整批都不落库。
@@ -0,0 +1,31 @@
1
+ ---
2
+ name: easyv-screen-shared
3
+ description: 使用 easyv-screen 命令操作 EasyV 大屏时的共用规则:登录、--json 输出、revision 乐观锁、写入前确认。任何搭建、修改、排查或组件开发任务都先遵守这里。
4
+ ---
5
+
6
+ # EasyV 大屏 CLI 共用规则
7
+
8
+ 命令是 `easyv-screen`。输出默认就是 JSON,不需要再加 `--json`。
9
+
10
+ ## 开始之前
11
+
12
+ 1. 先看有没有环境:`easyv-screen config list --json`。没有就添加并切换:
13
+ `easyv-screen config add --name <名称> --base-url <OpenAPI 地址> --web <Web 站点地址> --use`。
14
+ baseURL 形如 `http://127.0.0.1:9800/api/easyv/open/v1`。可以添加多个环境,用 `config use <名称>` 切换。
15
+ 2. 每个 baseURL 有自己的一组 API Key,环境之间不共用。先 `easyv-screen auth list --json` 看当前地址下的 Key。
16
+ 已有 Key 时 `easyv-screen auth add --name <名称> --token <appId.secret>`,多把 Key 用 `auth use <名称>` 切换。
17
+ 只能切换当前 baseURL 下的 Key;换地址要先 `config use`。
18
+ 没有 Key 时运行 `easyv-screen auth login`,把输出的授权地址交给用户,等用户在浏览器确认。
19
+ 3. 一把 Key 只绑定一个空间和一个团队。`easyv-screen auth status` 会返回当前 Key 绑定的空间名称、空间 ID、团队名称和团队 ID。要操作别的团队,在同一个 baseURL 下换一把 Key。
20
+
21
+ ## 写入规则
22
+
23
+ - 读文档拿到的 `revision` 要在写回时带上:`document put` 和 `apply` 都支持 `--if-match <revision>`。
24
+ 返回 `REVISION_CONFLICT`(退出码 4)时,重新 `document get` 再合并,不要原样重试。
25
+ - 写完跑 `screen validate`。有 `error` 先修再继续;`warn` 告知用户即可。
26
+ - 发布、删除、上传组件会生效到用户的空间。执行前用一句话向用户确认。
27
+ - 不要编造组件的配置字段。用 `component fields <module> --keyword` 查路径;用自己开发的组件时也可以对照 `main.json` 的 `configuration`。
28
+
29
+ ## 退出码
30
+
31
+ `0` 成功,`1` 业务错误,`2` 参数错误,`3` 未登录或凭证失效,`4` 版本冲突。