@easyv/screen-cli 0.1.4 → 0.1.6
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.
- package/README.md +31 -7
- package/dist/commands/elements.js +226 -0
- package/dist/index.js +2 -0
- package/package.json +1 -1
- package/skills/easyv-component-dev/SKILL.md +24 -3
- package/skills/easyv-screen-build/SKILL.md +35 -24
- package/skills/easyv-screen-data/SKILL.md +17 -7
- package/skills/easyv-screen-debug/SKILL.md +8 -4
- package/skills/easyv-screen-edit/SKILL.md +20 -10
- package/skills/easyv-screen-shared/SKILL.md +24 -2
- package/skills/{easyv-screen-build → easyv-screen-shared}/references/component-selection.md +15 -1
- package/skills/easyv-screen-shared/references/custom-events.md +133 -0
- package/skills/easyv-screen-shared/references/panels-containers.md +114 -0
- package/skills/figma-asset-slice/SKILL.md +3 -1
- package/spec/openapi.v1.yaml +829 -83
package/README.md
CHANGED
|
@@ -158,7 +158,11 @@ easyv-screen screen document put <id> -f doc.json --if-match <revision>
|
|
|
158
158
|
|
|
159
159
|
| 操作 | 作用 |
|
|
160
160
|
| --- | --- |
|
|
161
|
-
| `addComponent` | 新增组件。`key`、`module`、`version`、`name`、`layout`;可选 `configPatches`、`data`、`parentKey`、`index` |
|
|
161
|
+
| `addComponent` | 新增组件。`key`、`module`、`version`、`name`、`layout`;可选 `configPatches`、`data`、`parentKey`、`index`。`parentKey` 只能是已有分组 |
|
|
162
|
+
| `addPanel` | 新增动态面板,自带一个空状态。`key`、可选 `name`、`layout`、`parentKey`、`index` |
|
|
163
|
+
| `addContainer` | 新增组件容器,自带一个空子屏。字段同 `addPanel`,名称最长 50 |
|
|
164
|
+
| `addFilter` | 在根屏上新增过滤器。`key`、`name`,可选 `content`、`callbackKeys` |
|
|
165
|
+
| `addDataContainer` | 在根屏上新增数据容器。`key`、`name`。不占图层 |
|
|
162
166
|
| `removeComponent` | 删除组件 |
|
|
163
167
|
| `setComponentConfig` | 按路径改配置,`configPatches` 为 `[{ path, value }]` |
|
|
164
168
|
| `setComponentLayout` | 改位置和尺寸:`left`、`top`、`width`、`height` |
|
|
@@ -174,6 +178,26 @@ easyv-screen screen document put <id> -f doc.json --if-match <revision>
|
|
|
174
178
|
|
|
175
179
|
交互事件的 `trigger` 是触发方式(如 `click`、`mouseEnter`),`actions` 里的 `component` 用 `$component(<数字 id>)` 指向目标。数字 id 是组件 key 里 `c-` 后面的数字。
|
|
176
180
|
|
|
181
|
+
## 面板、容器和数据容器
|
|
182
|
+
|
|
183
|
+
`document get` 会读出动态面板、引用面板、组件容器,以及根屏上的过滤器和数据容器。编辑器里已有的动态面板和引用面板,元素 key 是 `p-<id>`,引用面板的图层 key 是 `rp-<id>`,组件容器是 `k-<id>`。用 `addPanel` / `addContainer` 新建时,key 用你指定的名字,并在元素上带回 `id`。状态 key 是 `s-` 加子屏 id。过滤器和数据容器不占图层,分别在 `filters`、`dataContainers`。
|
|
184
|
+
|
|
185
|
+
从零搭建时,把动态面板、组件容器、过滤器和数据容器写进文档,一次 `document put`。改已经存在的大屏时用单独的命令:
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
easyv-screen panel create <id> --key panel-tabs --name 页签 --left 40 --top 80 --width 600 --height 360
|
|
189
|
+
easyv-screen panel state create <id> panel-tabs --name 详情
|
|
190
|
+
easyv-screen container update <id> repeat-1 --name 列表
|
|
191
|
+
easyv-screen filter update <id> unit-filter --content "return data"
|
|
192
|
+
easyv-screen data-container delete <id> sales-dc
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
`panel`、`container` 还有 `list`、`get`、`update`、`delete`。`panel state` 同样有这一套,状态 key 是 `s-` 加子屏 id,至少保留一个状态。过滤器和数据容器挂在根屏上。删除动态面板和组件容器会进回收站。
|
|
196
|
+
|
|
197
|
+
不能把组件放进面板或容器,也不能改状态里面的组件。`parentKey` 只能指向分组。引用面板和万能组件不能新建。`element.bindContainer`、`element.bindFilter` 仍不能调用。`document put` 少了已有的面板、容器、过滤器或数据容器,仍会整单拒绝。
|
|
198
|
+
|
|
199
|
+
已有大屏里这三类对象怎么认,见技能 `easyv-screen-shared` 的 `references/panels-containers.md`。用自定义事件切到某个面板状态时,见同一技能的 `references/custom-events.md`。组件选型见同一技能的 `references/component-selection.md`。
|
|
200
|
+
|
|
177
201
|
其他常用命令:
|
|
178
202
|
|
|
179
203
|
```bash
|
|
@@ -263,12 +287,12 @@ easyv config set secretkey <Secret Key>
|
|
|
263
287
|
|
|
264
288
|
| 技能 | 什么时候用 |
|
|
265
289
|
| --- | --- |
|
|
266
|
-
| `easyv-screen-shared` |
|
|
267
|
-
| `easyv-screen-build` |
|
|
268
|
-
| `easyv-screen-edit` |
|
|
269
|
-
| `easyv-screen-data` |
|
|
270
|
-
| `easyv-screen-debug` |
|
|
271
|
-
| `easyv-component-dev` |
|
|
290
|
+
| `easyv-screen-shared` | 每次操作前都先读:工作台、登录、找到大屏、revision、发布或删除前确认。选型、事件、面板容器、预览和发布链接也在这里 |
|
|
291
|
+
| `easyv-screen-build` | 从零搭建一块大屏。接数据和配交互交给下面两个技能 |
|
|
292
|
+
| `easyv-screen-edit` | 改已有大屏的组件、配置、交互和图层,以及发布、取消发布和截图 |
|
|
293
|
+
| `easyv-screen-data` | 查、改、删数据源,给组件接数据或填静态数据 |
|
|
294
|
+
| `easyv-screen-debug` | 排查单个组件的数据来源和交互。组件不显示时改看文档里的显隐 |
|
|
295
|
+
| `easyv-component-dev` | 从零开发组件并上传。放进大屏交给搭建或修改 |
|
|
272
296
|
|
|
273
297
|
## 输出和退出码
|
|
274
298
|
|
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.registerElements = registerElements;
|
|
4
|
+
const client_1 = require("../client");
|
|
5
|
+
const output_1 = require("../output");
|
|
6
|
+
const auth_1 = require("./auth");
|
|
7
|
+
/**
|
|
8
|
+
* 动态面板、面板状态、过滤器、组件容器、数据容器。
|
|
9
|
+
* 从零搭建优先把它们写进文档一次提交;这些命令用于改已经存在的大屏。
|
|
10
|
+
*/
|
|
11
|
+
function registerElements(program) {
|
|
12
|
+
const panel = program.command('panel').description('动态面板。引用面板不在这里');
|
|
13
|
+
registerPlacement(panel, 'panels', '动态面板');
|
|
14
|
+
registerStates(panel);
|
|
15
|
+
registerPlacement(program.command('container').description('组件容器'), 'component-containers', '组件容器');
|
|
16
|
+
registerNamed(program.command('filter').description('过滤器,挂在根屏上'), 'filters', '过滤器', true);
|
|
17
|
+
registerNamed(program.command('data-container').description('数据容器,挂在根屏上'), 'data-containers', '数据容器', false);
|
|
18
|
+
}
|
|
19
|
+
function registerPlacement(command, segment, label) {
|
|
20
|
+
command.command('list')
|
|
21
|
+
.description(`列出${label}`)
|
|
22
|
+
.argument('<screenId>', '大屏 id')
|
|
23
|
+
.action(async function (screenId) {
|
|
24
|
+
await run(this, () => (0, client_1.createClient)().request('GET', `/screens/${screenId}/${segment}`));
|
|
25
|
+
});
|
|
26
|
+
command.command('get')
|
|
27
|
+
.description(`查看${label}`)
|
|
28
|
+
.argument('<screenId>')
|
|
29
|
+
.argument('<key>', '文档 key')
|
|
30
|
+
.action(async function (screenId, key) {
|
|
31
|
+
await run(this, () => (0, client_1.createClient)().request('GET', `/screens/${screenId}/${segment}/${encodeURIComponent(key)}`));
|
|
32
|
+
});
|
|
33
|
+
command.command('create')
|
|
34
|
+
.description(`新建${label}`)
|
|
35
|
+
.argument('<screenId>')
|
|
36
|
+
.requiredOption('--key <key>', '稳定的文档 key,例如 panel-tabs')
|
|
37
|
+
.option('--name <name>')
|
|
38
|
+
.option('--left <n>')
|
|
39
|
+
.option('--top <n>')
|
|
40
|
+
.option('--width <n>')
|
|
41
|
+
.option('--height <n>')
|
|
42
|
+
.option('--parent <key>', '放到某个分组里,只能是已有分组')
|
|
43
|
+
.option('--index <n>', '在兄弟图层中的位置,从 0 开始')
|
|
44
|
+
.action(async function (screenId, options) {
|
|
45
|
+
await run(this, () => (0, client_1.createClient)().request('POST', `/screens/${screenId}/${segment}`, {
|
|
46
|
+
body: placementBody(options, true),
|
|
47
|
+
}));
|
|
48
|
+
});
|
|
49
|
+
command.command('update')
|
|
50
|
+
.description(`修改${label}的名称或位置`)
|
|
51
|
+
.argument('<screenId>')
|
|
52
|
+
.argument('<key>')
|
|
53
|
+
.option('--name <name>')
|
|
54
|
+
.option('--left <n>')
|
|
55
|
+
.option('--top <n>')
|
|
56
|
+
.option('--width <n>')
|
|
57
|
+
.option('--height <n>')
|
|
58
|
+
.action(async function (screenId, key, options) {
|
|
59
|
+
await run(this, () => (0, client_1.createClient)().request('PATCH', `/screens/${screenId}/${segment}/${encodeURIComponent(key)}`, {
|
|
60
|
+
body: placementBody(options, false),
|
|
61
|
+
}));
|
|
62
|
+
});
|
|
63
|
+
command.command('delete')
|
|
64
|
+
.description(`删除${label}。面板和组件容器进入回收站`)
|
|
65
|
+
.argument('<screenId>')
|
|
66
|
+
.argument('<key>')
|
|
67
|
+
.action(async function (screenId, key) {
|
|
68
|
+
await run(this, () => (0, client_1.createClient)().request('DELETE', `/screens/${screenId}/${segment}/${encodeURIComponent(key)}`));
|
|
69
|
+
});
|
|
70
|
+
}
|
|
71
|
+
function registerStates(panel) {
|
|
72
|
+
const state = panel.command('state').description('动态面板的状态');
|
|
73
|
+
state.command('list')
|
|
74
|
+
.description('列出动态面板的状态')
|
|
75
|
+
.argument('<screenId>')
|
|
76
|
+
.argument('<panelKey>')
|
|
77
|
+
.action(async function (screenId, panelKey) {
|
|
78
|
+
await run(this, () => (0, client_1.createClient)().request('GET', statePath(screenId, panelKey)));
|
|
79
|
+
});
|
|
80
|
+
state.command('get')
|
|
81
|
+
.description('查看一个状态')
|
|
82
|
+
.argument('<screenId>')
|
|
83
|
+
.argument('<panelKey>')
|
|
84
|
+
.argument('<stateKey>', '状态 key,形如 s-88001')
|
|
85
|
+
.action(async function (screenId, panelKey, stateKey) {
|
|
86
|
+
await run(this, () => (0, client_1.createClient)().request('GET', `${statePath(screenId, panelKey)}/${encodeURIComponent(stateKey)}`));
|
|
87
|
+
});
|
|
88
|
+
state.command('create')
|
|
89
|
+
.description('给动态面板新增一个空状态')
|
|
90
|
+
.argument('<screenId>')
|
|
91
|
+
.argument('<panelKey>')
|
|
92
|
+
.option('--name <name>', '不传则按「状态N」命名')
|
|
93
|
+
.action(async function (screenId, panelKey, options) {
|
|
94
|
+
await run(this, () => (0, client_1.createClient)().request('POST', statePath(screenId, panelKey), {
|
|
95
|
+
body: { ...(options.name != null ? { name: options.name } : {}) },
|
|
96
|
+
}));
|
|
97
|
+
});
|
|
98
|
+
state.command('update')
|
|
99
|
+
.description('重命名一个状态')
|
|
100
|
+
.argument('<screenId>')
|
|
101
|
+
.argument('<panelKey>')
|
|
102
|
+
.argument('<stateKey>')
|
|
103
|
+
.requiredOption('--name <name>')
|
|
104
|
+
.action(async function (screenId, panelKey, stateKey, options) {
|
|
105
|
+
await run(this, () => (0, client_1.createClient)().request('PATCH', `${statePath(screenId, panelKey)}/${encodeURIComponent(stateKey)}`, {
|
|
106
|
+
body: { name: options.name },
|
|
107
|
+
}));
|
|
108
|
+
});
|
|
109
|
+
state.command('delete')
|
|
110
|
+
.description('删除一个状态。至少保留一个')
|
|
111
|
+
.argument('<screenId>')
|
|
112
|
+
.argument('<panelKey>')
|
|
113
|
+
.argument('<stateKey>')
|
|
114
|
+
.action(async function (screenId, panelKey, stateKey) {
|
|
115
|
+
await run(this, () => (0, client_1.createClient)().request('DELETE', `${statePath(screenId, panelKey)}/${encodeURIComponent(stateKey)}`));
|
|
116
|
+
});
|
|
117
|
+
}
|
|
118
|
+
function registerNamed(command, segment, label, withFilterBody) {
|
|
119
|
+
command.command('list')
|
|
120
|
+
.description(`列出${label}`)
|
|
121
|
+
.argument('<screenId>')
|
|
122
|
+
.action(async function (screenId) {
|
|
123
|
+
await run(this, () => (0, client_1.createClient)().request('GET', `/screens/${screenId}/${segment}`));
|
|
124
|
+
});
|
|
125
|
+
command.command('get')
|
|
126
|
+
.description(`查看${label}`)
|
|
127
|
+
.argument('<screenId>')
|
|
128
|
+
.argument('<key>')
|
|
129
|
+
.action(async function (screenId, key) {
|
|
130
|
+
await run(this, () => (0, client_1.createClient)().request('GET', `/screens/${screenId}/${segment}/${encodeURIComponent(key)}`));
|
|
131
|
+
});
|
|
132
|
+
const create = command.command('create')
|
|
133
|
+
.description(`新建${label}`)
|
|
134
|
+
.argument('<screenId>')
|
|
135
|
+
.requiredOption('--key <key>')
|
|
136
|
+
.requiredOption('--name <name>');
|
|
137
|
+
if (withFilterBody) {
|
|
138
|
+
create
|
|
139
|
+
.option('--content <content>', '过滤器函数体,默认 return data')
|
|
140
|
+
.option('--callback-keys <keys>', '逗号分隔的回调参数名');
|
|
141
|
+
}
|
|
142
|
+
create.action(async function (screenId, options) {
|
|
143
|
+
await run(this, () => (0, client_1.createClient)().request('POST', `/screens/${screenId}/${segment}`, {
|
|
144
|
+
body: namedBody(options, withFilterBody),
|
|
145
|
+
}));
|
|
146
|
+
});
|
|
147
|
+
const update = command.command('update')
|
|
148
|
+
.description(`修改${label}`)
|
|
149
|
+
.argument('<screenId>')
|
|
150
|
+
.argument('<key>');
|
|
151
|
+
if (withFilterBody) {
|
|
152
|
+
update
|
|
153
|
+
.option('--name <name>')
|
|
154
|
+
.option('--content <content>', '过滤器函数体')
|
|
155
|
+
.option('--callback-keys <keys>', '逗号分隔的回调参数名');
|
|
156
|
+
}
|
|
157
|
+
else {
|
|
158
|
+
update.requiredOption('--name <name>');
|
|
159
|
+
}
|
|
160
|
+
update.action(async function (screenId, key, options) {
|
|
161
|
+
await run(this, () => (0, client_1.createClient)().request('PATCH', `/screens/${screenId}/${segment}/${encodeURIComponent(key)}`, {
|
|
162
|
+
body: namedBody(options, withFilterBody),
|
|
163
|
+
}));
|
|
164
|
+
});
|
|
165
|
+
command.command('delete')
|
|
166
|
+
.description(`删除${label}`)
|
|
167
|
+
.argument('<screenId>')
|
|
168
|
+
.argument('<key>')
|
|
169
|
+
.action(async function (screenId, key) {
|
|
170
|
+
await run(this, () => (0, client_1.createClient)().request('DELETE', `/screens/${screenId}/${segment}/${encodeURIComponent(key)}`));
|
|
171
|
+
});
|
|
172
|
+
}
|
|
173
|
+
function statePath(screenId, panelKey) {
|
|
174
|
+
return `/screens/${screenId}/panels/${encodeURIComponent(panelKey)}/states`;
|
|
175
|
+
}
|
|
176
|
+
function placementBody(options, creating) {
|
|
177
|
+
const layout = layoutOf(options);
|
|
178
|
+
const index = options.index != null ? integerOption(options.index, 'index') : undefined;
|
|
179
|
+
return {
|
|
180
|
+
...(creating ? { key: options.key } : {}),
|
|
181
|
+
...(options.name != null ? { name: options.name } : {}),
|
|
182
|
+
...(layout != null ? { layout } : {}),
|
|
183
|
+
...(options.parent != null ? { parentKey: options.parent } : {}),
|
|
184
|
+
...(index != null ? { index } : {}),
|
|
185
|
+
};
|
|
186
|
+
}
|
|
187
|
+
function namedBody(options, withFilterBody) {
|
|
188
|
+
return {
|
|
189
|
+
...(options.key != null ? { key: options.key } : {}),
|
|
190
|
+
...(options.name != null ? { name: options.name } : {}),
|
|
191
|
+
...(withFilterBody && options.content != null ? { content: options.content } : {}),
|
|
192
|
+
...(withFilterBody && options.callbackKeys != null
|
|
193
|
+
? { callbackKeys: options.callbackKeys.split(',').map(item => item.trim()).filter(item => item.length > 0) }
|
|
194
|
+
: {}),
|
|
195
|
+
};
|
|
196
|
+
}
|
|
197
|
+
function layoutOf(options) {
|
|
198
|
+
const layout = {};
|
|
199
|
+
for (const field of ['left', 'top', 'width', 'height']) {
|
|
200
|
+
const value = options[field];
|
|
201
|
+
if (value != null)
|
|
202
|
+
layout[field] = numberOption(value, field);
|
|
203
|
+
}
|
|
204
|
+
return Object.keys(layout).length > 0 ? layout : undefined;
|
|
205
|
+
}
|
|
206
|
+
function numberOption(value, name) {
|
|
207
|
+
const parsed = Number(value);
|
|
208
|
+
if (!Number.isFinite(parsed))
|
|
209
|
+
throw new Error(`${name} 必须是数字`);
|
|
210
|
+
return parsed;
|
|
211
|
+
}
|
|
212
|
+
function integerOption(value, name) {
|
|
213
|
+
const parsed = numberOption(value, name);
|
|
214
|
+
if (!Number.isInteger(parsed) || parsed < 0)
|
|
215
|
+
throw new Error(`${name} 必须是大于等于 0 的整数`);
|
|
216
|
+
return parsed;
|
|
217
|
+
}
|
|
218
|
+
async function run(command, call) {
|
|
219
|
+
try {
|
|
220
|
+
const result = await call();
|
|
221
|
+
(0, output_1.emit)((0, auth_1.globalJson)(command), result, () => console.log(JSON.stringify(result, null, 2)));
|
|
222
|
+
}
|
|
223
|
+
catch (error) {
|
|
224
|
+
(0, client_1.exitOnError)(error);
|
|
225
|
+
}
|
|
226
|
+
}
|
package/dist/index.js
CHANGED
|
@@ -5,6 +5,7 @@ const auth_1 = require("./commands/auth");
|
|
|
5
5
|
const component_1 = require("./commands/component");
|
|
6
6
|
const data_1 = require("./commands/data");
|
|
7
7
|
const debug_1 = require("./commands/debug");
|
|
8
|
+
const elements_1 = require("./commands/elements");
|
|
8
9
|
const screen_1 = require("./commands/screen");
|
|
9
10
|
const skills_1 = require("./commands/skills");
|
|
10
11
|
const update_1 = require("./commands/update");
|
|
@@ -19,6 +20,7 @@ program
|
|
|
19
20
|
.option('--json', '输出 JSON。现在默认就是 JSON,这个参数可以不写');
|
|
20
21
|
(0, auth_1.registerAuth)(program);
|
|
21
22
|
(0, screen_1.registerScreen)(program);
|
|
23
|
+
(0, elements_1.registerElements)(program);
|
|
22
24
|
(0, component_1.registerComponent)(program);
|
|
23
25
|
(0, data_1.registerData)(program);
|
|
24
26
|
(0, debug_1.registerDebug)(program);
|
package/package.json
CHANGED
|
@@ -1,14 +1,35 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: easyv-component-dev
|
|
3
|
-
description: 从零开发一个 EasyV
|
|
3
|
+
description: 从零开发一个 EasyV 组件并上传到平台。按组件规范定义配置项、静态数据、触发事件和接收的动作,打包签名后发布,返回 module 和 version。当官方组件和当前空间已发布的自定义组件都不合适,或需要定制可视化时使用。从 Figma 设计稿还原时,沿用本地已按数据边界拆好的组件,把后期会改的外观和固定文案抽成配置项,交互声明成触发事件。放进大屏交给 easyv-screen-build 或 easyv-screen-edit。开始前先读 easyv-screen-shared。
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# 从零开发 EasyV 组件
|
|
7
7
|
|
|
8
|
+
先读 [easyv-screen-shared](../easyv-screen-shared/SKILL.md)。上传会写到当前登录的空间,执行前向用户确认。
|
|
9
|
+
|
|
8
10
|
组件是 React 组件。配置项、事件和动作都声明在 `config/main.json`,平台据此渲染配置面板和交互选项。
|
|
9
11
|
完整字段说明见 [component-spec.md](references/component-spec.md)。配置项的控件类型、分组和显隐见 [configuration.md](references/configuration.md)。图片、视频等静态资源的上传、配置和拼接见 [assets.md](references/assets.md)。
|
|
10
12
|
|
|
11
|
-
先读 [component-selection.md](../easyv-screen-
|
|
13
|
+
先读 [component-selection.md](../easyv-screen-shared/references/component-selection.md)。命中其中的官方组件时不要从零开发。没有命中的,按那份文档里的顺序查官方组件和空间组件。两边都不合适,再从零开发。
|
|
14
|
+
|
|
15
|
+
## 从设计稿还原
|
|
16
|
+
|
|
17
|
+
只有 [从 Figma 设计稿还原](../easyv-screen-build/SKILL.md) 并且本地 React 工程已经按数据边界拆好组件时,才按这一节写配置和事件。组件边界与本地一致,不要在上传时并成整页或整栏。控件类型、分组和显隐见 [configuration.md](references/configuration.md),资源见 [assets.md](references/assets.md)。
|
|
18
|
+
|
|
19
|
+
配置项按后期只改配置、不改代码来抽,默认值用设计稿上的值。
|
|
20
|
+
|
|
21
|
+
抽成配置项:
|
|
22
|
+
|
|
23
|
+
- 颜色、字体、字号、字重、行高、对齐、间距、圆角、透明度、显隐
|
|
24
|
+
- 可能更换的装饰图和图标。类型用 `image`,值为上传后的相对路径
|
|
25
|
+
- 不跟着数据源变化的文案:固定标题、单位、空态、按钮文字
|
|
26
|
+
- 小数位、千分位,以及组件自己绘制的前后缀
|
|
27
|
+
- 状态阈值和对应颜色,例如超过某值换色
|
|
28
|
+
- 组件自带动画的开关和时长
|
|
29
|
+
|
|
30
|
+
留在数据里:会随业务变化的数值、类目、系列和列表行,写进 `main.data.json` 的 `data` 和 `fields`。画布上的位置和尺寸属于大屏布局。换成另一种结构就不再是这个组件,另做组件。
|
|
31
|
+
|
|
32
|
+
有交互时在 `triggers` 里声明,`value` 与 `emit` 的第一个参数一致。组件只抛出被点击、选中项变化这类事实。需要被大屏反向更新时再声明 `actions`,并监听 `document` 上的 `<value>_<id>`。切页面、显隐和联动由大屏上的自定义事件来配。
|
|
12
33
|
|
|
13
34
|
## 流程
|
|
14
35
|
|
|
@@ -22,7 +43,7 @@ description: 从零开发一个 EasyV 组件并上传到平台。按组件规范
|
|
|
22
43
|
4. 按下面的「easyv-cli」准备打包工具和签名密钥。没装好、密钥没配好就不要执行打包。
|
|
23
44
|
5. `easyv-screen component publish <目录名>`。它会打包、签名并上传;如果平台已有同名组件且版本不比本地高,
|
|
24
45
|
会自动把补丁号加一后重新打包再上传。
|
|
25
|
-
6. 上传结果里 `status` 为 `published`
|
|
46
|
+
6. 上传结果里 `status` 为 `published` 后,把返回的 `module` 和 `version` 交给 `easyv-screen-build` 或 `easyv-screen-edit` 放进大屏。已经在大屏里的实例不会跟着升级。
|
|
26
47
|
|
|
27
48
|
## easyv-cli
|
|
28
49
|
|
|
@@ -1,25 +1,45 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: easyv-screen-build
|
|
3
|
-
description:
|
|
3
|
+
description: 从零到一在 EasyV 上搭建可视化应用。当用户要把大屏、看板或可视化页面建到 EasyV 上时使用;单纯还原 Figma 设计稿时不用。来源可以是 Figma 设计稿,也可以是已有本地工程:来自 Figma 时先在本地用 React 和 Vite 搭出功能并核对,已是本地工程时直接按该工程做成 EasyV 大屏。开始前先读 easyv-screen-shared。接数据交给 easyv-screen-data,配交互交给 easyv-screen-edit。
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# 从零搭建大屏
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
先读 [easyv-screen-shared](../easyv-screen-shared/SKILL.md)。只在要把可视化应用建到 EasyV 上时用这份技能。来源可以是 Figma 设计稿,也可以是已有本地工程。单纯还原设计稿、还不往 EasyV 上搭时,不用这里。
|
|
9
|
+
|
|
10
|
+
来自 Figma 时,先做第 1、2 步,再做第 3 步。已经是本地工程时,直接做第 3 步。
|
|
11
|
+
|
|
12
|
+
## 从 Figma 设计稿还原
|
|
13
|
+
|
|
14
|
+
来自 Figma 时按顺序做。不要拿到稿就创建大屏,也不要切完图就上传组件。已经是本地工程时,跳到第 3 步。
|
|
15
|
+
|
|
16
|
+
### 1. 切图
|
|
17
|
+
|
|
18
|
+
用 [figma-asset-slice](../figma-asset-slice/SKILL.md) 导出。之后只用本次导出目录里的正式素材和 `manifest.json`。位置按清单计算:`left = layout.x - overflow.left`,`top = layout.y - overflow.top`,宽高用导出尺寸折回布局单位。图表、进度条,以及能用选项卡配置出来的样式,按那份技能留给组件,不贴图。
|
|
19
|
+
|
|
20
|
+
### 2. 本地用 React 和 Vite 核对
|
|
21
|
+
|
|
22
|
+
在单独的目录新建 React + Vite 工程,把功能搭出来并对照设计稿核对,再进第三步。这一步只验证效果和组件边界,不执行 `component init`,不上传。工程不要和切图导出目录、`easyv-components` 混在一起。
|
|
23
|
+
|
|
24
|
+
- 素材用第一步的正式文件,按清单摆放。动态文字用文本节点渲染。
|
|
25
|
+
- 按「一块数据、一次交互」拆组件,颗粒度小到每一块还能单独接数据。会单独取数、单独刷新或单独被点选的区域,各自一个组件。同一条数据上的标题、数值、单位、趋势留在同一个组件里,用字段区分。列表和排行让组件接收数组,一行一条,不要按稿上的行数复制组件。不同数据源或不同更新节奏的区域不要收成一个整栏组件。一行里还有多块要分开摆、分开接数的,先拆成并列组件,搭大屏时用组件容器按行重复。
|
|
26
|
+
- 没有数据的背景、外框、标题装饰、图标保持为图片。图表用占位或简单图表把数据形状跑通。官方组件已经能表达的块(图片、翻牌器、选项卡、图表)在本地标出来,第三步直接用官方 module。
|
|
27
|
+
- 点击、选中、页签、换页在本地用回调或状态跑通。换页只用当前页状态,不引入路由库。
|
|
28
|
+
- 把工程跑起来,对照设计稿看位置、间距、素材、文字和交互。对不上就改本地工程。
|
|
9
29
|
|
|
10
|
-
|
|
30
|
+
### 3. 做成 EasyV 大屏
|
|
11
31
|
|
|
12
|
-
|
|
32
|
+
本地对上之后,再上传组件并按「步骤」搭大屏。组件划分保持本地那一版。
|
|
13
33
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
34
|
+
- 先读 [component-selection.md](../easyv-screen-shared/references/component-selection.md)。官方组件能覆盖的用官方组件。覆盖不了的,按 [easyv-component-dev](../easyv-component-dev/SKILL.md) 的「从设计稿还原」写成自定义组件并上传。上传前向用户确认。本地的示例数据写进组件静态数据,让大屏先按稿显示。
|
|
35
|
+
- 交互写在大屏的自定义事件上。组件只抛出本地已经验证过的动作,事件再接到显隐、更新数据或切换面板,见 [custom-events.md](../easyv-screen-shared/references/custom-events.md)。
|
|
36
|
+
- 有多页、整页切换时用动态面板:一页一个状态,导航放在面板外面,用 `switchState` 切换。页内选项卡用 `tabV2`,内容区用面板状态。只有一页时不要加这层面板。面板、状态和根上导航的切换事件可以写进文档;状态里面的组件写不进去,见 [panels-containers.md](../easyv-screen-shared/references/panels-containers.md)。把每个状态要放的组件和本地布局列清楚,交给用户在编辑器里放进对应状态。
|
|
37
|
+
|
|
38
|
+
## 组件从哪来
|
|
39
|
+
|
|
40
|
+
新增组件前先读 [component-selection.md](../easyv-screen-shared/references/component-selection.md)。文档里已有对应 module 的,直接用。没有的,按那份文档里的顺序查官方组件和空间组件。
|
|
41
|
+
|
|
42
|
+
多状态切换、一块区域里按数据行重复组件、多个组件共用一份取数,分别是动态面板、组件容器、数据容器。先读 [panels-containers.md](../easyv-screen-shared/references/panels-containers.md)。从零搭建时把它们写进同一份 `doc.json`:面板和容器放进 `layers` 与 `elements`,`states` 留空数组;过滤器和数据容器写在根上的 `filters`、`dataContainers`。和画布一起一次 `document put`,不要逐个调用 `panel create`、`container create`、`filter create`、`data-container create`。文档创建的面板只带一个空状态;还要更多状态时,文档落库后再用 `panel state create`。建完重新 `document get`,用返回的 `id` 和 `states[].screenId` 写自定义事件。不能往面板或容器里面放组件,也不能新建引用面板。选项卡本身用 `tabV2`,它不包含面板里的各份状态。
|
|
23
43
|
|
|
24
44
|
## 步骤
|
|
25
45
|
|
|
@@ -35,17 +55,8 @@ description: 从零搭建一个 EasyV 可视化大屏。先判断用现成组件
|
|
|
35
55
|
5. `easyv-screen screen apply <id> -f ops.json --if-match <revision>` 一次提交。
|
|
36
56
|
返回 `COMPONENT_CONFIG_INVALID` 时按 `details.elements[].unknownPaths` 重新查路径再提交。
|
|
37
57
|
6. `easyv-screen screen validate <id>` 检查。`ELEMENT_OUT_OF_CANVAS`、`ELEMENT_OVERLAP`、`ELEMENT_HIDDEN` 说明布局有问题,调整后再提交。
|
|
38
|
-
7.
|
|
39
|
-
8.
|
|
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>` 关掉。这次发布只用于查看。
|
|
58
|
+
7. 截图、打开预览或发布链接,按共用规则的「查看和发布」。
|
|
59
|
+
8. 交付时的正式发布也按那一节:先向用户确认,再执行 `screen publish`。
|
|
49
60
|
|
|
50
61
|
## 文档要点
|
|
51
62
|
|
|
@@ -1,13 +1,15 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: easyv-screen-data
|
|
3
|
-
description: 给 EasyV
|
|
3
|
+
description: 给 EasyV 大屏的组件接数据:查已有数据源、新建、修改或删除数据库和 API 连接、看表结构和预览数据、把组件绑定到数据源或填静态数据。当用户要给组件接数据、换数据源、改连接或填静态数据时使用。开始前先读 easyv-screen-shared。
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# 给组件接数据
|
|
7
7
|
|
|
8
|
+
先读 [easyv-screen-shared](../easyv-screen-shared/SKILL.md)。绑定要用大屏 id 和文档 `revision`,没有 id 时按那里找到大屏。
|
|
9
|
+
|
|
8
10
|
## 先看有没有现成的数据源
|
|
9
11
|
|
|
10
|
-
`easyv-screen data source list
|
|
12
|
+
`easyv-screen data source list`,可用 `--type mysql` 这类参数过滤。详情用 `data source get <dataId>`,密码只会显示为 `******`。
|
|
11
13
|
|
|
12
14
|
## 新建数据源
|
|
13
15
|
|
|
@@ -16,19 +18,25 @@ description: 给 EasyV 大屏的组件接数据:查已有数据源、新建数
|
|
|
16
18
|
```
|
|
17
19
|
easyv-screen data source create --name "业务库" --type mysql \
|
|
18
20
|
--addr 10.0.0.8 --port 3306 --username app --database biz \
|
|
19
|
-
--password-env DB_PASSWORD
|
|
21
|
+
--password-env DB_PASSWORD
|
|
20
22
|
```
|
|
21
23
|
|
|
22
24
|
`--type` 常用 `mysql`、`postgresql`、`clickhouse`、`oracle`、`mssql`、`api`、`csv`。
|
|
23
|
-
API 类型用 `--base-url`。建完用 `data source test <dataId
|
|
25
|
+
API 类型用 `--base-url`。建完用 `data source test <dataId>` 确认连通。
|
|
24
26
|
|
|
25
27
|
连接测试、表结构和预览依赖数据源服务。如果返回 `DATASOURCE_SERVICE_UNAVAILABLE`,说明服务地址还没配置,
|
|
26
28
|
告诉用户这一步暂时做不了,数据源本身已经创建。
|
|
27
29
|
|
|
30
|
+
## 修改或删除数据源
|
|
31
|
+
|
|
32
|
+
改名称、地址、端口、账号、库名或 API 地址用 `data source update <dataId>`。类型在创建时确定,更新时不能改。没写上的字段保持原值,不传密码就保留原密码。密码仍然只走 `--password-env` 或 `--password-stdin`。
|
|
33
|
+
|
|
34
|
+
删除用 `easyv-screen data source delete <dataId>`。执行前向用户确认。
|
|
35
|
+
|
|
28
36
|
## 确认字段
|
|
29
37
|
|
|
30
|
-
`data source tables <dataId
|
|
31
|
-
`data source preview <dataId> --sql "select ..."
|
|
38
|
+
`data source tables <dataId>` 看有哪些表,`data source columns <dataId> --table <表名>` 看字段,
|
|
39
|
+
`data source preview <dataId> --sql "select ..."` 看样本。用样本核对组件需要的字段。
|
|
32
40
|
|
|
33
41
|
## 绑定到组件
|
|
34
42
|
|
|
@@ -46,8 +54,10 @@ API 类型用 `--base-url`。建完用 `data source test <dataId> --json` 确认
|
|
|
46
54
|
}
|
|
47
55
|
```
|
|
48
56
|
|
|
49
|
-
用 `easyv-screen screen apply <id> -f ops.json --if-match <revision
|
|
57
|
+
用 `easyv-screen screen apply <id> -f ops.json --if-match <revision>` 提交。
|
|
50
58
|
`data_id` 必须是当前团队的数据源,否则校验报 `DATA_SOURCE_NOT_FOUND`。
|
|
51
59
|
|
|
52
60
|
只用静态数据时,用 `setComponentStaticData`,`data` 传对象数组,`fields` 传字段说明。
|
|
53
61
|
改回静态数据用 `element.unbindData`。
|
|
62
|
+
|
|
63
|
+
数据容器是大屏上单独的一份取数。从零搭建时写进文档一次 `document put`。改已有大屏时用 `easyv-screen data-container` 新建、改名或删除。`element.bindContainer` 和 `element.bindFilter` 仍然不能调用,组件自己的数据源继续用 `element.bindData`。区别见 [panels-containers.md](../easyv-screen-shared/references/panels-containers.md)。
|
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: easyv-screen-debug
|
|
3
|
-
description: 排查 EasyV
|
|
3
|
+
description: 排查 EasyV 大屏上单个组件的配置并判断原因:数据绑定、它触发了谁、谁触发了它。当用户反馈点击没反应、联动不对、数据不对或组件不显示时使用。不显示要看文档里的显隐,这条命令不返回显隐。开始前先读 easyv-screen-shared。
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# 排查大屏
|
|
7
7
|
|
|
8
|
+
先读 [easyv-screen-shared](../easyv-screen-shared/SKILL.md)。没有大屏 id 时按那里找到大屏。组件 key 从 `screen document get` 的文档里取。
|
|
9
|
+
|
|
8
10
|
`easyv-screen debug` 只取出一个组件的配置,不下结论。拿到数据后自己判断原因,再用一句人话告诉用户。
|
|
9
11
|
|
|
10
12
|
下面这些已经有别的命令,不要再用 debug 去要:
|
|
@@ -34,14 +36,16 @@ easyv-screen debug <screenId> <key>
|
|
|
34
36
|
- `data.staticData`:文档里的静态数据。绑了数据源时它也可能还在。
|
|
35
37
|
- `outgoing`:这个组件自己的事件,结构与文档里的 `interactions.events` 相同。动作的 `component` 是它指向的目标。
|
|
36
38
|
- `incoming`:别的组件里,动作 `component` 指向它的事件。每项的 `key` 是来源组件。
|
|
37
|
-
- `refs`:上面这些事件里出现的 `$component(...)`
|
|
38
|
-
- `location
|
|
39
|
+
- `refs`:上面这些事件里出现的 `$component(...)`、`$panel(...)`、`$container(...)`、`$state(...)`、`$super(...)` 引用,解析成文档 key、名称和 `found`。`found` 为 false 表示文档里没有这个对象。
|
|
40
|
+
- `location`:组件在某个面板或容器的状态里时才有,含 `parentKey`、`parentKind`、`stateKey`、`stateName`。没有该字段就是在大屏根上。
|
|
41
|
+
|
|
42
|
+
动态面板、组件容器、过滤器和数据容器在文档里的 key,见 [panels-containers.md](../easyv-screen-shared/references/panels-containers.md)。`dataBinding` 为 null 时,画面上的数据仍可能来自数据容器或组件容器下发。文档能看到数据容器在不在,看不到它和组件的绑定。
|
|
39
43
|
|
|
40
44
|
## 怎么判断
|
|
41
45
|
|
|
42
46
|
按用户的具体问题看对应的字段,不要套固定的故障类型。
|
|
43
47
|
|
|
44
|
-
- 点击没反应:看 `outgoing` 里有没有该触发方式、动作有没有目标、`refs` 里目标是否 `found`。只关心一种触发就加 `--trigger
|
|
48
|
+
- 点击没反应:看 `outgoing` 里有没有该触发方式、动作有没有目标、`refs` 里目标是否 `found`。只关心一种触发就加 `--trigger`。切面板时动作是 `switchState`,`stateId` 形如 `$state(<子屏 id>)`,字段见 [custom-events.md](../easyv-screen-shared/references/custom-events.md)。
|
|
45
49
|
- 被别的组件影响:看 `incoming`,来源是每一项的 `key`。
|
|
46
50
|
- 数据不对:先看 `data`。绑定了数据源再按 `data_id` 查连接和预览。
|
|
47
51
|
- 不显示:debug 不返回显隐。用 `screen document get` 看该 key 和祖先图层的 `visible`。
|
|
@@ -1,27 +1,31 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: easyv-screen-edit
|
|
3
|
-
description:
|
|
3
|
+
description: 修改已经存在的 EasyV 大屏:添加或删除组件、改配置和名称、批量修改、配置交互、调整显隐图层和成组、升级组件版本,以及发布、取消发布和截图。当用户要改大屏、加组件、改布局、做点击联动、发布或查看已有大屏时使用。开始前先读 easyv-screen-shared。接数据交给 easyv-screen-data。
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# 修改大屏
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
先读 [easyv-screen-shared](../easyv-screen-shared/SKILL.md)。没有大屏 id 时按那里找到。然后 `easyv-screen screen document get <id> -o doc.json` 拿到当前文档和 `revision`。
|
|
9
9
|
|
|
10
|
-
往大屏里新增组件时,先读 [component-selection.md](../easyv-screen-
|
|
10
|
+
往大屏里新增组件时,先读 [component-selection.md](../easyv-screen-shared/references/component-selection.md),再写 `addComponent`。
|
|
11
11
|
|
|
12
12
|
## 用原子操作做局部修改
|
|
13
13
|
|
|
14
14
|
把操作写进 `ops.json`,格式 `{ "operations": [ ... ] }`,然后:
|
|
15
15
|
|
|
16
16
|
```
|
|
17
|
-
easyv-screen screen apply <id> -f ops.json --if-match <revision>
|
|
17
|
+
easyv-screen screen apply <id> -f ops.json --if-match <revision>
|
|
18
18
|
```
|
|
19
19
|
|
|
20
20
|
支持的操作(元素和图层都用文档 key):
|
|
21
21
|
|
|
22
22
|
| 操作 | 作用 | 关键字段 |
|
|
23
23
|
| --- | --- | --- |
|
|
24
|
-
| `addComponent` |
|
|
24
|
+
| `addComponent` | 新增组件,其余用组件默认配置。`parentKey` 只能是已有分组 | `key` `module` `version` `name` `layout` `configPatches` `data` `parentKey` `index` |
|
|
25
|
+
| `addPanel` | 新增动态面板,自带一个空状态 | `key` `name` `layout` `parentKey` `index` |
|
|
26
|
+
| `addContainer` | 新增组件容器,自带一个空子屏。名称最长 50 | `key` `name` `layout` `parentKey` `index` |
|
|
27
|
+
| `addFilter` | 在根屏上新增过滤器 | `key` `name` `content` `callbackKeys` |
|
|
28
|
+
| `addDataContainer` | 在根屏上新增数据容器,不占图层 | `key` `name` |
|
|
25
29
|
| `removeComponent` | 删除组件 | `key` |
|
|
26
30
|
| `setComponentConfig` | 按路径改配置 | `key` `configPatches`(`[{ path, value }]`) |
|
|
27
31
|
| `setComponentLayout` | 改位置尺寸 | `key` `layout`(`left` `top` `width` `height`) |
|
|
@@ -33,19 +37,21 @@ easyv-screen screen apply <id> -f ops.json --if-match <revision> --json
|
|
|
33
37
|
| `element.bindData` | 绑定数据源 | `key` `dataType` `data`(含 `data_id`) |
|
|
34
38
|
| `element.unbindData` | 改回静态数据 | `key` |
|
|
35
39
|
| `setLayerVisible` | 显隐 | `key` `visible` |
|
|
36
|
-
| `moveLayer` |
|
|
40
|
+
| `moveLayer` | 移动图层。`parentKey` 只能是已有分组,或空着移到根上 | `key` `parentKey` `index` |
|
|
37
41
|
| `groupLayers` | 成组 | `keys` `groupKey`(`g-` 开头) `name` |
|
|
38
42
|
| `ungroupLayer` | 解散分组 | `key` |
|
|
39
43
|
| `upgradeComponentVersion` | 升级组件版本 | `key` `version` |
|
|
40
44
|
| `screen.updateMeta` | 改大屏名称 | `name` |
|
|
41
45
|
|
|
42
|
-
改完跑 `screen validate <id
|
|
46
|
+
改完跑 `screen validate <id>`。
|
|
47
|
+
|
|
48
|
+
查数据源、新建或修改连接、看表和预览用 `easyv-screen-data`。表里的 `setComponentStaticData`、`element.bindData`、`element.unbindData` 只负责把结果写进文档。
|
|
43
49
|
|
|
44
50
|
## 交互事件
|
|
45
51
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
52
|
+
自定义事件的字段、触发方式和动作写在 [custom-events.md](../easyv-screen-shared/references/custom-events.md)。切换已有动态面板的状态用动作 `switchState`,示例也在那份说明里。
|
|
53
|
+
|
|
54
|
+
改已经存在的大屏时,动态面板、状态、过滤器、组件容器、数据容器用单独的命令增删改,不要为了改一个名称去重写整份文档。从零搭建仍把它们写进文档一次提交。命令和限制见 [panels-containers.md](../easyv-screen-shared/references/panels-containers.md)。状态里的组件不能作为 `apply` 的目标,也不能放进面板或容器。
|
|
49
55
|
|
|
50
56
|
## 改配置
|
|
51
57
|
|
|
@@ -60,3 +66,7 @@ easyv-screen screen apply <id> -f ops.json --if-match <revision> --json
|
|
|
60
66
|
## 批量修改
|
|
61
67
|
|
|
62
68
|
多个组件的修改放进同一个 `operations` 数组一次提交,任何一条不通过整批都不落库。
|
|
69
|
+
|
|
70
|
+
## 发布、取消发布和截图
|
|
71
|
+
|
|
72
|
+
截图、打开预览或发布链接、临时发布后关掉,以及交付时的正式发布,按共用规则的「查看和发布」。取消公开发布用 `easyv-screen screen unpublish <id>`,执行前向用户确认。
|