@jnrs/lingshu-smart 2.2.27 → 2.2.29

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

@@ -5,6 +5,7 @@
 巨能前端 2D 数字孪生库，灵枢智造。
 
 - 2D 数字孪生编辑器、运行看板
+- ...
 
 ## 💻 技术栈
 
@@ -19,45 +20,8 @@ pnpm add @jnrs/lingshu-smart
 ## 🔍 使用示例
 
 ```typescript
-import type { *** } from '@jnrs/lingshu-smart'
-import { LingshuSmartEditor } from '@jnrs/lingshu-smart/components'
+import type { ILayerOperating } from '@jnrs/lingshu-smart'
+import { LingshuSmartPreview, LingshuSmartEditor } from '@jnrs/lingshu-smart/components'
 ```
 
-## 📋 API
-
-#### @jnrs/lingshu-smart/components 模块
-
-Vue 组件
-
-- LingshuSmartEditor 编辑器组件
-
-| 属性名  | 描述     | 类型            | 默认值 |
-| ------- | -------- | --------------- | ------ |
-| actions | 事件处理 | `EditorActions` | {}     |
-
-```
-interface EditorActions {
-  /**
-   * 加载案例列表
-   * @returns Promise<ICase[]>
-   */
-  loadCases?: (id?: string) => Promise<ICase[]>
-
-  /**
-   * 保存方案列表
-   */
-  saveCases?: (cases?: ICase[]) => void
-
-  /**
-   * 跳转到预览页面
-   */
-  handlePreview?: (currentCase?: ICase) => void
-
-  /**
-   * 退出当前页面
-   */
-  handleExit?: () => void
-}
-```
-
-详细文档请查看 `AGENTS.md`
+详细文档请查看 [AGENTS.md](./AGENTS.md)