kd-lane-chart-v3

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

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

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

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

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

目录

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 提供：

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

数据流：

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

2. 环境与安装

2.1 依赖要求（peer）

业务工程需自行注册 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. 布局面板说明

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

7. Props 一览

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

其余常用：

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. 事件

模板中可用 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;

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. 交互模式与轴标签

井深刻度为 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 迁移注意

业务侧 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";