@jnrs/lingshu-smart

✨ 介绍

巨能（JNRS）前端 2D 数字孪生库，灵枢智造。基于 LeaferJS 引擎构建，提供完整的 2D 数字孪生解决方案。

核心功能

| 功能 | 说明 | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 编辑器模式 | LingshuSmartEditor — 方案可视化编辑，支持拖拽布局、设备配置、图层管理、方案保存/预览 | | 运行看板 | LingshuSmartPreview — 方案运行看板，支持 WebSocket 实时驱动设备动画、交互事件（点击/拖拽/右键菜单） | | 设备模型 | 机床、机器人（单关节/双关节）、RGV、装载站、打标机、清洗机、轨道拖链、资源库、托盘等 | | 设备运转 | 灯光、进度条、入口动画、工位槽资源增删、坐标/角度/货叉控制 | | 坐标转换 | transRuntimeToPixel / transPercentToPixel — 物理坐标与像素坐标互转 | | WebSocket 代理器 | WsProxy — 声明式字段映射将后端 socket 数据桥接为 operating 驱动设备动画；支持内置请求器/外接注入两种数据源、direct/proxy 请求模式、自动连接开关、按 type 分类代理配置及配置导出/导入 |

💻 技术栈

TypeScript、Vue3 生态、LeaferJS

🧩 安装教程

pnpm add @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'

编辑器模式

<LingshuSmartEditor :actions="{ loadCases, saveCases, handlePreview, handleExit }" />

运行看板模式

<LingshuSmartPreview
  ref="previewRef"
  :case-uuid="currentCaseId"
  :actions="{ loadCases, onTap, onMenuTap, onDragEnd }"
/>

详细文档请查看 AGENTS.md

🐛 调试功能

本库内置了全局调试系统，支持运行时动态配置日志等级、渲染效果和交互状态，适用于开发环境排查问题或生产环境现场调试。

调试模式触发

在编辑器或预览页面中，500ms 内快速点击主容器（#lingshu-smart）10 次即可触发调试模式确认对话框，确认后打开调试配置面板。此操作类似 Android 系统的"开发者模式"快捷入口。

该触发方式基于 DOM 原生 click 事件绑定，不受"禁止所有交互"配置的影响。

调试配置面板

| 配置项 | 说明 | | ------------- | -------------------------------------------------------------------------------------------------------- | | 日志显示等级 | none（静默）/ error / warn / info / log（全部显示）/ operating（全部显示 + UI 模型操作追踪） | | 显示内外阴影 | 全局开关所有 Leafer 图形的 shadow / innerShadow 效果（含 ShadowCanvas 绘制阴影） | | 启用全局动画 | 全局开关循环动画（如灯闪烁、入口通道动画），关闭后保留静态状态（如灯颜色保持不变），不影响一次性动画 | | 全局 FPS | 限制 Leafer 渲染帧率：auto（不限制）/ 30 / 60 / 120 FPS | | 禁止所有交互 | 通过 CSS pointer-events: none 禁用主容器内所有子元素交互，调试模式开关不受此限制 | | 语言/Language | 切换调试面板和性能统计的显示语言：中文 / English | | 性能统计 | 显示页面运行开始时间、持续运行时长、WebSocket 消息接收次数和数据量 |

日志系统

日志工具 createLogger(tag) 创建带标签的 Logger 实例，输出格式为 [等级:Tag] 消息内容：

• log / info / operating 级别：使用彩色单徽章样式（LEVEL:Tag 合并显示）
• warn / error 级别：保留浏览器默认样式，以纯文本前缀显示

import { createLogger, setLogLevel, type LogLevel } from '@jnrs/lingshu-smart/utils/logger'

const logger = createLogger('MyModule')
logger.log('模型已加载, uuid=%s', uuid) // LOG:MyModule 模型已加载, uuid=xxx
logger.warn('配置缺失: %s', key) // [WARN:MyModule] 配置缺失: xxx
logger.operating('执行操作, data=%o', data) // OPERATING:MyModule 执行操作, data={...}

// 代码层面设置日志等级（优先级低于调试面板的运行时配置）
setLogLevel('warn' as LogLevel) // 仅显示 warn + error

operating 日志级别

operating 是最详细的日志级别，用于追踪 UI 模型的操作指令。在 ModelAbs.handleOperation 和 ComponentAbs.handleOperation 中自动埋点，记录模型的 className、uuid、businessId 和接收到的 operating 数据，便于追溯 WebSocket 数据与前端 UI 动作的对应关系，定位问题是后端数据返回有误还是前端 UI 显示有误。

性能统计

通过 trackWebSocketMessage(data) 记录 WebSocket 消息接收，在调试面板中实时显示运行时长和数据接收量：

import { trackWebSocketMessage } from '@jnrs/lingshu-smart/utils/performance-stats'

// 在 WebSocket onmessage 回调中调用
ws.onmessage = (event) => {
  trackWebSocketMessage(event.data)
  // ... 业务处理
}

配置持久化

所有调试配置通过 localStorage 持久化存储，key 为 @jnrs/lingshu-smart/debug：

{
  "logLevel": "log",
  "shadowsEnabled": true,
  "animationsEnabled": true,
  "fpsMode": "auto",
  "interactionsDisabled": false,
  "locale": "zhCn"
}

页面刷新后自动恢复上次配置。如需重置，点击调试面板中的"恢复默认"按钮。

🌐 国际化

本库内置 vue-i18n 国际化支持，默认提供中文（zhCn）和英文（en）两种语言，涵盖调试面板、性能统计等模块。

在宿主项目中切换语言

通过 useDebugStore 的 setLocale 方法切换语言，切换后库内所有组件文本实时更新：

import { useDebugStore } from '@jnrs/lingshu-smart/stores'

const debugStore = useDebugStore()

// 切换为英文
debugStore.setLocale('en')

// 切换为中文
debugStore.setLocale('zhCn')

自定义或扩展翻译

如需覆盖现有翻译或添加新的语言，通过 vue-i18n 的 mergeLocaleMessage 合并：

import i18n from '@jnrs/lingshu-smart/locales/i18next'

// 覆盖中文翻译
i18n.global.mergeLocaleMessage('zhCn', {
  perf: {
    panelButton: '监控面板'
  }
})

// 添加新语言
i18n.global.mergeLocaleMessage('ja', {
  perf: {
    title: 'ライブモニター',
    status: '実行中'
  }
})

与宿主项目 i18n 集成

如果宿主项目已使用 vue-i18n，可选择以下方案：

1. 独立模式（推荐）：库内部 i18n 实例独立运行，通过 setLocale 同步语言，互不干扰。
2. 共享模式：将库的 messages 合并到宿主项目的 i18n 实例中，统一管理。

// 方案1：监听宿主语言变化，同步到库
import { watch } from 'vue'
import { useDebugStore } from '@jnrs/lingshu-smart/stores'

const debugStore = useDebugStore()
watch(
  () => hostI18n.global.locale.value,
  (lang) => {
    debugStore.setLocale(lang === 'zh-CN' ? 'zhCn' : 'en')
  }
)