kd-lane-container 0.0.1

package/README.md

@@ -0,0 +1,406 @@
+# KdLaneChartContainer 组件使用文档
+
+## 1. 组件概述
+
+KdLaneChartContainer 是一个基于 Vue 开发的泳道图容器组件，用于展示和管理泳道模板、线条配置等。
+
+### 1.1 设计思路
+- **逻辑分离**：将模板、泳道、参数的设置逻辑和绘制逻辑完全剥离，提高组件的可维护性和扩展性
+- **接口兼容**：提供了不依赖接口但是兼容接口实现的模板配置逻辑，既支持本地静态数据直接使用，也支持对接后端接口
+- **使用场景**：
+  - 适合静态数据展示场景，无需后端接口即可运行
+  - 适合合作单位使用，提供灵活的数据接入方式
+- **技术栈无关**：不限制绘制区技术栈，绘制逻辑完全由外部实现，只需要监听组件事件即可动态调整绘制内容
+
+## 2. 组件功能
+
+## 2. 组件功能
+
+- 加载和展示泳道模板
+- 支持自定义泳道头部
+- 提供上下文菜单操作
+- 支持自定义菜单扩展
+- 实时曲线配置功能
+- 模板和线条的增删改查操作
+
+## 3. 组件引入
+
+```javascript
+import KdLaneChartContainer from "./components/kd-lane/chart-container.vue";
+
+export default {
+  components: {
+    KdLaneChartContainer,
+  },
+  // ...
+};
+```
+
+## 4. 组件使用
+
+### 4.1 基本使用
+
+```vue
+<KdLaneChartContainer class="container" :config="config" :customMenuList="customMenuList" @onCustomMenuClicked="onCustomMenuClicked">
+  <!-- 自定义插槽内容 -->
+</KdLaneChartContainer>
+```
+
+### 4.1 场景与版本控制
+
+#### 4.1.1 场景唯一标识规则
+- **caseId (场景ID)**：用于唯一标识不同的应用场景或业务模块。
+  - 必须确保在同一应用中唯一，否则会导致数据混淆。
+  - 建议使用业务模块名称或唯一的UUID。
+  - 所有数据操作都将与该场景ID绑定，确保数据隔离。
+
+#### 4.1.2 版本号管理
+- **versionCode (版本号)**：用于管理不同版本的初始配置。
+  - 当业务需求发生重大变更时，可以通过升级版本号来重置数据。
+  - 版本号升级后，系统会自动清理旧版本数据并重新初始化。
+  - 版本号必须为整数，建议从1开始递增。
+
+#### 4.1.3 数据初始化策略
+- 首次初始化：系统会将传入的`dataSource`保存为当前版本的初始配置。
+- 版本冲突：当检测到版本号变更时，系统会自动重置数据并使用新版本的配置。
+- 异常恢复：如果初始化过程中出现错误，系统会自动执行重置操作。
+
+### 4.2 配置参数
+
+#### 4.2.1 本地数据源 (Local)
+
+```javascript
+config: {
+  type: "local", // 数据源类型，可选值: "local" | "custom"
+  caseId: "demo", // 案例ID
+  versionCode: 2, // 版本号
+  dataSource: { // 数据源
+    // 支持两种数据结构：
+    
+    // 1. 扁平结构 (推荐用于数据量大的场景)
+    templates: [], // 模板数据
+    lanes: [], // 泳道数据
+    lines: [], // 线条数据
+    params: [] // 参数数据
+    
+    // 2. 树形结构 (直观易读，不用关心数据ID，组件会自己补全和维护)
+    // templates: [{
+    //   lanes: [{
+    //     lines: []
+    //   }]
+    // }],
+    // params: []
+  }
+}
+```
+
+#### 4.2.2 自定义数据源 (Custom)
+
+当需要从服务器或自定义数据源获取和管理数据时，使用 `custom` 类型。需要实现以下CRUD方法：
+
+```javascript
+config: {
+  type: "custom", // 数据源类型，可选值: "local" | "custom"
+  caseId: "demo", // 案例ID
+  versionCode: 2, // 版本号
+  
+  // 自定义数据源必须实现的方法
+  getUserTemplates() { /* 加载所有模板、泳道和线条数据 */ },
+  upsertTemplate(data) { /* 新增或更新模板 */ },
+  delTemplate(data) { /* 删除模板 */ },
+  upsertLane(data) { /* 新增或更新泳道 */ },
+  delLane(data) { /* 删除泳道 */ },
+  upsertLine(data) { /* 新增或更新线条 */ },
+  delLine(data) { /* 删除线条 */ },
+  
+  // 可选方法：恢复默认设置
+  restoreSetting() { /* 恢复默认设置 */ }
+}
+```
+
+各方法参数和返回值说明：
+
+1. `getUserTemplates()`
+   - 返回值：`Promise<Object>` - 包含所有模板、泳道和线条数据的配置对象
+   - 示例：
+     ```json
+     {
+       "caseVersion": { "caseId": "case123", "versionCode": "v1.0" },
+       "templates": [/* 模板数组 */],
+       "params": []
+     }
+     ```
+
+2. `upsertTemplate(data)`
+   - 参数：`data` - 模板数据
+   - 返回值：`Promise<Object>` - 插入或更新后的完整模板对象
+
+3. `delTemplate(data)`
+   - 参数：`data` - 模板数据（需包含`templateId`）
+   - 返回值：`Promise<void>` - 操作成功或失败的Promise
+
+4. `upsertLane(data)`
+   - 参数：`data` - 泳道数据
+   - 返回值：`Promise<Object>` - 插入或更新后的完整泳道对象
+
+5. `delLane(lane)`
+   - 参数：`lane` - 泳道数据（需包含`laneId`和`lines`数组）
+   - 返回值：`Promise<void>` - 操作成功或失败的Promise
+
+6. `upsertLine(data)`
+   - 参数：`data` - 线条数据
+   - 返回值：`Promise<Object>` - 插入或更新后的完整线条对象
+
+7. `delLine(data)`
+   - 参数：`data` - 线条数据（需包含`lineId`和`laneId`）
+   - 返回值：`Promise<void>` - 操作成功或失败的Promise
+
+8. `restoreSetting()` (可选)
+   - 返回值：`Promise<void>` - 恢复默认设置的Promise
+
+### 4.3 自定义菜单
+
+customMenuList用于在上下文菜单中添加自定义操作选项。当用户在泳道头部或线条上右键点击时，这些自定义选项会出现在上下文菜单中。
+
+#### 4.3.1 菜单结构
+```javascript
+customMenuList: [
+  { 
+    name: "单屏时长", // 菜单项显示名称
+    key: "timeRange" // 菜单项唯一标识
+  },
+  { 
+    name: "导出数据", 
+    key: "exportData" 
+  }
+];
+```
+
+#### 4.3.2 点击事件
+当用户点击自定义菜单项时，会触发 `onCustomMenuClicked` 事件，并传递以下参数：
+- `event`: 事件对象，包含 `option` 和 `item` 属性
+  - `option`: 被点击的菜单项配置
+  - `item`: 右键点击时的目标对象（可能是泳道或线条）
+
+#### 4.3.3 使用示例
+```html
+<kd-lane-chart-container
+  :customMenuList=\"[{ name: '单屏时长', key: 'timeRange' }]\"
+  @onCustomMenuClicked=\"handleCustomMenuClick\">
+</kd-lane-chart-container>
+```
+
+```javascript
+handleCustomMenuClick(event) {
+  const { option, item } = event;
+  console.log('自定义菜单项被点击:', option.name);
+  console.log('点击的目标对象:', item);
+  
+  if (option.key === 'timeRange') {
+    // 处理单屏时长操作
+  }
+}
+```
+
+## 5. 组件 API
+
+### 5.1 Props
+
+| 属性名           | 类型   | 默认值 | 说明             |
+| ---------------- | ------ | ------ | ---------------- |
+| config           | Object | 必填   | 组件配置对象     |
+| headerPadding    | Number | 4      | 泳道头部内边距   |
+| headerItemHeight | Number | 20     | 头部线条项高度   |
+| itemGap          | Number | 2      | 线条项之间的间距 |
+| customMenuList   | Array  | []     | 自定义菜单列表   |
+
+### 5.2 事件
+
+| 事件名              | 参数     | 说明               |
+| ------------------- | -------- | ------------------ |
+| onCustomMenuClicked | event    | 自定义菜单点击事件 |
+| line-change         | line     | 线条变化事件       |
+| template-change     | template | 模板变化事件       |
+
+### 5.3 方法
+
+组件内部提供的方法主要用于模板和线条的管理：
+
+- upsertTemplate(data) - 新增或更新模板
+  - 参数：`data` - 模板数据
+  - 返回值：`Promise<Object>` - 插入或更新后的**完整**模板对象
+
+- delTemplate(data) - 删除模板
+  - 参数：`data` - 模板数据（需包含`templateId`）
+  - 返回值：`Promise<void>` - 操作成功或失败的Promise
+
+- upsertLane(data) - 新增或更新泳道
+  - 参数：`data` - 泳道数据
+  - 返回值：`Promise<Object>` - 插入或更新后的**完整**泳道对象
+
+- delLane(lane) - 删除泳道
+  - 参数：`lane` - 泳道数据（需包含`laneId`和`lines`数组）
+  - 返回值：`Promise<void>` - 操作成功或失败的Promise
+
+- upsertLine(data) - 新增或更新线条
+  - 参数：`data` - 线条数据
+  - 返回值：`Promise<Object>` - 插入或更新后的**完整线**条对象
+
+- delLine(data) - 删除线条
+  - 参数：`data` - 线条数据（需包含`lineId`和`laneId`）
+  - 返回值：`Promise<void>` - 操作成功或失败的Promise
+
+- restoreSetting() - 恢复默认设置
+  - 功能：将当前场景的数据重置为初始配置状态
+  - 实现逻辑：使用构造函数传入的初始dataSource重新初始化数据
+  - 返回值：`Promise<void>` - 恢复默认设置的Promise
+
+## 6. 自定义插槽
+
+组件支持根据泳道 ID 动态生成的插槽，用于自定义泳道头部：
+
+```vue
+<KdLaneChartContainer ...>
+  <!-- 动态slot名称 -->
+  <template v-if="slotName">
+    <div :slot="slotName" class="demo-slot">
+      {{ slotName }}
+    </div>
+  </template>
+  
+  <!-- 带参数的插槽 -->
+  <template v-if="slotName2" :slot="slotName2" slot-scope="slotData">
+    <div class="demo-slot">{{ typeof slotData }}</div>
+  </template>
+</KdLaneChartContainer>
+```
+
+插槽名称格式为 `lane${laneId}`，例如：`lane1556bdbfd0f24c11948b14999947c556`。
+
+### 6.2 draw-slot 画布插槽
+
+组件提供 `draw-slot` 插槽用于自定义绘制内容，该插槽占据泳道下方的整个绘制区域：
+
+```vue
+<KdLaneChartContainer ...>
+  <template slot="draw-slot">
+    <div style="height: 100%; width: 100%; padding: 10px">
+      <!-- 自定义绘制内容 -->
+    </div>
+  </template>
+</KdLaneChartContainer>
+```
+
+### 6.3 插槽布局与尺寸注意事项
+
+1. **布局方式**：
+   - 自定义插槽与泳道区域采用 flex 布局
+   - 自定义插槽会占据剩余位置后，与其他泳道进行平分
+   - 确保自定义插槽内容的宽度和高度设置正确，以保证与泳道对齐
+
+2. **尺寸单位**：
+   - 组件内的自定义插槽使用 style 绑定形式
+   - 宽度和高度单位必须使用 px，以确保精确对齐
+   - 避免使用其他单位（如 %、rem、em 等），否则可能导致布局错位
+
+3. **样式处理**：
+   - 不要使用全局样式处理插件对自定义插槽的尺寸单位进行转换
+   - 直接使用 px 单位编写插槽内容的尺寸样式
+   - 确保插槽内容的 box-sizing 为 border-box，以避免 padding 和 border 影响实际尺寸
+
+```vue
+<!-- 推荐的插槽内容样式 -->
+<template slot="draw-slot">
+  <div style="height: 100%; width: 100%; box-sizing: border-box; padding: 10px">
+    <!-- 自定义绘制内容 -->
+  </div>
+</template>
+```
+
+## 7. 样式定制
+
+可以通过 CSS 变量或直接覆盖样式来自定义组件外观：
+
+```css
+.kd-lane-chart-container {
+  --kd-lane-container-border-color: white;
+  --kd-lane-container-context-background-color: darkgray;
+  --kd-lane-container-context-hover-color: darkgray;
+  --kd-lane-container-header-item-color: white;
+  --app-background-color: gray;
+}
+```
+
+## 8. 使用示例
+
+```vue
+<template>
+  <div id="app">
+    <KdLaneChartContainer class="container" :config="config" :customMenuList="customMenuList" @onCustomMenuClicked="onCustomMenuClicked">
+      <template v-if="slotName">
+        <div :slot="slotName" class="demo-slot">
+          {{ slotName }}
+        </div>
+      </template>
+    </KdLaneChartContainer>
+  </div>
+</template>
+
+<script>
+import KdLaneChartContainer from "./components/kd-lane/chart-container.vue";
+import { data } from "./mock/mockData.js";
+
+export default {
+  name: "App",
+  components: {
+    KdLaneChartContainer,
+  },
+  data() {
+    return {
+      config: {
+        type: "local",
+        caseId: "demo",
+        versionCode: 2,
+        dataSource: { templates: data.templates, lanes: data.lanes, lines: data.lines, params: data.params },
+      },
+      slotName: "",
+      customMenuList: [{ name: "单屏时长", key: "timeRange" }],
+    };
+  },
+  mounted() {
+    setTimeout(() => {
+      this.slotName = "lane1556bdbfd0f24c11948b14999947c556";
+    }, 2000);
+  },
+  methods: {
+    onCustomMenuClicked(event) {
+      console.log(event);
+    },
+  },
+};
+</script>
+
+<style>
+#app {
+  font-family: Avenir, Helvetica, Arial, sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  text-align: center;
+  color: #2c3e50;
+  height: 100vh;
+  position: relative;
+  padding: 10px;
+
+  .container {
+    margin-left: 100px;
+    margin-top: 50px;
+    height: 600px;
+    width: 800px;
+  }
+
+  .demo-slot {
+    width: 80px;
+  }
+}
+</style>
+```