@jnrs/lingshu-smart 2.2.28 → 2.2.30

package/AGENTS.md

@@ -74,7 +74,7 @@ const handleExit = () => {
 import { ref, computed, onMounted } from 'vue'
 import type { ICase, ILayer, ILayerOperating, InteractiveUi } from '@/types'
 import { EnumModel } from '@/types'
-import { transRuntimeToPixel } from '@/utils'
+import { transRuntimeToPixel, transPercentToPixel } from '@/utils'
 import LingshuSmartPreview from '@/components/preview/index.vue'
 
 const lingshuSmartPreviewRef = ref()
@@ -305,7 +305,7 @@ operating({
     color: payload.status === 2 ? 'green' : '#424242',
     blinking: payload.status === 2
   },
-  x: transRuntimeToPixel(payload.x, 1, 'width') // 沿轨道移动时需转换
+  x: transPercentToPixel(payload.x, 2, 'width') // 沿轨道移动时需转换
 })
 ```
 
@@ -320,7 +320,7 @@ operating({
     color: payload.status === 2 ? 'green' : '#424242',
     blinking: payload.status === 2
   },
-  x: transRuntimeToPixel(payload.x, 1, 'width'),
+  x: transPercentToPixel(payload.x, 2, 'width'),
   j1: payload.j1, // 一级关节角度（度）
   currentFixture: payload.currentFixture // EnumResourceType.PALLET | TOOL
 })
@@ -337,7 +337,7 @@ operating({
     color: payload.status === 0 ? '#f30' : '#424242'
   },
   currentFixture: payload.currentFixture,
-  x: transRuntimeToPixel(payload.x, 1, 'width'),
+  x: transPercentToPixel(payload.x, 2, 'width'),
   j1: payload.j1,
   j2: payload.j2
 })
@@ -392,10 +392,10 @@ operating({
   id: payload.id,
   rawData: payload,
   light: { color: payload.lightColor, blinking: payload.blinking },
-  x: transRuntimeToPixel(payload.x, 1, 'width'),
+  x: transPercentToPixel(payload.x, 2, 'width'),
   j1: payload.j1, // 旋转角度
-  forkXY: payload.forkXY, // 货叉横向移动比例 0~1
-  forkZ: payload.forkZ // 货叉升降比例 0~1
+  forkXY: payload.forkXY, // 货叉进出移动比例 [−1,1]
+  forkZ: payload.forkZ // 货叉升降比例 [0,1]
 })
 ```
 
@@ -423,6 +423,18 @@ const pixelX = transRuntimeToPixel(payload.x, 1, 'width')
 const pixelY = transRuntimeToPixel(payload.y, 1, 'height')
 ```
 
+### 百分比转换为像素数值
+
+后端推送的 `x` / `y` 通常为**百分比数值**（范围通常为[-1,1]），画布使用**像素坐标**。转换公式：
+
+```typescript
+import { transPercentToPixel } from '@jnrs/lingshu-smart'
+
+// 宽方向：pixel = percentVal * scene.width
+const pixelX = transPercentToPixel(payload.x, 2, 'width')
+const pixelY = transPercentToPixel(payload.y, 1, 'height')
+```
+
 **前提：** 方案 `IScene` 中需配置 `runtime_width` / `runtime_height`。该函数读取 `useEditorStore().scene`，预览页需确保场景数据已加载。
 
 ### WebSocket 接入示例
@@ -559,14 +571,14 @@ type ILayerOperating =
 
 #### IRGVOperating
 
-| 属性       | 类型                 | 说明                 |
-| ---------- | -------------------- | -------------------- |
-| `light`    | `ILightOperating`    | 双灯同步更新         |
-| `x`        | `number`             | 沿轨道位移（像素）   |
-| `j1`       | `number`             | 车体旋转角度（度）   |
-| `forkXY`   | `number`             | 货叉横向移动比例 0~1 |
-| `forkZ`    | `number`             | 货叉升降比例 0~1     |
-| `resource` | `IResourceOperating` | 托盘/刀具工位槽      |
+| 属性       | 类型                 | 说明                      |
+| ---------- | -------------------- | ------------------------- |
+| `light`    | `ILightOperating`    | 双灯同步更新              |
+| `x`        | `number`             | 沿轨道位移（像素）[0,1]   |
+| `j1`       | `number`             | 车体旋转角度（度）[0,360] |
+| `forkXY`   | `number`             | 货叉进出移动比例 [−1,1]   |
+| `forkZ`    | `number`             | 货叉升降比例 [0,1]        |
+| `resource` | `IResourceOperating` | 托盘/刀具工位槽           |
 
 #### IRailOperating
 
@@ -666,6 +678,7 @@ type ILayerOperating =
 | `transPercentAndPixel(val, size, precision?, getPercent?)` | 百分比 ↔ 像素                                       |
 | `transFraction(val, size)`                                 | 百分比转小数                                         |
 | `transRuntimeToPixel(val, precision?, type?)`              | 运行时坐标 → 像素（依赖 scene.runtime_width/height） |
+| `transPercentToPixel(val, precision?, type?)`              | 百分比数值 → 像素（依赖 scene.width/height）         |
 
 ---
 
@@ -673,7 +686,7 @@ type ILayerOperating =
 
 1. **编辑器 vs 预览：** 编辑模式配置 `EditorActions`；预览模式配置 `PreviewActions` + `onMessage` → `operating`
 2. **ID 匹配：** `operating` 的 `id` 必须与方案图层 `rawData.id` 一致，否则静默失败（在前端层面该值即为编辑器组件中业务数据配置中必填项 id 的值，需根据后端预先提供的设备 id 在编辑器中进行配置）
-3. **坐标系：** 轨道类设备的 `x` 通常需 `transRuntimeToPixel` 转换；`IRailOperating.x` 直接使用像素
+3. **坐标系：** 轨道类设备的 `x` 通常需 `transPercentToPixel` 转换；`IRailOperating.x` 直接使用像素
 4. **资源消息：** `Resource` 类型不对应独立图层，通过目标设备的 `resource` 字段操作工位槽
 5. **引擎生命周期：** 组件卸载时自动 `destroyContainer`；手动集成需自行销毁
 6. **类型安全：** 所有 API 均导出 TypeScript 类型，推荐 `import type { ILayerOperating, EnumModel } from '@jnrs/lingshu-smart'`

package/README.md

@@ -2,14 +2,21 @@
 
 ## ✨ 介绍
 
-巨能前端 2D 数字孪生库，灵枢智造。
+巨能前端 2D 数字孪生库，灵枢智造。基于 LeaferJS 引擎构建，提供完整的 2D 数字孪生解决方案。
 
-- 2D 数字孪生编辑器、运行看板
-- ...
+### 核心功能
+
+| 功能       | 说明                                                         |
+| ---------- | ------------------------------------------------------------ |
+| 编辑器模式 | `LingshuSmartEditor` — 方案可视化编辑，支持拖拽布局、设备配置、图层管理、方案保存/预览 |
+| 运行看板   | `LingshuSmartPreview` — 方案运行看板，支持 WebSocket 实时驱动设备动画、交互事件（点击/拖拽/右键菜单） |
+| 设备模型   | 机床、机器人（单关节/双关节）、RGV、装载站、打标机、清洗机、轨道拖链、资源库等 |
+| 设备运转   | 灯光、进度条、入口动画、工位槽资源增删、坐标/角度/货叉控制 |
+| 坐标转换   | `transRuntimeToPixel` / `transPercentToPixel` — 物理坐标与像素坐标互转 |
 
 ## 💻 技术栈
 
-TypeScript、Vue3 生态、LeaferJs
+TypeScript、Vue3 生态、LeaferJS
 
 ## 🧩 安装教程
 
@@ -20,8 +27,25 @@ pnpm add @jnrs/lingshu-smart
 ## 🔍 使用示例
 
 ```typescript
-import type { ILayerOperating } from '@jnrs/lingshu-smart'
+import type { ILayerOperating, ILayer, ICase } from '@jnrs/lingshu-smart'
 import { LingshuSmartPreview, LingshuSmartEditor } from '@jnrs/lingshu-smart/components'
+import { transRuntimeToPixel, transPercentToPixel } from '@jnrs/lingshu-smart'
+```
+
+### 编辑器模式
+
+```vue
+<LingshuSmartEditor :actions="{ loadCases, saveCases, handlePreview, handleExit }" />
+```
+
+### 运行看板模式
+
+```vue
+<LingshuSmartPreview
+  ref="previewRef"
+  :case-uuid="currentCaseId"
+  :actions="{ loadCases, onTap, onMenuTap, onDragEnd }"
+/>
 ```
 
-详细文档请查看 `AGENTS.md`
+详细文档请查看 [AGENTS.md](./AGENTS.md)