@easyv/screen-cli 0.0.0-stage → 0.1.1

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,224 @@
1
+ "use strict";
2
+ /**
3
+ * 从大屏文档里抽出一个组件的数据来源和交互配置。
4
+ * 只做提取和引用解析,不判断显示或点击是否正常。
5
+ */
6
+ Object.defineProperty(exports, "__esModule", { value: true });
7
+ exports.queryComponent = queryComponent;
8
+ const REF_RULES = [
9
+ { type: 'component', source: String.raw `\$super\(component\(([^)]+)\)\)` },
10
+ { type: 'component', source: String.raw `\$container_\w+\(component\(([^)]+)\)\)` },
11
+ { type: 'component', source: String.raw `\$component\(([^)]+)\)` },
12
+ { type: 'group', source: String.raw `\$group\(([^)]+)\)` },
13
+ { type: 'panel', source: String.raw `\$panel\(([^)]+)\)` },
14
+ { type: 'container', source: String.raw `\$container\(([^)]+)\)` },
15
+ { type: 'state', source: String.raw `\$state\(([^)]+)\)` },
16
+ ];
17
+ /** 读取一个组件的数据绑定,以及指向别人 / 被别人指向的事件。 */
18
+ function queryComponent(document, key, filter = {}) {
19
+ const index = indexDocument(document.elements);
20
+ const target = index.all.find(item => item.key === key);
21
+ if (target == null)
22
+ throw new Error(`文档里没有 ${key}`);
23
+ const outgoing = readEvents(target.element).filter(event => matches(event, filter));
24
+ const incoming = index.all
25
+ .filter(item => item !== target)
26
+ .flatMap(item => readEvents(item.element)
27
+ .filter(event => matches(event, filter) && targetsKey(event, key, index))
28
+ .map(event => ({ ...describe(item), event })));
29
+ const refTexts = new Set();
30
+ collectRefStrings(outgoing, refTexts);
31
+ collectRefStrings(incoming, refTexts);
32
+ const refs = {};
33
+ for (const ref of [...refTexts].sort())
34
+ refs[ref] = resolveRef(ref, index);
35
+ return {
36
+ ...describe(target),
37
+ data: {
38
+ dataBinding: target.element['dataBinding'] ?? null,
39
+ staticData: target.element['staticData'] ?? null,
40
+ },
41
+ outgoing,
42
+ incoming,
43
+ refs,
44
+ };
45
+ }
46
+ function indexDocument(elements) {
47
+ const index = { elements: new Map(), states: new Map(), all: [] };
48
+ walkElements(elements, undefined, index);
49
+ return index;
50
+ }
51
+ function walkElements(elements, location, index) {
52
+ if (!isRecord(elements))
53
+ return;
54
+ for (const [key, value] of Object.entries(elements)) {
55
+ if (!isRecord(value))
56
+ continue;
57
+ const located = { key, element: value, ...(location != null ? { location } : {}) };
58
+ index.all.push(located);
59
+ if (!index.elements.has(key))
60
+ index.elements.set(key, located);
61
+ const states = value['states'];
62
+ if (!Array.isArray(states))
63
+ continue;
64
+ const parentKind = typeof value['kind'] === 'string' ? value['kind'] : 'panel';
65
+ for (const state of states) {
66
+ if (!isRecord(state) || typeof state['key'] !== 'string')
67
+ continue;
68
+ const stateName = typeof state['name'] === 'string' ? state['name'] : undefined;
69
+ if (!index.states.has(state['key'])) {
70
+ index.states.set(state['key'], {
71
+ key: state['key'],
72
+ parentKey: key,
73
+ ...(stateName != null ? { name: stateName } : {}),
74
+ });
75
+ }
76
+ walkElements(state['elements'], {
77
+ parentKey: key,
78
+ parentKind,
79
+ stateKey: state['key'],
80
+ ...(stateName != null ? { stateName } : {}),
81
+ }, index);
82
+ }
83
+ }
84
+ }
85
+ function describe(located) {
86
+ const described = {
87
+ key: located.key,
88
+ kind: typeof located.element['kind'] === 'string' ? located.element['kind'] : 'unknown',
89
+ };
90
+ copyString(described, 'name', located.element['name']);
91
+ copyString(described, 'module', located.element['module']);
92
+ copyString(described, 'version', located.element['version']);
93
+ if (located.location != null)
94
+ described['location'] = located.location;
95
+ return described;
96
+ }
97
+ function readEvents(element) {
98
+ const interactions = element['interactions'];
99
+ if (!isRecord(interactions) || !Array.isArray(interactions['events']))
100
+ return [];
101
+ return interactions['events'];
102
+ }
103
+ function matches(event, filter) {
104
+ if (filter.trigger == null && filter.eventId == null)
105
+ return true;
106
+ if (!isRecord(event))
107
+ return false;
108
+ if (filter.trigger != null && event['trigger'] !== filter.trigger)
109
+ return false;
110
+ if (filter.eventId != null && String(event['id'] ?? '') !== filter.eventId)
111
+ return false;
112
+ return true;
113
+ }
114
+ function targetsKey(event, key, index) {
115
+ if (!isRecord(event) || !Array.isArray(event['actions']))
116
+ return false;
117
+ return event['actions'].some((action) => {
118
+ if (!isRecord(action))
119
+ return false;
120
+ return actionTargets(action['component']).some(raw => extractRefs(raw).some(ref => resolveRef(ref, index).key === key));
121
+ });
122
+ }
123
+ function actionTargets(component) {
124
+ if (typeof component === 'string')
125
+ return [component];
126
+ if (!Array.isArray(component))
127
+ return [];
128
+ return component.filter((item) => typeof item === 'string');
129
+ }
130
+ function collectRefStrings(value, into) {
131
+ if (typeof value === 'string') {
132
+ for (const ref of extractRefs(value))
133
+ into.add(ref);
134
+ return;
135
+ }
136
+ if (Array.isArray(value)) {
137
+ for (const item of value)
138
+ collectRefStrings(item, into);
139
+ return;
140
+ }
141
+ if (isRecord(value)) {
142
+ for (const item of Object.values(value))
143
+ collectRefStrings(item, into);
144
+ }
145
+ }
146
+ function extractRefs(text) {
147
+ const refs = [];
148
+ for (const rule of REF_RULES) {
149
+ for (const match of text.matchAll(new RegExp(rule.source, 'g'))) {
150
+ const id = match[1];
151
+ if (id != null && id.length > 0)
152
+ refs.push(`$${rule.type}(${id})`);
153
+ }
154
+ }
155
+ return refs;
156
+ }
157
+ function resolveRef(ref, index) {
158
+ const match = /^\$(component|group|panel|container|state)\(([^)]+)\)$/.exec(ref);
159
+ if (match == null)
160
+ return { found: false };
161
+ const type = match[1] ?? '';
162
+ const id = match[2] ?? '';
163
+ if (type === 'state') {
164
+ const state = index.states.get(id);
165
+ if (state == null)
166
+ return { found: false };
167
+ return {
168
+ key: state.key,
169
+ kind: 'state',
170
+ found: true,
171
+ parentKey: state.parentKey,
172
+ ...(state.name != null ? { name: state.name } : {}),
173
+ };
174
+ }
175
+ const key = guessKey(type, id, index);
176
+ const located = key != null ? index.elements.get(key) : undefined;
177
+ if (located == null)
178
+ return { ...(key != null ? { key } : {}), found: false };
179
+ const resolved = { key: located.key, kind: describe(located)['kind'], found: true };
180
+ copyString(resolved, 'name', located.element['name']);
181
+ copyString(resolved, 'module', located.element['module']);
182
+ return resolved;
183
+ }
184
+ function guessKey(type, id, index) {
185
+ if (index.elements.has(id))
186
+ return id;
187
+ if (type === 'component') {
188
+ if (/^\d+$/.test(id))
189
+ return `c-${id}`;
190
+ if (id.startsWith('super_'))
191
+ return `u-${id.slice('super_'.length)}`;
192
+ return `c-${id}`;
193
+ }
194
+ if (type === 'group') {
195
+ const raw = id.startsWith('group_') ? id.slice('group_'.length) : id;
196
+ return `g-${sanitize(raw)}`;
197
+ }
198
+ if (type === 'panel') {
199
+ if (id.startsWith('panel_'))
200
+ return `p-${id.slice('panel_'.length)}`;
201
+ if (id.startsWith('ref_'))
202
+ return `rp-${id.slice('ref_'.length)}`;
203
+ if (/^\d+$/.test(id))
204
+ return `p-${id}`;
205
+ return undefined;
206
+ }
207
+ if (type === 'container') {
208
+ if (id.startsWith('container_'))
209
+ return `k-${id.slice('container_'.length)}`;
210
+ if (/^\d+$/.test(id))
211
+ return `k-${id}`;
212
+ }
213
+ return undefined;
214
+ }
215
+ function sanitize(value) {
216
+ return value.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-');
217
+ }
218
+ function copyString(target, field, value) {
219
+ if (typeof value === 'string')
220
+ target[field] = value;
221
+ }
222
+ function isRecord(value) {
223
+ return typeof value === 'object' && value != null && !Array.isArray(value);
224
+ }
package/dist/index.js ADDED
@@ -0,0 +1,25 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ const commander_1 = require("commander");
4
+ const auth_1 = require("./commands/auth");
5
+ const component_1 = require("./commands/component");
6
+ const data_1 = require("./commands/data");
7
+ const debug_1 = require("./commands/debug");
8
+ const screen_1 = require("./commands/screen");
9
+ const skills_1 = require("./commands/skills");
10
+ const program = new commander_1.Command();
11
+ program
12
+ .name('easyv-screen')
13
+ .description('用命令驱动 EasyV 大屏:搭建、修改、排查,以及从零开发组件')
14
+ .version('0.1.0')
15
+ .option('--json', '输出 JSON。现在默认就是 JSON,这个参数可以不写');
16
+ (0, auth_1.registerAuth)(program);
17
+ (0, screen_1.registerScreen)(program);
18
+ (0, component_1.registerComponent)(program);
19
+ (0, data_1.registerData)(program);
20
+ (0, debug_1.registerDebug)(program);
21
+ (0, skills_1.registerSkills)(program);
22
+ program.parseAsync(process.argv).catch((error) => {
23
+ console.error(error.message);
24
+ process.exit(1);
25
+ });
package/dist/output.js ADDED
@@ -0,0 +1,7 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.emit = emit;
4
+ /** 命令输出默认就是 JSON,便于人和 AI 读取。--json 仍然接受,不再改变格式。 */
5
+ function emit(_json, data, _human) {
6
+ console.log(JSON.stringify(data, null, 2));
7
+ }
package/package.json CHANGED
@@ -1,6 +1,38 @@
1
1
  {
2
2
  "name": "@easyv/screen-cli",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "用自然语言驱动 EasyV 大屏的命令行工具:搭建、修改、排查,以及从零开发组件",
5
+ "bin": {
6
+ "easyv-screen": "bin/easyv-screen.js"
7
+ },
8
+ "files": [
9
+ "bin",
10
+ "dist",
11
+ "skills",
12
+ "spec"
13
+ ],
14
+ "scripts": {
15
+ "build": "tsc -p tsconfig.json",
16
+ "sync-spec": "node scripts/sync-spec.js",
17
+ "prepack": "npm run sync-spec && npm run build",
18
+ "typecheck": "tsc --noEmit -p tsconfig.json"
19
+ },
20
+ "engines": {
21
+ "node": ">=18"
22
+ },
23
+ "dependencies": {
24
+ "commander": "^12.1.0"
25
+ },
26
+ "optionalDependencies": {
27
+ "playwright": "^1.48.0"
28
+ },
29
+ "devDependencies": {
30
+ "@types/node": "^22.9.0",
31
+ "typescript": "^5.6.3"
32
+ },
33
+ "license": "UNLICENSED",
34
+ "publishConfig": {
35
+ "registry": "https://registry.npmjs.org/",
36
+ "access": "public"
37
+ }
38
+ }
@@ -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,49 @@
1
+ ---
2
+ name: easyv-screen-debug
3
+ description: 排查 EasyV 大屏的问题。读取一个组件的数据来源和交互配置(它触发了谁、谁触发了它),再根据这些配置判断原因。当用户反馈大屏显示、交互或数据异常时使用。
4
+ ---
5
+
6
+ # 排查大屏
7
+
8
+ `easyv-screen debug` 只取出一个组件的配置,不下结论。拿到数据后自己判断原因,再用一句人话告诉用户。
9
+
10
+ 下面这些已经有别的命令,不要再用 debug 去要:
11
+
12
+ - 显隐、位置、完整属性树:`easyv-screen screen document get <screenId>`
13
+ - 数据源连接详情、表和预览:拿到 `data_id` 后走 `easyv-screen-data`
14
+ - 组件能发出的事件、能接收的动作:`easyv-screen component schema <module>`
15
+
16
+ ## 命令
17
+
18
+ ```
19
+ easyv-screen debug <screenId> <key>
20
+ ```
21
+
22
+ `<screenId>` 是大屏 id,也可以是一份文档 JSON 的路径。
23
+
24
+ `<key>` 是组件在文档里的 key,以 `c-` 开头。平台上已有的组件是 `c-` 加组件数字 id,例如组件 `88` 写成 `c-88`。通过命令新建并指定了 key 的组件,用当时写入的那个 key,例如 `c-kpi-1`,横线后面不一定是数字 id。
25
+
26
+ 过滤事件时加上,两个条件同时生效:
27
+
28
+ - `--trigger <trigger>`:只保留这种触发方式,例如 `click`、`mouseEnter`
29
+ - `--event <eventId>`:只保留这一个事件
30
+
31
+ ## 返回里有什么
32
+
33
+ - `data.dataBinding`:数据源绑定。不为 `null` 时,`dataType` 是类型,`data.data_id` 是数据源 id,其余字段是查询配置(如 `sql`)。为 `null` 表示当前用静态数据。
34
+ - `data.staticData`:文档里的静态数据。绑了数据源时它也可能还在。
35
+ - `outgoing`:这个组件自己的事件,结构与文档里的 `interactions.events` 相同。动作的 `component` 是它指向的目标。
36
+ - `incoming`:别的组件里,动作 `component` 指向它的事件。每项的 `key` 是来源组件。
37
+ - `refs`:上面这些事件里出现的 `$component(...)` 等引用,解析成文档 key、名称和 `found`。`found` 为 false 表示文档里没有这个对象。
38
+ - `location`:组件在某个面板或容器的状态里时才有。没有该字段就是在大屏根上。
39
+
40
+ ## 怎么判断
41
+
42
+ 按用户的具体问题看对应的字段,不要套固定的故障类型。
43
+
44
+ - 点击没反应:看 `outgoing` 里有没有该触发方式、动作有没有目标、`refs` 里目标是否 `found`。只关心一种触发就加 `--trigger`。
45
+ - 被别的组件影响:看 `incoming`,来源是每一项的 `key`。
46
+ - 数据不对:先看 `data`。绑定了数据源再按 `data_id` 查连接和预览。
47
+ - 不显示:debug 不返回显隐。用 `screen document get` 看该 key 和祖先图层的 `visible`。
48
+
49
+ 接口没返回、脚本报错这类运行时问题,文档里看不出来,直接说明。