@syhr/sy-threed-graph 1.0.0-bate4

package/README.md

@@ -0,0 +1,226 @@
+# @syhr/sy-threed-graph
+
+一个基于 ThreeJs 的三维图形展示工具。
+
+## 特性
+
+- 🎨 基于 ThreeJs 的强大三维图形展示能力
+- 🔧 支持多种三维模型
+- 📱 响应式设计，支持移动端
+- 🎯 完整的 TypeScript 支持
+- 📦 多种模块格式支持（ES、UMD、CommonJS）
+- 🔌 Vue 3 插件化架构
+- 🛡️ 安全的全局属性处理，避免变量冲突
+- 🔄 实时数据更新和 WebSocket 支持
+- 🎛️ 可定制的错误处理和回调机制
+- 🚀 高性能渲染和批量更新
+- 🎨 多层级显示控制
+- 📡 支持自定义 API 和事件总线注入
+
+## 安装
+
+```bash
+npm install @syhr/sy-threed-graph
+```
+
+### Peer Dependencies
+
+确保你的项目已安装以下 peer dependencies：
+
+```bash
+# 必需依赖
+npm install vue@^3.0.0 element-plus@^2.0.0 lodash-es@^4.17.0 three@^0.184.0 three-edit-cores@^0.0.15
+
+# 可选依赖（根据需要安装）
+npm install pinia@^2.0.0 vue-router@^4.0.0
+```
+
+## 使用
+
+### 全局注册（推荐）
+
+```javascript
+import { createApp } from 'vue';
+import SyGraph from '@syhr/sy-threed-graph';
+import '@syhr/sy-threed-graph/style';
+
+const app = createApp(App);
+app.use(SyGraph);
+app.mount('#app');
+```
+
+### 局部使用
+
+```javascript
+import { SyThreedGraph } from '@syhr/sy-threed-graph';
+
+export default {
+  components: {
+    SyThreedGraph,
+  },
+};
+```
+
+### 在模板中使用
+
+```vue
+<template>
+  <div>
+    <SyThreedGraph
+      ref="graphRef"
+      :id="sceneId"
+      :data="sceneData"
+      :url="graphUrl"
+      :token="token"
+      :socketUrl="socketUrl"
+      @loaded="handleLoaded"
+      @graph-event="handleGraphEvent"
+    />
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import { SyGraph } from '@syhr/sy-graph';
+const sceneId = ref('');
+const sceneData = ref({});
+const graphRef = ref();
+const graphUrl = ref('path/to/your/graph.json');
+const token = ref('');
+const socketUrl = ref('');
+
+const handleLoaded = (stage) => {
+  console.log('Graph loaded:', stage);
+  // 可以通过 stage 进行图纸操作
+};
+
+// 图纸事件, 点击等
+const handleGraphEvent = (errorInfo) => {
+  console.error('Graph error:', errorInfo);
+};
+
+// 组件方法调用示例
+const toggleLevel = () => {
+  graphRef.value?.changeVisibleByLevel(3, false);
+};
+
+const batchUpdate = (dataList) => {
+  graphRef.value?.batchUpdatePen(dataList);
+};
+</script>
+```
+
+## Props
+
+| 属性      | 类型   | 默认值 | 说明                     |
+| --------- | ------ | ------ | ------------------------ |
+| data      | Object | null   | 场景数据，优先级最高     |
+| url       | String | ''     | 图纸数据 URL，优先级第二 |
+| id        | String | ''     | 图纸 ID，优先级第三      |
+| token     | String | ''     | socket token             |
+| socketUrl | String | ''     | socket 地址              |
+
+## Events
+
+| 事件名      | 说明             | 参数               |
+| ----------- | ---------------- | ------------------ |
+| loaded      | 图纸加载完成     | stage: Meta2D 实例 |
+| graph-event | 图纸事件，点击等 | msg: 消息对象      |
+
+## 方法
+
+通过 ref 获取组件实例后可调用以下方法：
+
+- `setValue(pen, render = true)` - 设置图元属性
+- `getStage()` - 获取 Meta2D 实例
+- `getAllPens()` - 获取所有图元
+- `getCustomPenType()` - 获取所有图元类型
+- `batchUpdatePen(dataList)` - 批量更新图元
+- `handleLineCross()` - 处理线条交叉
+- `changeVisibleByLevel(level, isStrict = false)` - 切换显示层级
+
+## 使用场景
+
+### 1. 基础三维图纸展示
+
+```vue
+<SyThreedGraph :url="'/api/graph/123'" />
+```
+
+### 2. 图纸id
+
+```vue
+<SyThreedGraph :id="'111111111'" />
+```
+
+### 3. 直接传入数据
+
+```vue
+<SyThreedGraph :data="graphData" />
+```
+
+### 4. 完整配置示例
+
+```vue
+<SyThreedGraph
+  ref="graphRef"
+  :id="sceneId"
+  :data="sceneData"
+  :url="graphUrl"
+  :token="token"
+  :socketUrl="socketUrl"
+  @loaded="handleLoaded"
+  @graph-event="handleGraphEvent"
+/>
+```
+
+## 浏览器支持
+
+- Chrome >= 60
+- Firefox >= 60
+- Safari >= 12
+- Edge >= 79
+
+## 开发
+
+```bash
+# 安装依赖
+npm install
+
+# 开发模式
+npm run dev
+
+# 构建库
+npm run build:lib
+
+# 构建类型
+npm run build:types
+
+# 完整构建
+npm run build:all
+
+# 类型检查
+npm run type-check
+
+# 代码检查
+npm run lint
+```
+
+## 许可证
+
+[MIT](LICENSE)
+
+## 更新日志
+
+查看 [CHANGELOG.md](CHANGELOG.md) 了解详细的更新记录。
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request。
+
+## 相关链接
+
+- [ThreeJs 官方文档](https://threejs.org)
+- [ThreeEditor 官方文档](https://z2586300277.github.io/editor-docs/)
+- [Vue 3 文档](https://vuejs.org)
+- [Element Plus 文档](https://element-plus.org)