kd-lane-chart-v3 0.1.13 → 0.1.15

package/README.md

@@ -1,175 +1,704 @@
-# kd-lane-chart
+# kd-lane-chart-v3（Vue 3）使用文档
 
-泳道图（KdLaneContainer）+ 实时曲线（frameLayout）Vue 2 组件包。
+面向**第一次接入**的开发者：从安装、跑通演示，到配置模板、灌数据、监听事件、调用 ref 方法，以及常见问题。
 
-> **注意：** 旧包 `kd-lane-container` 和 `kd-curve-v2` 已不再推荐使用，请迁移至此统一包。
+| 项 | 说明 |
+|---|---|
+| 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. [它是什么 / 能做什么](#1-它是什么--能做什么)
+2. [环境与安装](#2-环境与安装)
+3. [本地跑演示](#3-本地跑演示)
+4. [最小接入（5 分钟）](#4-最小接入5-分钟)
+5. [页面必须满足的条件](#5-页面必须满足的条件)
+6. [布局面板说明](#6-布局面板说明)
+7. [Props 一览](#7-props-一览)
+8. [depthConfig / timeConfig 详解](#8-depthconfig--timeconfig-详解)
+9. [曲线数据 curveDatas](#9-曲线数据-curvedatas)
+10. [工具栏 toolBarConfig](#10-工具栏-toolbarconfig)
+11. [插槽（Vue 3 动态名）](#11-插槽vue-3-动态名)
+12. [事件](#12-事件)
+13. [ref 方法（重点）](#13-ref-方法重点)
+14. [强制更新配置 forceUpdateCurveConfig](#14-强制更新配置-forceupdatecurveconfig)
+15. [预警 / Tooltip / 主题](#15-预警--tooltip--主题)
+16. [交互模式与轴标签](#16-交互模式与轴标签)
+17. [单独使用 KdLaneContainer](#17-单独使用-kdlanecontainer)
+18. [多语言](#18-多语言)
+19. [Vue 2 → Vue 3 迁移注意](#19-vue-2--vue-3-迁移注意)
+20. [接入检查清单](#20-接入检查清单)
+21. [常见问题](#21-常见问题)
 
-```bash
-npm install kd-lane-chart
-```
+---
 
-### 依赖
+## 1. 它是什么 / 能做什么
 
-| 依赖 | 版本 |
+`kd-lane-chart-v3` 提供：
+
+| 组件 | 用途 |
 |---|---|
-| vue | ^2.6.0 |
-| element-ui | ^2.15.14 |
-| echarts | * |
-| vuedraggable | ^2.24.3 |
-| v-click-outside | ^2.1.3 |
-| resize-detector | ^0.3.0 |
-| lodash-es | ^4.18.1 |
+| **`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（及图标），并引入样式：
 
 ```js
-import Vue from "vue";
-import { KdLaneContainer, frameLayout } from "kd-lane-chart";
+import ElementPlus from "element-plus";
+import "element-plus/dist/index.css";
+app.use(ElementPlus);
+```
+
+### 2.2 从 npm 安装
 
-// 全局注册（也可按需单独注册）
-Vue.use(KdLaneContainer);
-Vue.use(frameLayout);
+```bash
+npm install kd-lane-chart-v3
+# 或
+pnpm add kd-lane-chart-v3
 ```
 
-或在组件内局部使用：
+### 2.3 本仓库 monorepo
+
+```bash
+# 仓库根
+pnpm install
+pnpm build:v3
+
+# test-v3 示例："kd-lane-chart-v3": "workspace:*"
+```
+
+本地 link：
+
+```bash
+cd kd-curve-v3/publish
+pnpm run link
+```
+
+### 2.4 注册组件（Vue 3）
 
 ```js
-import { KdLaneContainer, frameLayout } from "kd-lane-chart";
+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");
+```
 
-export default {
-  components: {
-    KdLaneContainer,
-    frameLayout,
-  },
-};
+局部注册（`<script setup>`）：
+
+```vue
+<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 依赖齐全。
+
 ---
 
-## KdLaneContainer（泳道图）
+## 3. 本地跑演示
+
+```bash
+cd kd-curve-v3
+pnpm install
+pnpm serve
+# 等价：pnpm dev
+```
 
-泳道图组件，用于展示钻井相关的车道数据。
+- 默认：`http://127.0.0.1:8888/`（`vite.config.js`）
+- 端口占用时 Vite 可能换端口，以终端为准
 
-### 基本用法
+演示页 `src/App.vue` 仅作接口参考，勿整页拷贝进生产。
+
+构建发布包：
+
+```bash
+# 仓库根
+pnpm build:v3
+```
+
+---
+
+## 4. 最小接入（5 分钟）
 
 ```vue
 <template>
-  <kd-lane-container
-    :config="config"
-    :datas="datas"
-    theme-name="dark"
-  />
+  <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>
-export default {
-  data() {
-    return {
-      config: { /* 泳道图配置 */ },
-      datas: { /* 数据 */ },
-    };
+<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>
 ```
 
-### Props
+---
+
+## 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 版基本相同，另多：
 
 | 参数 | 类型 | 说明 |
 |---|---|---|
-| config | Object | 泳道图配置 |
-| datas | Object | 数据 |
-| themeName | String | 主题：`white` / `dark` / `gray` |
+| `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 详解
+
+```js
+{
+  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
+
+```js
+curveDatas.value = { type: "replace", data: rows };
+curveDatas.value = { type: "append", data: row };
+```
+
+行示例：
+
+```js
+{ wellDepth: 1000, timestamp: 1709019984000, "8010": 1200, "8018": null }
+```
+
+切轴 / 切实时历史：在 `@update-settings` 里 `replace` 对应数据。  
+触顶触底：监听 `@chart-scroll` 补数。
 
 ---
 
-## frameLayout（实时曲线）
+## 10. 工具栏 toolBarConfig
 
-实时曲线图表容器，支持井深/时间两种曲线类型、实时/历史数据、多主题、滚动加载等。
+```js
+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`：
 
 ```vue
-<template>
-  <frame-layout
-    ref="frameLayout"
-    :depthConfig="depthConfig"
-    :timeConfig="timeConfig"
-    :curveDatas="curveDatas"
-    :themeName="themeName"
-    :toolBarConfig="toolBarConfig"
-    :parameterPanelConfig="parameterPanelConfig"
-    :WellBitDepthTimePlotConfig="WellBitDepthTimePlotConfig"
-    :warningData="warningData"
-    @template-change="onTemplateChange"
-    @line-change="onLineChange"
-    @chart-scroll="onChartScroll"
-    @updateSettings="onUpdateSettings"
-    @visibleDataChange="onVisibleDataChange"
-    @dialogFunction="onDialog"
-    @refresh="onRefresh"
-  >
-    <template v-for="lane in headerSlotName" :slot="lane.laneId">
-      <div class="header-slot">{{ lane.laneName }}</div>
-    </template>
-    <template v-for="lane in contentSlotName" :slot="lane.laneId">
-      <div class="content-slot">
-        <resizeEcharts autoresize :options="contentSlotOptions[lane.contentKey]" />
-      </div>
-    </template>
-  </frame-layout>
+<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>
 ```
 
-### Props
+在 `@template-change` 中维护 `headerSlotName` / `contentSlotName`（`laneId` 前缀仍为 `lane` / `content` + 数字 id），逻辑与 Vue 2 相同。
 
-| 参数 | 类型 | 说明 |
-|---|---|---|
-| depthConfig | Object | 井深配置（templates、params） |
-| timeConfig | Object | 时间配置（templates、params） |
-| curveDatas | Object | 曲线数据，`{ type: "replace" / "append", data: [...] }` |
-| themeName | String | 主题：`white` / `dark` / `gray` |
-| toolBarConfig | Object | 工具栏配置 |
-| parameterPanelConfig | Object | 参数面板配置 |
-| WellBitDepthTimePlotConfig | Object | 井深-钻头-时间曲线面板配置 |
-| warningData | Array | 预警数据 |
-
-### 事件
-
-| 事件 | 参数 | 说明 |
+---
+
+## 12. 事件
+
+| 事件 | 载荷 | 说明 |
 |---|---|---|
-| @template-change | data | 模板变更 |
-| @line-change | line | 曲线变更 |
-| @chart-scroll | { direction, currentData } | 图表滚动（方向 top/bottom） |
-| @updateSettings | { key, value, settings } | 设置变更 |
-| @visibleDataChange | { firstValue, lastValue } | 可见数据范围变更 |
-| @dialogFunction | { type, start, end } | 弹窗（1-井深段，2-时间段，3-导出） |
-| @refresh | — | 刷新 |
-| @onCustomMenuClicked | — | 自定义菜单点击 |
-| @trend-change | { paramId, laneId, segments } | 趋势线变更（加点/拖拽结束/删点/断段/重置） |
+| `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`。
+
+建议：
 
-趋势线的配置、交互和保存方式见 **[趋势线使用手册](./src/components/kdCurveV2/trend-line/趋势线使用手册.md)**。
+```js
+function onConfigChange({ axisType, config, reason }) {
+  const target = axisType === "time" ? timeConfig : depthConfig;
+  target.dataSource = config.dataSource;
+  if (config.versionCode != null) target.versionCode = config.versionCode;
+}
+```
 
-对数轴（泳道 `isLogScale`、表头点值按 lg 输出、边控显隐）见 **[对数轴使用手册](./src/components/kdCurveV2/log-axis/对数轴使用手册.md)**。
+原地更新 `dataSource`，避免整对象替换导致图表不必要整页重建。
 
-### 曲线数据格式
+---
+
+## 13. ref 方法（重点）
 
 ```js
-// 初始化/替换数据
-curveDatas: { type: "replace", data: [...] }
+const fl = frameLayoutRef.value;
+```
 
-// 追加数据（实时更新）
-curveDatas: { type: "append", data: generator() }
+| 方法 | 说明 |
+|---|---|
+| `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 强制落库当前内存配置
+
+```js
+await frameLayoutRef.value.forceUpdateCurveConfig();
+```
+
+流程：清空该 `caseId` 存储 → 写入当前快照 → `loadConfig` 重载 → `emit('config-change', { reason: 'force-update', axisType, config })`。
+
+### 14.2 传入完整新配置
+
+```js
+await frameLayoutRef.value.forceUpdateCurveConfig({
+  type: "local",
+  caseId: "my-well-depth",
+  versionCode: 2,
+  dataSource: {
+    templates: [/* ... */],
+    params: [/* ... */],
+  },
+});
 ```
 
+### 14.3 选项
+
+```js
+await frameLayoutRef.value.forceUpdateCurveConfig(nextConfig, {
+  updateDefaultSnapshot: true, // 默认 true：同步「恢复默认」基准
+});
+```
+
+### 14.4 与恢复默认
+
+初始化时会冻结首份传入的 `dataSource`。右键恢复默认优先用策略源，找不到则回退到该快照 / 当前 config。强制更新且 `updateDefaultSnapshot: true` 时，恢复基准也会换成新配置。
+
 ---
 
-## License
+## 15. 预警 / Tooltip / 主题
+
+预警、色带、tooltip 格式与 Vue 2 相同。  
+`tooltipFormatter` **必须返回 HTML 字符串**，不要返回 VNode/DOM。
+
+```js
+function tooltipFormatter({ series, mousePositionData }) {
+  return `<div>${mousePositionData?.depth ?? ""}</div>`;
+}
+```
+
+主题：`theme-name` + `body[data-theme]`。
 
-MIT
+---
+
+## 16. 交互模式与轴标签
+
+| `isGeomechanical` | 行为 |
+|---|---|
+| `false` | 窗口滚动（多泳道同步） |
+| `true` | 地应力缩放/平移；可配合 `canClickSelectLane` |
+
+井深刻度为 HTML 叠层。缩放过程中按像素密度疏化刻度并节流刷新，减轻卡顿与「刻度挤压」；结束后再精确对齐。
+
+对数轴见专题手册。
+
+---
+
+## 17. 单独使用 KdLaneContainer
+
+```vue
+<KdLaneContainer :config="depthConfig" theme-name="dark" />
+```
+
+`config` 需含 `caseId`、`type`、`versionCode`、`dataSource`。  
+同样可调用 `forceUpdateCurveConfig` / `getCurrentConfig`（在该组件 ref 上）。
+
+---
+
+## 18. 多语言
+
+```js
+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 完整；组件会用冻结快照回退。
+
+---
+
+## 附录：导出一览
+
+```js
+import {
+  KdLaneContainer,
+  FrameLayout,
+  frameLayout,
+  setCurrentLocale,
+  getCurrentLocale,
+  installKdI18n,
+  localeState,
+} from "kd-lane-chart-v3";
+```