kd-lane-chart-v3（Vue 3）使用文档

面向第一次接入的开发者：从安装、跑通演示，到配置模板、灌数据、监听事件、调用 ref 方法，以及常见问题。

| 项 | 说明 | |---|---| | npm 包名 | kd-lane-chart-v3（当前约 0.1.13） | | 框架 | Vue ^3.5 | | UI | Element Plus + @element-plus/icons-vue | | 演示工程 | 本目录 kd-curve-v3（Vite） | | 发布产物 | kd-curve-v3/publish/（含 index.d.ts） | | 仓库总览 | 仓库根目录 使用文档.md（v2/v3 对照） |

请勿安装 Vue 2 包 kd-lane-chart 到 Vue 3 工程。本目录旧版 USAGE 若仍写 Vue 2，以本文为准。

与 Vue 2 版（kd-lane-chart）功能对齐，差异主要在：框架 API、UI 库、插槽写法、拖拽库（vue-draggable-plus）。

专题手册（路径与 v2 相同，相对本包 src）：

| 专题 | 路径 | |---|---| | 趋势线 | src/components/kdCurveV2/trend-line/趋势线使用手册.md | | 对数轴 | src/components/kdCurveV2/log-axis/对数轴使用手册.md | | 加载/内存 | src/components/kdCurveV2/perf/加载优化文档.md | | 架构速览 | CODE_WIKI.md |

目录

1. 它是什么 / 能做什么
2. 环境与安装
3. 本地跑演示
4. 最小接入（5 分钟）
5. 页面必须满足的条件
6. 布局面板说明
7. Props 一览
8. depthConfig / timeConfig 详解
9. 曲线数据 curveDatas
10. 工具栏 toolBarConfig
11. 插槽（Vue 3 动态名）
12. 事件
13. ref 方法（重点）
14. 强制更新配置 forceUpdateCurveConfig
15. 预警 / Tooltip / 主题
16. 交互模式与轴标签
17. 单独使用 KdLaneContainer
18. 多语言
19. Vue 2 → Vue 3 迁移注意
20. 接入检查清单
21. 常见问题

1. 它是什么 / 能做什么

kd-lane-chart-v3 提供：

| 组件 | 用途 | |---|---| | FrameLayout / frameLayout | 业务主入口：参数栏 + 井深时间小图 + 泳道曲线 + 工具栏 | | KdLaneContainer | 泳道图本体（也可单独用） |

能力与 Vue 2 包对齐：实时/历史曲线、井深/时间轴、比例尺、预警、趋势线、自定义插槽、模板编辑、IndexedDB 本地模板、配置回传与强制覆盖等。

数据流：

业务页
  ├─ depthConfig / timeConfig  → 模板 → IndexedDB（type: local）
  ├─ curveDatas                → 测点 replace / append
  ├─ toolBarConfig.form        → 轴类型、比例尺…
  └─ ref / 事件                 → getCurrentConfig、forceUpdateCurveConfig…

2. 环境与安装

2.1 依赖要求（peer）

| 依赖 | 建议版本 | |---|---| | vue | ^3.5.0 | | element-plus | ^2.9.0 | | @element-plus/icons-vue | ^2.3.1 | | echarts | >=5.0.0 | | vue-draggable-plus | ^0.6.0 | | v3-click-outside | ^1.0.2 | | resize-detector | ^0.3.0 | | lodash-es | ^4.18.1 |

业务工程需自行注册 Element Plus（及图标），并引入样式：

import ElementPlus from "element-plus";
import "element-plus/dist/index.css";
app.use(ElementPlus);

2.2 从 npm 安装

npm install kd-lane-chart-v3
# 或
pnpm add kd-lane-chart-v3

2.3 本仓库 monorepo

# 仓库根
pnpm install
pnpm build:v3

# test-v3 示例："kd-lane-chart-v3": "workspace:*"

本地 link：

cd kd-curve-v3/publish
pnpm run link

2.4 注册组件（Vue 3）

import { createApp } from "vue";
import ElementPlus from "element-plus";
import "element-plus/dist/index.css";
import {
  KdLaneContainer,
  FrameLayout,
  setCurrentLocale,
  installKdI18n,
} from "kd-lane-chart-v3";
import App from "./App.vue";

const app = createApp(App);
app.use(ElementPlus);
app.use(KdLaneContainer);
app.use(FrameLayout); // 注册 FrameLayout + frameLayout，并会 installKdI18n
// 或显式：installKdI18n(app);

setCurrentLocale("zh-CN");
app.mount("#app");

局部注册（<script setup>）：

<script setup>
import { FrameLayout, KdLaneContainer } from "kd-lane-chart-v3";
</script>

<template>
  <FrameLayout ref="frameLayoutRef" /* ... */ />
</template>

TypeScript：包提供 index.d.ts，从 kd-lane-chart-v3 直接 import 即可。

2.5 源码调试

可直接引用 src/components/kdCurveV2/frame-layout/index.vue，注意 Vite 别名与 peer 依赖齐全。

3. 本地跑演示

cd kd-curve-v3
pnpm install
pnpm serve
# 等价：pnpm dev

• 默认：http://127.0.0.1:8888/（vite.config.js）
• 端口占用时 Vite 可能换端口，以终端为准

演示页 src/App.vue 仅作接口参考，勿整页拷贝进生产。

构建发布包：

# 仓库根
pnpm build:v3

4. 最小接入（5 分钟）

<template>
  <div class="page" data-theme="dark">
    <FrameLayout
      ref="frameLayoutRef"
      theme-name="dark"
      :depth-config="depthConfig"
      :time-config="timeConfig"
      :curve-datas="curveDatas"
      :tool-bar-config="toolBarConfig"
      @template-change="onTemplateChange"
      @update-settings="onUpdateSettings"
      @config-change="onConfigChange"
    />
  </div>
</template>

<script setup>
import { onMounted, reactive, ref } from "vue";
import { FrameLayout, setCurrentLocale } from "kd-lane-chart-v3";

setCurrentLocale("zh-CN");

const frameLayoutRef = ref(null);

const depthConfig = reactive({
  type: "local",
  caseId: "my-well-depth",
  versionCode: 1,
  dataSource: {
    templates: [
      {
        templateName: "默认",
        isPublic: "1",
        createUser: "SYSTEM_USER",
        lanes: [
          {
            laneName: "井深",
            laneKey: "wellDepth",
            canScroll: false,
            canDrag: false,
            width: 60,
            sort: 0,
            lines: [],
          },
          {
            laneName: "大钩负荷",
            sort: 1,
            width: 120,
            lines: [
              {
                paramId: "8010",
                lineSort: 1,
                min: 0,
                max: 8000,
                lineSize: "2",
                lineType: "solid",
                isUsed: "1",
                lineColor: "#3DE375",
              },
            ],
          },
        ],
      },
    ],
    params: [
      { paramId: "wellDepth", paramName: "井深", paramUnit: "m" },
      { paramId: "8010", paramName: "大钩负荷", paramUnit: "kN" },
    ],
  },
});

const timeConfig = reactive({
  type: "local",
  caseId: "my-well-time",
  versionCode: 1,
  dataSource: { templates: [], params: [] },
});

const toolBarConfig = reactive({
  show: true,
  axisTypeList: { depth: "wellDepth", time: "timestamp" },
  form: {
    axisType: "depth",
    dataType: "history",
    displayType: "float",
    scale: 5,
  },
});

const curveDatas = ref({
  type: "replace",
  data: [
    { wellDepth: 1000, timestamp: Date.now(), "8010": 1200 },
    { wellDepth: 1001, timestamp: Date.now() + 1000, "8010": 1250 },
  ],
});

onMounted(() => {
  document.body.setAttribute("data-theme", "dark");
});

function onTemplateChange() {}
function onUpdateSettings({ key, value }) {
  console.log("settings", key, value);
}
function onConfigChange({ axisType, config, reason }) {
  if (axisType === "time") {
    timeConfig.dataSource = config.dataSource;
    if (config.versionCode != null) timeConfig.versionCode = config.versionCode;
  } else {
    depthConfig.dataSource = config.dataSource;
    if (config.versionCode != null) depthConfig.versionCode = config.versionCode;
  }
  console.log("config-change", reason, axisType);
}

// 强制更新示例
async function forceWrite() {
  await frameLayoutRef.value.forceUpdateCurveConfig();
}
</script>

<style>
.page {
  height: 100vh;
  width: 100%;
}
</style>

5. 页面必须满足的条件

1. 外层明确高度（100vh 或 flex 子项撑满）。
2. themeName 与 document.body 的 data-theme 一致（white / dark / gray）。
3. 先 replace 再按需 append。
4. axisTypeList 字段 = 数据行键 = 轴列 laneKey。
5. paramId = 数据行字段；缺测用 null。
6. 模板结构变更：versionCode++，或调用 forceUpdateCurveConfig。

6. 布局面板说明

| 面板 | 内容 | 开关 | |---|---|---| | 左 1 | 参数列表 | parameterPanelConfig.show | | 左 2 | 井深-钻头-时间小图 | WellBitDepthTimePlotConfig.show | | 中 3 | 主曲线 | 配置有效即显示 | | 右 4 | 工具栏 | toolBarConfig === false 可隐藏 |

formCache 是 FrameLayout 内部状态，不是 prop；由 toolBarConfig.form 初始化。

7. Props 一览

与 Vue 2 版基本相同，另多：

| 参数 | 类型 | 说明 | |---|---|---| | canClickSelectLane | Boolean | 地应力下是否允许点选泳道红框（常与 isGeomechanical 联用） |

其余常用：

| 参数 | 说明 | |---|---| | depthConfig / timeConfig | 模板配置 | | curveDatas | { type, data } | | themeName | white / dark / gray | | toolBarConfig | 工具栏或 false | | parameterPanelConfig | 左侧参数 | | WellBitDepthTimePlotConfig | 左侧小图 | | headerStyle | 表头样式 | | headerSlotName / contentSlotName | 插槽登记 | | warningData / warningLabelConfig / warningAreaData | 预警 | | tooltipFormatter | 返回 HTML 字符串 | | lineListData | 趋势线回显 | | isGeomechanical | 地应力模式 | | showContextMenuStatus | 右键开关 | | customMenuList | 扩展菜单 |

8. depthConfig / timeConfig 详解

{
  type: "local",
  caseId: "depth",      // 必填，存储隔离
  versionCode: 1,       // 结构变更必须递增
  dataSource: {
    templates: [
      {
        templateName: "默认",
        lanes: [
          { laneName: "井深", laneKey: "wellDepth", canScroll: false, lines: [] },
          {
            laneName: "曲线道",
            lines: [
              { paramId: "8010", min: 0, max: 8000, lineType: "solid", isUsed: "1", lineColor: "#3DE375" },
            ],
          },
        ],
      },
    ],
    params: [
      { paramId: "wellDepth", paramName: "井深", paramUnit: "m" },
      { paramId: "8010", paramName: "大钩负荷", paramUnit: "kN" },
    ],
  },
}

泳道 / 曲线字段含义与 Vue 2 文档一致（laneKey、contentKey、isLogScale、templateRangeSaved 等）。
type: "local" 使用 IndexedDB；其它类型走自定义 Strategy。

9. 曲线数据 curveDatas

curveDatas.value = { type: "replace", data: rows };
curveDatas.value = { type: "append", data: row };

行示例：

{ wellDepth: 1000, timestamp: 1709019984000, "8010": 1200, "8018": null }

切轴 / 切实时历史：在 @update-settings 里 replace 对应数据。
触顶触底：监听 @chart-scroll 补数。

10. 工具栏 toolBarConfig

toolBarConfig: {
  show: true,
  axisTypeList: { depth: "wellDepth", time: "timestamp" },
  scaleList: [
    { label: "1:100", value: 1 },
    { label: "1:500", value: 5 },
  ],
  form: {
    axisType: "depth",
    dataType: "history",
    displayType: "float",
    scale: 5,
    showLogAxis: true,
  },
}

未传的按钮/列表项走组件默认。

11. 插槽（Vue 3 动态名）

Vue 3 不要再用 :slot=，请用 v-slot:[name]，且 v-for 带 :key：

<template
  v-for="lane in headerSlotName"
  :key="lane.laneId"
  v-slot:[lane.laneId]
>
  <div class="header-slot">{{ lane.laneName }}</div>
</template>

<template
  v-for="lane in contentSlotName"
  :key="lane.laneId"
  v-slot:[lane.laneId]
>
  <div class="content-slot" /><!-- 自定义岩性等 -->
</template>

在 @template-change 中维护 headerSlotName / contentSlotName（laneId 前缀仍为 lane / content + 数字 id），逻辑与 Vue 2 相同。

12. 事件

| 事件 | 载荷 | 说明 | |---|---|---| | template-change | 当前模板 | 拖拽/编辑后 | | line-change | line + actionType | 曲线变更 | | config-change | { reason, config, axisType } | 保存/重置/拖拽/强制更新后回传 | | update-settings | { key, value, settings } | 切轴、切实时历史 | | chart-scroll | { direction, currentData } | 触顶触底 | | visible-data-change | 可见窗口信息 | 自定义道跟窗 | | dialog-function | { type, start, end } | 井深段/时间段/导出 | | refresh | — | 刷新 | | trend-change | 趋势线数据 | 编辑后 | | show-context-menu / on-custom-menu-clicked | 右键 | 菜单 | | lane-width-change | 列宽 | 拖宽 |

模板中可用 kebab-case：@config-change、@update-settings。

建议：

function onConfigChange({ axisType, config, reason }) {
  const target = axisType === "time" ? timeConfig : depthConfig;
  target.dataSource = config.dataSource;
  if (config.versionCode != null) target.versionCode = config.versionCode;
}

原地更新 dataSource，避免整对象替换导致图表不必要整页重建。

13. ref 方法（重点）

const fl = frameLayoutRef.value;

| 方法 | 说明 | |---|---| | getCurrentConfig() | { axisType, config } | | forceUpdateCurveConfig(nextConfig?, options?) | 强制写内存 + IndexedDB，并 config-change | | setCurveMinMaxByParamId(paramsId, min, max) | 改量程；模板锁定则 false | | getTrendLineData() / setTrendLineData(...) | 趋势线 | | breakTrendSegment() / resetTrendLine / resetAllTrendLines | 趋势线编辑 | | clearActiveLane() | 清选中 | | clearChartData() | 清数据 | | refresh() | 内部刷新 | | startLoading() / stopLoading() | 加载态 | | jumpToNextMarkLine(percent?) | 跳预警线 | | updateForm({ key, value }) | 改 form |

Options API 下：this.$refs.frameLayout.xxx()。

14. 强制更新配置 forceUpdateCurveConfig

用于强制用新配置覆盖当前轴（含 IndexedDB），不依赖 versionCode 升级路径。

14.1 强制落库当前内存配置

await frameLayoutRef.value.forceUpdateCurveConfig();

流程：清空该 caseId 存储 → 写入当前快照 → loadConfig 重载 → emit('config-change', { reason: 'force-update', axisType, config })。

14.2 传入完整新配置

await frameLayoutRef.value.forceUpdateCurveConfig({
  type: "local",
  caseId: "my-well-depth",
  versionCode: 2,
  dataSource: {
    templates: [/* ... */],
    params: [/* ... */],
  },
});

14.3 选项

await frameLayoutRef.value.forceUpdateCurveConfig(nextConfig, {
  updateDefaultSnapshot: true, // 默认 true：同步「恢复默认」基准
});

14.4 与恢复默认

初始化时会冻结首份传入的 dataSource。右键恢复默认优先用策略源，找不到则回退到该快照 / 当前 config。强制更新且 updateDefaultSnapshot: true 时，恢复基准也会换成新配置。

15. 预警 / Tooltip / 主题

预警、色带、tooltip 格式与 Vue 2 相同。
tooltipFormatter 必须返回 HTML 字符串，不要返回 VNode/DOM。

function tooltipFormatter({ series, mousePositionData }) {
  return `<div>${mousePositionData?.depth ?? ""}</div>`;
}

主题：theme-name + body[data-theme]。

16. 交互模式与轴标签

| isGeomechanical | 行为 | |---|---| | false | 窗口滚动（多泳道同步） | | true | 地应力缩放/平移；可配合 canClickSelectLane |

井深刻度为 HTML 叠层。缩放过程中按像素密度疏化刻度并节流刷新，减轻卡顿与「刻度挤压」；结束后再精确对齐。

对数轴见专题手册。

17. 单独使用 KdLaneContainer

<KdLaneContainer :config="depthConfig" theme-name="dark" />

config 需含 caseId、type、versionCode、dataSource。
同样可调用 forceUpdateCurveConfig / getCurrentConfig（在该组件 ref 上）。

18. 多语言

import {
  setCurrentLocale,
  getCurrentLocale,
  installKdI18n,
  localeState,
} from "kd-lane-chart-v3";

installKdI18n(app); // use(FrameLayout) 时通常已调用
setCurrentLocale("en");

比 Vue 2 包多导出：installKdI18n、localeState。

19. Vue 2 → Vue 3 迁移注意

| 点 | Vue 2（kd-lane-chart） | Vue 3（kd-lane-chart-v3） | |---|---|---| | 安装包名 | kd-lane-chart | kd-lane-chart-v3 | | 注册 | Vue.use | app.use | | UI | Element UI | Element Plus | | 插槽 | :slot="id" | v-slot:[id] + :key | | 拖拽 peer | vuedraggable | vue-draggable-plus | | 点击外部 | v-click-outside | v3-click-outside | | 生命周期 | beforeDestroy | beforeUnmount | | i18n 导出 | setCurrentLocale 等 | 另含 installKdI18n、localeState | | 类型 | 无官方 d.ts（以 JS 为准） | 有 index.d.ts |

业务侧 depthConfig / curveDatas / 事件名语义保持一致，迁移成本主要在工程脚手架与模板语法。

20. 接入检查清单

• [ ] Vue 3 + Element Plus + echarts 等 peer 已装
• [ ] app.use(FrameLayout)，容器有高度
• [ ] data-theme 与 themeName 一致
• [ ] 轴字段三处统一：axisTypeList / 数据行 / laneKey
• [ ] 缺测为 null
• [ ] 模板变更：versionCode++ 或 forceUpdateCurveConfig
• [ ] 监听 config-change 写回业务配置
• [ ] 插槽使用 v-slot:[name]
• [ ] tooltip 返回字符串
• [ ] 大数据注意窗口化，避免一次渲染整井

21. 常见问题

切轴后空白
数据缺轴字段，或 laneKey ≠ axisTypeList。

改模板不生效
IndexedDB 旧缓存：提高 versionCode，或 forceUpdateCurveConfig(新配置)。

Maximum recursive updates（KdLaneContainer）
大数据下曾因拖拽 v-model / 频繁 lineRange 更新引起；请使用当前修复版本。若仍出现，避免在 watch 里同步连环全量重绘。

缩放卡顿、井深轴挤压
当前版本已做密度疏化与节流；确认未把整井数据当单窗绘制。

量程改不了
模板已 templateRangeSaved，或 paramsId 错误。

恢复默认失败
确认首次传入的 config 完整；组件会用冻结快照回退。

附录：导出一览

import {
  KdLaneContainer,
  FrameLayout,
  frameLayout,
  setCurrentLocale,
  getCurrentLocale,
  installKdI18n,
  localeState,
} from "kd-lane-chart-v3";