KdLaneContainer 组件使用文档

1. 组件概述

KdLaneContainer 是一个基于 Vue 开发的泳道图容器组件，用于展示和管理泳道模板、线条配置等。

$3

- 逻辑分离：将模板、泳道、参数的设置逻辑和绘制逻辑完全剥离，提高组件的可维护性和扩展性
- 接口兼容：提供了不依赖接口但是兼容接口实现的模板配置逻辑，既支持本地静态数据直接使用，也支持对接后端接口
- 使用场景：
- 适合静态数据展示场景，无需后端接口即可运行
- 适合合作单位使用，提供灵活的数据接入方式
- 技术栈无关：不限制绘制区技术栈，绘制逻辑完全由外部实现，只需要监听组件事件即可动态调整绘制内容

$3

重要通知：从版本 0.0.8 开始，组件名称正式从 KdLaneChartContainer 更名为 KdLaneContainer

#### 更名必要性：

1. 更准确的功能定位：原名称包含 "Chart"（图表），但组件实际上是一个通用的泳道容器，不直接负责图表绘制，更名后更符合其实际功能定位
2. 简化命名：去掉冗余的 "Chart" 后缀，使组件名称更简洁易记
3. 避免语义混淆：澄清了组件职责边界，明确表示这是一个容器组件而非图表组件，避免与其他图表组件混淆，和包名保持一致

#### 版本兼容性：

- 版本 0.0.8 及以后：统一使用 KdLaneContainer
- 版本 0.0.7 及之前：使用旧名称 KdLaneChartContainer

2. 组件功能

- 加载和展示泳道模板
- 支持自定义泳道头部
- 提供上下文菜单操作
- 支持自定义菜单扩展
- 实时曲线配置功能
- 模板和线条的增删改查操作

3. 组件引入

$3

``javascript
// 安装依赖
// npm install kd-lane-container --save

// 引入组件
import KdLaneContainer from "kd-lane-container";
import Vue from "vue";

// 注册组件
Vue.use(KdLaneContainer);
`

$3

`javascript
export default {
// 组件已全局注册，无需再局部注册
// components: {},
// ...
};
`

4. 组件使用

$3

#### 4.1.1 泳道宽度配置

从版本 0.1.0 开始，支持通过 width 属性自定义泳道宽度。

配置说明：
- 自定义插槽泳道：
- 如果泳道配置中包含 width 属性（数字类型），则动态设置 style 为 width: ${width}px。
- 如果未配置 width，则动态设置 style 为 width: auto，由插槽内容决定实际宽度(之前的默认逻辑)。
- 普通泳道：
- 如果泳道配置中包含 width 属性（数字类型），则动态设置 style 为 width: ${width}px。
- 如果未配置 width，则动态设置 style 为 flex: 1，与其他未设置宽度的泳道平分剩余空间(之前的默认逻辑)。

示例配置：
`javascript
lanes: [
{ 其他属性..., width: 200 }, // 自定义宽度为 200px
{ 其他属性..., } // 未设置宽度，使用默认逻辑
]
`

#### 4.1.2 泳道尺寸获取

新增 getGridSize 方法，用于获取泳道的精确尺寸（包括泳道抬头部分）。

注意事项：
- 调用时机：需确保泳道容器的 div 已挂载并渲染完毕，否则可能返回空数组或错误数据。
- 返回值：返回泳道的 x、y、width、height 等尺寸信息，以及 lane-id 属性。

示例代码：
`javascript
const gridSizes = this.$refs.laneContainer.getGridSize();
console.log(gridSizes); // 输出泳道尺寸信息
`

`vue
class="container"
:config="config"
:customMenuList="customMenuList"
@onCustomMenuClicked="onCustomMenuClicked"
@template-change="templateChange"
@line-change="lineChange"
:themeName="themeName"
>





`

#### 使用步骤说明

1. 配置组件：
- 通过 config 属性传入初始配置，包括数据源类型、案例ID、版本号等。
- 通过 customMenuList 属性传入自定义菜单列表。

2. 监听事件动态渲染：
- 监听 template-change 事件，获取最新的泳道数据（lanes），动态渲染自定义抬头和泳道布局。
- 监听 line-change 事件，处理线条配置的变化。从版本 0.1.1 开始，该事件会传递包含 actionType 属性的线条对象，可用于区分新增/更新和删除操作。

3. 主题变化处理：
- 主题变更是由外部触发的，组件仅负责根据 themeName 属性正确渲染标题。
- 模板和线条的变化需要自行处理，组件不会主动通知这些变化。

#### 线条变更事件处理示例

`javascript
// 在组件方法中处理 line-change 事件
lineChange(line) {
console.log('线条变更事件:', line);

// 根据 actionType 区分操作类型
switch (line.actionType) {
case 'upsertLine':
console.log('新增或更新线条:', line);
// 处理线条新增或更新逻辑
break;
case 'delLine':
console.log('删除线条:', line);
// 处理线条删除逻辑
break;
default:
console.log('未知操作类型:', line.actionType);
}
}
`

$3

#### 4.2.1 场景唯一标识规则

- caseId (场景 ID)：用于唯一标识不同的应用场景或业务模块。
- 必须确保在同一应用中唯一，否则会导致数据混淆。
- 建议使用业务模块名称或唯一的 UUID。
- 所有数据操作都将与该场景 ID 绑定，确保数据隔离。

#### 4.2.2 版本号管理

- versionCode (版本号)：用于管理不同版本的初始配置。
- 当业务需求发生重大变更时，可以通过升级版本号来重置数据。
- 版本号升级后，系统会自动清理旧版本数据并重新初始化。
- 版本号必须为整数，建议从 1 开始递增。

#### 4.2.3 数据初始化策略

- 首次初始化：系统会将传入的dataSource保存为当前版本的初始配置。
- 版本冲突：当检测到版本号变更时，系统会自动重置数据并使用新版本的配置。
- 异常恢复：如果初始化过程中出现错误，系统会自动执行重置操作。

$3

#### 4.3.1 数据源类型选择说明

KdLaneContainer 支持两种数据源类型：

- local：无后台配置接口，仅需前端单方面维护配置时使用
- custom：需要本组件 + 后台实时曲线配置接口组合使用时使用

#### 4.3.2 本地数据源 (Local)

`javascript
config: {
type: "local", // 数据源类型，可选值: "local" | "custom"
caseId: "demo", // 案例ID
versionCode: 2, // 版本号
dataSource: { // 数据源
// 支持两种数据结构：

// 1. 扁平结构 (推荐用于数据量大的场景)
templates: [], // 模板数据
lanes: [], // 泳道数据
lines: [], // 线条数据
params: [] // 参数数据

// 2. 树形结构 (直观易读，不用关心数据ID，组件会自己补全和维护)
// templates: [{
// lanes: [{
// lines: []
// }]
// }],
// params: []
}
}
`

local 模式下 datasource 参数说明：

- templates：只需提供 templateName 属性
- lane：不需要提供任何属性
- line：需要提供以下属性：paramId, min, lineSort, max, lineSize, lineColor, lineType, isUsed
可选属性：themeConfig - 线条级别主题颜色配置，支持为不同主题设置不同的线条颜色；isGradient - 是否为渐变线条。当设置为 true 时：
- lineType 必须为 "area"避免歧义
- lineColor 和 themeConfig 中的 lineColor 应使用 linear-gradient 格式
- LineEdit 组件中的颜色选择器和线型选择器将被禁用
示例：{ paramId: "52", min: 0.001, max: 100, lineSort: 1, lineSize: "2", lineColor: "linear-gradient(to bottom, blue, red)", lineType: "area", isUsed: "1", isGradient: true, themeConfig: { white: { lineColor: "linear-gradient(to bottom, black, red)" }, dark: { lineColor: "linear-gradient(to bottom, yellow, red)" }, gray: { lineColor: "linear-gradient(to bottom, #E5360B, red)" } } }
- params：需要提供以下属性：paramId, paramName, paramUnit
示例：{ paramId: "12", paramName: "钻头位置", paramUnit: "m" }

完整 local 模式示例配置：

`javascript
config: {
type: "local",
caseId: "demo",
versionCode: 2,
dataSource: {
// 嵌套结构示例
templates: [
{
templateName: "测试",
lanes: [
{
lines: [
{ paramId: "51", min: 0.001, lineSort: 1, max: 100, lineSize: "2", lineColor: "#E5360B", lineType: "solid", isUsed: "1", isGradient: false, themeConfig: { white: { lineColor: "blue" }, dark: { lineColor: "black" }, gray: { lineColor: "yellow" } } },
{ paramId: "52", min: 0.001, lineSort: 2, max: 100, lineSize: "2", lineColor: "linear-gradient(to bottom, blue, red)", lineType: "area", isUsed: "1", isGradient: true, themeConfig: { white: { lineColor: "linear-gradient(to bottom, black, red)" }, dark: { lineColor: "linear-gradient(to bottom, yellow, red)" }, gray: { lineColor: "linear-gradient(to bottom, #E5360B, red)" } } }
]
}
]
}
],
params: [
{ paramId: "51", paramName: "钻头位置", paramUnit: "m" },
{ paramId: "52", paramName: "钻压", paramUnit: "kN" }
]
}
}
`

#### 4.3.3 自定义数据源 (Custom)

`javascript
config: {
type: "custom", // 数据源类型，可选值: "local" | "custom"
caseId: "demo", // 案例ID
versionCode: 2, // 版本号

// 自定义数据源必须实现的7个方法，需按照要求的返回格式设置
getUserTemplates() { / 加载所有模板、泳道和线条数据 / },
upsertTemplate(data) { / 新增或更新模板 / },
delTemplate(data) { / 删除模板 / },
upsertLane(data) { / 新增或更新泳道 / },
delLane(data) { / 删除泳道 / },
upsertLine(data) { / 新增或更新线条 / },
delLine(data) { / 删除线条 / },

// 可选方法：恢复默认设置 【在local模式下，可以通过this.$refs[xxx].restoreSetting()方法恢复默认设置】
restoreSetting() { / 恢复默认设置 / }
}
`

各方法参数和返回值说明：

1. getUserTemplates()

- 返回值：Promise