@easyv/screen-cli 0.1.5 → 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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@easyv/screen-cli",
3
- "version": "0.1.5",
3
+ "version": "0.1.6",
4
4
  "description": "用自然语言驱动 EasyV 大屏的命令行工具:搭建、修改、排查,以及从零开发组件",
5
5
  "bin": {
6
6
  "easyv-screen": "bin/easyv-screen.js"
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: easyv-component-dev
3
- description: 从零开发一个 EasyV 组件并上传到平台。按组件规范定义配置项、静态数据、触发事件和接收的动作,打包签名后发布,返回 module 和 version。当官方组件和当前空间已发布的自定义组件都不合适,或需要定制可视化时使用。放进大屏交给 easyv-screen-build 或 easyv-screen-edit。开始前先读 easyv-screen-shared。
3
+ description: 从零开发一个 EasyV 组件并上传到平台。按组件规范定义配置项、静态数据、触发事件和接收的动作,打包签名后发布,返回 module 和 version。当官方组件和当前空间已发布的自定义组件都不合适,或需要定制可视化时使用。从 Figma 设计稿还原时,沿用本地已按数据边界拆好的组件,把后期会改的外观和固定文案抽成配置项,交互声明成触发事件。放进大屏交给 easyv-screen-build 或 easyv-screen-edit。开始前先读 easyv-screen-shared。
4
4
  ---
5
5
 
6
6
  # 从零开发 EasyV 组件
@@ -12,6 +12,25 @@ description: 从零开发一个 EasyV 组件并上传到平台。按组件规范
12
12
 
13
13
  先读 [component-selection.md](../easyv-screen-shared/references/component-selection.md)。命中其中的官方组件时不要从零开发。没有命中的,按那份文档里的顺序查官方组件和空间组件。两边都不合适,再从零开发。
14
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>`。切页面、显隐和联动由大屏上的自定义事件来配。
33
+
15
34
  ## 流程
16
35
 
17
36
  1. `easyv-screen component init` 在当前目录准备工程 `./easyv-components`(已存在则复用)。
@@ -1,11 +1,39 @@
1
1
  ---
2
2
  name: easyv-screen-build
3
- description: 从零搭建一个 EasyV 可视化大屏。先判断用现成组件还是从零开发组件,再创建大屏、写入画布和组件、校验布局。当用户要新建大屏、做一块看板或可视化页面时使用。接数据交给 easyv-screen-data,配交互交给 easyv-screen-edit。
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
- 先读 [easyv-screen-shared](../easyv-screen-shared/SKILL.md),再按下面搭建。
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
+ - 把工程跑起来,对照设计稿看位置、间距、素材、文字和交互。对不上就改本地工程。
29
+
30
+ ### 3. 做成 EasyV 大屏
31
+
32
+ 本地对上之后,再上传组件并按「步骤」搭大屏。组件划分保持本地那一版。
33
+
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)。把每个状态要放的组件和本地布局列清楚,交给用户在编辑器里放进对应状态。
9
37
 
10
38
  ## 组件从哪来
11
39
 
@@ -34,6 +34,7 @@ description: 使用 easyv-screen 命令前先遵守的共用规则:确认工
34
34
 
35
35
  两种以上场景都会用到的平台事实写在 `references/`。用到再读,不要整份预读。以后新增这类说明,放在这个目录并在下面加一行。
36
36
 
37
+ - 从 Figma 设计稿还原大屏时,读 [easyv-screen-build](../easyv-screen-build/SKILL.md) 的「从 Figma 设计稿还原」:先切图,再在本地用 React 和 Vite 验证,最后才上传组件并搭建大屏。
37
38
  - 新增组件前读 [component-selection.md](references/component-selection.md)。表里已有的 module 直接用;没有的按那份文档里的顺序查官方组件和空间组件。
38
39
  - 配置交互,或排查点击、切换面板时,读 [custom-events.md](references/custom-events.md)。
39
40
  - 动态面板、引用面板、组件容器、数据容器怎么认、命令能改什么,读 [panels-containers.md](references/panels-containers.md)。
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: figma-asset-slice
3
- description: 用于从 Figma 大屏设计稿中导出适配 EasyV 的可复用资产,整合切图与组装规律、Figma 导出限制、EasyV 组件补位及 Fable 5.2 产物中的可借鉴规则。
3
+ description: 用于从 Figma 大屏设计稿中导出适配 EasyV 的可复用资产,整合切图与组装规律、Figma 导出限制、EasyV 组件补位及 Fable 5.2 产物中的可借鉴规则。还原到 EasyV 时,切完按 easyv-screen-build 的「从 Figma 设计稿还原」继续:先在本地用 React 和 Vite 核对,再上传组件并搭建大屏。
4
4
  ---
5
5
  # figma-asset-slice
6
6
 
@@ -158,6 +158,8 @@ description: 用于从 Figma 大屏设计稿中导出适配 EasyV 的可复用
158
158
 
159
159
  ## 切完之后
160
160
 
161
+ 还原到 EasyV 时,这一步只提供素材和清单。下一步在本地用 React 和 Vite 按清单搭出画面并核对组件拆分,确认后再上传。流程见 [easyv-screen-build](../easyv-screen-build/SKILL.md) 的「从 Figma 设计稿还原」。
162
+
161
163
  - 清单里记录:类型、来源节点、格式与导出倍率、布局框、导出尺寸、四边溢出、去掉的背景模糊半径;多尺寸标本注明布局档位(1x / 1.5x / 2x …)和该档宽高。这份清单是给后续对齐和组装用的机器可读记录,不是要上传的素材本身。
162
164
  - 独有项去向与重复引用、独立装饰的关系/对齐/复用、单格用途/间距/拼装及固定整组例外、整壳与标题的互斥替代方案、内嵌位图的尺寸/清晰度依据/处理与前后体积,写入清单中明确可展示的 `specialJudgments` 或 `notes`。不要求改预览脚本或强制引入新 schema;不得只有生成者脑中知道的装配约定。
163
165
  - 图表区域和进度条留给图表组件,不要用切图去贴。