@idooel/components 0.0.2-beta.29 → 0.0.2-beta.30

package/packages/utils/README.md

@@ -0,0 +1,172 @@
+# Utils 工具库目录结构
+
+## 📁 目录结构
+
+```
+utils/
+├── README.md                          # 本说明文档
+├── index.js                          # 工具库主入口，导出所有工具和常量
+└── runtime-context/                  # Runtime Context 数据池模块
+    ├── index.js                      # 统一导出入口
+    ├── globalDataPool.js             # 全局数据池核心架构
+    ├── dataPoolAPI.js                # 统一的数据池 API 接口
+    └── modelSchema.js                # 模型字段定义和类型验证
+```
+
+## 🚀 使用方式
+
+### 1. 传统工具（常量和函数）
+
+```javascript
+import { 
+  NAMESPACE, 
+  CONTEXT, 
+  BUILT_IN_EVENT_NAMES,
+  parseFieldMap 
+} from '@/utils'
+
+// 使用常量和工具函数
+const context = CONTEXT
+const fieldMap = parseFieldMap(fieldMapConfig, dataSource)
+```
+
+### 2. Runtime Context 数据池
+
+```javascript
+// 直接导入（推荐）
+import { createTreeTableModel, createDataPoolAPI } from '@/utils/runtime-context'
+
+// 使用示例
+const model = createTreeTableModel('my-table')
+const api = createDataPoolAPI()
+```
+
+### 3. TreeTable 模型（推荐用法）
+
+```javascript
+import { createTreeTableModel } from '@/utils/runtime-context'
+
+// 创建 TreeTable 模型实例
+const model = createTreeTableModel('tree-table-instance')
+
+// 使用模型方法
+model.setCurrentRowData({ id: 1, name: '测试数据' })
+const currentRow = model.getCurrentRowData()
+
+// 订阅数据变化
+model.subscribe('currentRowData', (event) => {
+  console.log('数据变化:', event.value)
+})
+
+// 设置共享数据（用于 modal table）
+model.setSharedData({ parentData: '父级数据' })
+```
+
+### 4. 模型字段定义
+
+```javascript
+import { TREE_TABLE_FIELDS, getSupportedFields, getFieldDefinition } from '@/utils/runtime-context'
+
+// 查看支持的字段
+console.log('支持的字段:', getSupportedFields()) // ['currentRowData']
+
+// 查看字段定义
+console.log('currentRowData 字段定义:', getFieldDefinition('currentRowData'))
+// 输出: { type: 'object', default: {}, description: '当前表格选中的行数据' }
+
+// 字段会在模型创建时自动初始化为默认值
+const model = createTreeTableModel('my-table')
+console.log(model.getCurrentRowData()) // {} (默认值)
+```
+
+## 📋 模块说明
+
+### Runtime Context 模块
+
+新一代的数据池管理系统，基于 `@idooel/runtime-context` 构建：
+
+- **globalDataPool.js**: 核心架构，挂载到 `window.__idooel_data_pool__`
+- **dataPoolAPI.js**: 统一的 API 接口，提供简洁易用的方法
+- **modelSchema.js**: 模型字段定义和类型验证
+
+### 传统工具
+
+保持向后兼容的工具和常量：
+
+- **index.js**: 常量定义和工具函数
+
+## 🔄 迁移指南
+
+### 从旧版数据池迁移
+
+```javascript
+// 旧版 TreeTableDataPoolManager（已弃用）
+import { createPoolManager, generateInstanceId } from '@/utils/treeTableDataPoolManager'
+
+// 新版 runtime-context（推荐）
+import { createTreeTableModel } from '@/utils/runtime-context'
+const model = createTreeTableModel('instance-id')
+```
+
+### TreeTable 组件迁移
+
+✅ **已完成迁移** - 组件已从 TreeTableDataPoolManager 迁移到新的 runtime-context 架构：
+
+```javascript
+// 新版用法（已实现）
+import { createTreeTableModel } from '@/utils/runtime-context'
+
+export default {
+  async created() {
+    // 确保全局数据池已初始化
+    if (!window.__idooel_data_pool__) {
+      console.error('Global data pool not initialized')
+      return
+    }
+    
+    // 创建 TreeTable 模型实例
+    this.model = createTreeTableModel('treeTableModel')
+    
+    // 使用模型方法
+    this.model.setCurrentRowData({ id: 1, name: '测试数据' })
+    const currentRow = this.model.getCurrentRowData()
+    
+    // 订阅数据变化
+    this.unsubscribe = this.model.subscribe('currentRowData', (event) => {
+      this.currentRowData = event.value
+      this.$forceUpdate()
+    })
+  },
+  
+  beforeDestroy() {
+    // 清理订阅
+    if (this.unsubscribe) this.unsubscribe()
+    if (this.model) this.model.cleanup()
+  }
+}
+```
+
+## 🛠️ 开发建议
+
+1. **新项目**: 直接使用 `runtime-context` 模块
+2. **已迁移项目**: 使用新的 `createTreeTableModel` API
+3. **初始化检查**: 组件中检查 `window.__idooel_data_pool__` 确保数据池已初始化
+4. **错误处理**: 使用 try-catch 包裹模型创建，添加安全检查
+5. **共享数据**: 使用简单的 `setSharedData()` 和 `getSharedData()` 方法
+6. **调试**: 使用 `window.__idooel_data_pool__.manager.debug()` 查看状态
+7. **批量操作**: 使用 `setBatchModelData` 提高效率
+8. **数据管理**: 使用 `export/import` 方法进行数据备份和恢复
+9. **内存管理**: 在组件销毁时正确清理订阅和模型数据
+
+## ⚠️ 注意事项
+
+- **初始化顺序**: 确保 `runtime-context` 模块在使用前已导入
+- **错误处理**: 组件应处理模型创建失败的情况
+- **清理工作**: 组件销毁时必须清理订阅和模型，避免内存泄漏
+- **向后兼容**: 旧的 `TreeTableDataPoolManager` 已弃用，请使用新的 API
+
+## 📚 相关文档
+
+- [API 接口文档](./runtime-context/dataPoolAPI.js)
+- [全局数据池架构](./runtime-context/globalDataPool.js)
+- [模型字段定义](./runtime-context/modelSchema.js)