bigmap-plugin 1.0.5 → 1.0.6

package/README.md

@@ -2,7 +2,7 @@
 
 **基于 bigemap / bmgl 的地图插件**，开箱即用的 Vue3 地图组件。
 
-高性能点位渲染（10 万级）· 交互式绘制 · 实体绘制 · 轨迹回放 · 遮罩反选 · 天气特效 · 3D 自动光源 · 生产底图切换
+高性能点位渲染（10 万级）· 交互式绘制 · 实体绘制 · 轨迹回放 · 遮罩反选 · KML 数据加载 · 天气特效 · 3D 自动光源 · 生产底图切换
 
 ---
 
@@ -36,6 +36,7 @@
   - [4.12 3D 自动光源](#412-3d-自动光源)
   - [4.13 主题切换](#413-主题切换)
   - [4.14 视图与地图](#414-视图与地图)
+- [4.15 KML 数据加载](#415-kml-数据加载)
 - [5. Composable 独立使用](#5-composable-独立使用)
 - [6. 常见问题 FAQ](#6-常见问题-faq)
 - [License](#license)
@@ -176,11 +177,11 @@ api.startDrawing('rectangle')                           // 开始交互式绘制
 | `searchDebounceTime` | `number` | `300` | 否 | 搜索输入防抖延迟（ms） |
 | `wmtsUrlProvider` | `() => Promise<string>` | `undefined` | 否 | 生产底图 WMTS URL 提供器：返回带令牌的 WMTS 请求地址，**优先级高于 `geoserver`**，见 [3.2.1](#321-生产底图切换wmtsurlprovider--geoserver) |
 | `geoserver` | `GeoServerSourceConfig` | `undefined` | 否 | 生产地图（GeoServer）源配置：提供 `baseUrl` / `layer` / `token`，配置后启用物探/生产底图切换，见 [3.2.1](#321-生产底图切换wmtsurlprovider--geoserver) |
-| `contourConfig` | `Partial<ContourConfig>` | `{ spacing:150, width:2 }` | 否 | 等高线显示配置（仅 3D） |
+| `contourConfig` | `Partial<ContourConfig>` | 内置默认（等高距 150m / 线宽 2px / 内置色带） | 否 | 彩色等高线显示配置（仅 3D），见 [4.8](#48-等高线显示) |
 | `lightingConfig` | `boolean` | `false` | 否 | 是否开启 3D 自动光源（按系统时间） |
 
-> **建议**：除 `theme` / `popupConfig` 外，其余配置统一放入 `config` 集中管理，代码更整洁。
-
+> **建议**：除 `theme` / `popupConfig` 外，其余配置统一放入 `config` 集中管理，代码更整洁。
+
 > **底图图层（`baseLayers` 与 `mapId` 的分工）**：`mapId` 是引擎（Viewer）自带的基础影像，`baseLayers` 是初始化时叠加在其上的底图图层列表。两者都会随「影像 / 生产底图」切换按钮一起生效：切回影像底图时按 `baseLayers` 重新加载。若只配 `mapId`、未配 `baseLayers`，默认的卫星影像 + 街道地名图层会盖在基础影像之上。
 
 ### 3.2 config 统一配置对象
@@ -936,29 +937,103 @@ const layers = getAllLayers()               // 获取全部图层
 
 ### 4.8 等高线显示
 
-**功能简介**：通过替换地表材质，在 **3D 模式** 下叠加等高线（仅等高线、不叠加高程色带），2D 模式自动关闭。
+**功能简介**：通过替换地表材质，在 **3D 模式** 下叠加彩色等高线（黑色描边 + 彩色主线 + 高程色带），并可按需在当前视区叠加固定高程标签。2D 模式自动关闭。
+
+等高线渲染由随包发布的 `BigemapElevationContourLayer` 完成，**仅在首次开启等高线时动态加载**，地图初始化不加载该脚本。
 
 **支持的小功能**：
 
 - [切换等高线 setContourVisible](#切换等高线-setcontourvisible)
+- [加载高程标签 loadContourLabels](#加载高程标签-loadcontourlabels)
+- [移除高程标签 clearContourLabels](#移除高程标签-clearcontourlabels)
+- [高程图例 getContourLegend](#高程图例-getcontourlegend)
+- [等高线状态 contourState](#等高线状态-contourstate)
 - [等高线配置 contourConfig](#等高线配置-contourconfig)
 
 #### 切换等高线 `setContourVisible`
 
 ```ts
-api.setContourVisible(true)  // 开启等高线（仅 3D 生效）
-api.setContourVisible(false) // 关闭
+await api.setContourVisible(true) // 开启彩色等高线（仅 3D 生效）
+api.setContourVisible(false)      // 关闭
+```
+
+首次开启时需先加载等高线库，因此返回 `Promise`；库加载失败时开关自动回退为关闭状态。
+
+#### 加载高程标签 `loadContourLabels`
+
+按需读取当前视区地形高程，在跨越的等高线上放置固定高程标签。地图移动 / 缩放不会自动重算，避免持续占用主线程；需先开启等高线。
+
+```ts
+const result = await api.loadContourLabels()
+// { status, labelCount, error? }
+```
+
+| `status` | 含义 |
+| --- | --- |
+| `success` | 加载成功，`labelCount` 为标签数量 |
+| `no-results` | 当前视区未找到可标注的等高线 |
+| `terrain-loading` | 地形尚未加载完成，稍后重试 |
+| `unsupported` | 当前 SDK 不支持高程标签集合 |
+| `hidden` | 等高线未开启 |
+| `busy` | 上一次加载尚未完成 |
+| `error` | 加载异常，`error` 为原始错误对象 |
+
+#### 移除高程标签 `clearContourLabels`
+
+```ts
+const result = api.clearContourLabels()
+// { status: 'cleared' | 'empty' | 'busy' | 'destroyed', labelCount: 0 }
+```
+
+#### 高程图例 `getContourLegend`
+
+返回绘制 HTML 图例所需的数据副本（未开启等高线时返回 `null`）：
+
+```ts
+const legend = api.getContourLegend()
+// { minHeight, maxHeight, legendColorStep, colorStops: [{ height, color }, ...] }
+```
+
+#### 等高线状态 `contourState`
+
+```ts
+api.contourState.value
+// { enabled, labelsLoading, labelCount, contourSpacing, labelSpacing, contourWidth, outlineWidth }
 ```
 
 #### 等高线配置 `contourConfig`
 
 | 字段 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
-| `spacing` | `number` | `150` | 等高线间距（m） |
-| `width` | `number` | `2` | 等高线线宽（px） |
+| `contourSpacing` | `number` | `150` | 等高距（m） |
+| `contourWidth` | `number` | `2` | 彩色主线宽度（px） |
+| `outlineWidth` | `number` | `2` | 黑色描边宽度（px） |
+| `labelEvery` | `number` | `5` | 每隔多少条等高线显示一个高程标签 |
+| `maxLabels` | `number` | `28` | 当前视区最多显示的高程标签数量 |
+| `labelMinDistance` | `number` | `140` | 标签之间的最小屏幕间距（px） |
+| `labelOutlineWidth` | `number` | `3` | 标签文字描边宽度（px） |
+| `sampleStep` | `number` | `80` | 高程采样步长（px） |
+| `scanStep` | `number` | `120` | 视口扫描步长（px） |
+| `viewportMargin` | `number` | `48` | 视口边缘留白（px） |
+| `legendColorStep` | `number` | `500` | 图例色阶间隔（m） |
+| `minHeight` | `number` | 取色带首节点 | 色带最低高程（m） |
+| `maxHeight` | `number` | 取色带末节点 | 色带最高高程（m） |
+| `colorStops` | `ContourColorStop[]` | 内置 20 级色带 | 高程颜色节点 `{ height, color }`；配置后默认按首尾节点推导高程范围 |
 
 ```vue
-<MapContainer :config="{ contourConfig: { spacing: 100, width: 1.5 } }" />
+<MapContainer :config="{
+  contourConfig: {
+    contourSpacing: 100,
+    contourWidth: 2,
+    outlineWidth: 2,
+    labelEvery: 2,
+    colorStops: [
+      { height: 0, color: '#0066FF' },
+      { height: 3000, color: '#FF8A00' },
+      { height: 6000, color: '#00F078' }
+    ]
+  }
+}" />
 ```
 
 ---
@@ -1255,6 +1330,319 @@ api.setMapNameVisible(false) // 隐藏
 
 ---
 
+### 4.15 KML 数据加载
+
+**功能简介**：加载 KML 数据并渲染为地图要素，支持两种数据输入方式：远程地址（`loadKmlFromUrl`）与直接传入 KML 文本（`loadKmlFromText`）。自动解析 Placemark 的点 / 线 / 面（含 MultiGeometry 展开与内环「洞」）、共享样式（`Style` / `styleUrl` / `StyleMap`，含内联样式覆盖）与 `ExtendedData` 属性；2D / 3D 通用，模式切换自动重建。加载失败时给出中文提示，可通过状态直接展示，也可 `await` + `try/catch` 捕获。
+
+**支持的小功能**：
+
+- [地址加载 loadKmlFromUrl](#地址加载-loadkmlfromurl)
+- [文本加载 loadKmlFromText](#文本加载-loadkmlfromtext)
+- [KML XML 结构规范](#kml-xml-结构规范)
+- [生成 KML XML 并加载](#生成-kml-xml-并加载)
+- [切换显隐 setKmlVisible](#切换显隐-setkmlvisible)
+- [清除数据 clearKml](#清除数据-clearkml)
+- [加载状态 kmlState](#加载状态-kmlstate)
+
+#### 地址加载 `loadKmlFromUrl`
+
+```ts
+const result = await api.loadKmlFromUrl(url, config?)
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `url` | `string` | 是 | KML 文件地址，支持绝对地址（`http(s)://...`）与相对地址（如 `/chengdu.kml`）；仅支持 `http/https/blob/data` 协议 |
+| `config` | `KmlConfig` | 否 | 本次加载的配置，覆盖初始化时的默认配置 |
+
+返回值 `KmlLoadResult`：`featureCount`（要素数）、`polygonCount` / `lineCount` / `pointCount`（各几何数量）、`features`（解析后的要素，含 `properties` 属性，可供弹窗等二次消费）等。
+
+**示例**：
+
+```ts
+try {
+  const { featureCount } = await api.loadKmlFromUrl('/chengdu.kml')
+  console.log('已加载要素数：', featureCount)
+} catch (error) {
+  // 无效地址 / 网络失败 / HTTP 异常 / 解析失败 等均在此捕获
+  console.warn((error as Error).message)
+}
+```
+
+#### 文本加载 `loadKmlFromText`
+
+```ts
+const result = await api.loadKmlFromText(text, config?)
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `text` | `string` | 是 | KML 格式的 XML 文本内容，不能为空 |
+| `config` | `KmlConfig` | 否 | 本次加载的配置，覆盖初始化时的默认配置 |
+
+**示例**：
+
+```ts
+const response = await fetch('/chengdu.kml')
+const text = await response.text()
+const { featureCount } = await api.loadKmlFromText(text, { autoFlyTo: false })
+```
+
+**`config`（`KmlConfig`）参数表**：
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `fillColor` | `string` | `'#3d8bff'` | 面默认填充色（KML 未声明 `PolyStyle` 时使用） |
+| `fillAlpha` | `number` | `0.35` | 面默认填充透明度（0 ~ 1） |
+| `strokeColor` | `string` | `'#ffffff'` | 线 / 面轮廓默认颜色 |
+| `strokeAlpha` | `number` | `1` | 线 / 面轮廓默认透明度（0 ~ 1） |
+| `strokeWidth` | `number` | `2` | 线 / 面轮廓默认线宽（px） |
+| `pointColor` | `string` | `'#ff3b30'` | 点默认颜色 |
+| `pointPixelSize` | `number` | `8` | 点默认像素大小 |
+| `showLabel` | `boolean` | `true` | 是否显示要素名称标签（每个要素在代表点生成 1 个标签，随要素显隐） |
+| `labelColor` | `string` | `'#ffffff'` | 标签文字颜色 |
+| `labelFontSize` | `number` | `13` | 标签字号（px） |
+| `labelOutlineColor` | `string` | `'#000000'` | 标签文字描边颜色 |
+| `fillPalette` | `string[]` | `[]` | 按要素顺序轮换取色的调色板；非空时覆盖 KML 自身颜色（用于区分相邻区域），为空则不覆盖 |
+| `useKmlStyle` | `boolean` | `true` | 是否采用 KML 内联样式；`false` 时统一使用上述默认配色 |
+| `showFill` | `boolean` | `true` | 是否填充面（与 KML `PolyStyle.fill` 为「与」关系，两者同时为真才填充） |
+| `showOutline` | `boolean` | `true` | 是否绘制面外轮廓（与 KML `PolyStyle.outline` 为「与」关系） |
+| `extractProperties` | `boolean` | `true` | 是否解析 `ExtendedData` 到要素属性 |
+| `autoFlyTo` | `boolean` | `true` | 加载成功后是否自动飞行定位到数据范围 |
+| `timeout` | `number` | `15000` | 远程加载超时（ms），仅地址加载有效 |
+
+#### KML XML 结构规范
+
+插件内置解析器按标签名（`localName`）匹配，不区分命名空间前缀（`<kml>` 与 `<kml:kml>` 均可），因此只需保证标签名与层级正确。支持的标签子集如下：
+
+| 标签 | 出现位置 | 必需 | 说明 |
+| --- | --- | --- | --- |
+| `<kml>` | 根节点 | 是 | 根节点名必须是 `kml`，否则报 `PARSE_FAILED` |
+| `<Document>` / `<Folder>` | 可任意层级嵌套 | 否 | 用于分组，仅影响遍历；Placemark 会被递归收集，与嵌套深度无关 |
+| `<Placemark>` | Document / Folder 内 | 是（至少一个） | 一个要素；文档内无任何可渲染几何时报 `NO_FEATURES` |
+| `<name>` | Placemark 内 | 否 | 要素名，缺省时回退为 Placemark 的 `id`；同时作为地图上名称标签的文字 |
+| `<visibility>` | Placemark 内 | 否 | 值为 `0` 时该要素默认隐藏（整体显隐不会强制显示它） |
+| `<styleUrl>` | Placemark 内 | 否 | 引用样式 id，写法 `#styleId` |
+| `<Style id>` | Document 内（任意层级均可被收集） | 否 | 样式定义；写在 Placemark 内时作为内联样式，覆盖 `styleUrl` 引用的结果 |
+| `<LineStyle>` | Style 内 | 否 | 含 `<color>`（aabbggrr）与 `<width>`（px），作用于线与面轮廓 |
+| `<PolyStyle>` | Style 内 | 否 | 含 `<color>`、`<fill>`（`0`/`1`）、`<outline>`（`0`/`1`） |
+| `<IconStyle>` | Style 内 | 否 | 含 `<color>`、`<scale>`、`<Icon><href>` |
+| `<StyleMap id>` | Document 内 | 否 | 取 `normal` 分支的 `styleUrl`（可穿透引用，自动解引用到目标 Style） |
+| `<Point><coordinates>` | Placemark 内 | 否 | 单个坐标 |
+| `<LineString><coordinates>` | Placemark 内 | 否 | 至少 2 个坐标，不足则跳过该几何 |
+| `<Polygon>` | Placemark 内 | 否 | 外环 `<outerBoundaryIs><LinearRing><coordinates>` 至少 3 个坐标；洞用 `<innerBoundaryIs>` 表达，可多个 |
+| `<MultiGeometry>` | Placemark 内 | 否 | 其内部几何会被展开为多个几何，一个 Placemark 可产出多个面 |
+| `<ExtendedData>` | Placemark 内 | 否 | 支持 `<SchemaData><SimpleData name="...">值</SimpleData>` 与 `<Data name="..."><value>值</value></Data>` 两种写法，结果进入 `features[].properties` |
+| `<Schema>` | Document 内 | 否 | 仅作声明用，解析属性时不依赖它，可省略 |
+
+**四条必须遵守的编码规则**：
+
+1. **颜色是 `aabbggrr`，不是 `#rrggbb`**：8 位十六进制，字节序为「alpha、蓝、绿、红」，与 CSS 的 `#rrggbb` 正好相反，且 alpha 在前。
+   - 例：CSS `#4d90fe`（蓝）配 50% 透明度 → `50fe904d`（`50` = alpha，`fe` = 蓝，`90` = 绿，`4d` = 红）
+   - 换算：`alpha` 字节 = `round(透明度 × 255)` 的两位十六进制，其后依次拼 `bb`、`gg`、`rr`
+   - 也兼容 6 位 `rrggbb`（按不透明处理），非法值回退为默认配色
+2. **坐标格式为 `经度,纬度[,高程]`**：多个坐标元组之间用空白（空格或换行）分隔；高程省略时按 `0` 处理，非数字的元组会被跳过。
+3. **环必须首尾闭合**：`LinearRing` 的最后一个坐标应重复第一个坐标；洞（`innerBoundaryIs`）同样需要闭合。
+4. **无效几何只跳过自身**：不足 3 点的面、不足 2 点的线会被丢弃，不影响同文档其他要素；若整个文档一个可渲染几何都没有，则报 `NO_FEATURES`。
+
+**配色两种做法，二选一**：
+
+- 在 KML 里写 `<Style>` + `<styleUrl>`，由数据自身决定每个要素的颜色（适合颜色有业务含义的场景，见下方生成示例）；
+- 不在 KML 里写样式，改用配置项 `fillPalette` 让插件按要素顺序轮换取色（适合只想区分相邻区域的场景，无需生成样式）。
+
+#### 生成 KML XML 并加载
+
+下面的 `buildKml` 是一段自包含的生成函数（不依赖本库任何导出），把业务数据拼成 KML 文本，再交给 `loadKmlFromText` 加载。
+
+```ts
+/** #rrggbb + 透明度(0~1) → KML 的 aabbggrr */
+function toKmlColor(hex: string, alpha: number): string {
+  const r = parseInt(hex.slice(1, 3), 16)
+  const g = parseInt(hex.slice(3, 5), 16)
+  const b = parseInt(hex.slice(5, 7), 16)
+  const h2 = (v: number): string => v.toString(16).padStart(2, '0')
+  return `${h2(Math.round(alpha * 255))}${h2(b)}${h2(g)}${h2(r)}`
+}
+
+/** XML 文本转义（名称等业务字段可能含 & < > " '） */
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;').replace(/'/g, '&apos;')
+}
+
+interface Region {
+  /** 区域名称：会作为地图上的名称标签文字 */
+  name: string
+  /** 区域颜色 #rrggbb */
+  color: string
+  /** 外环坐标（可不闭合，生成时会自动补首点） */
+  ring: Array<{ lng: number; lat: number }>
+}
+
+function buildKml(regions: Region[]): string {
+  const lines: string[] = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<kml xmlns="http://www.opengis.net/kml/2.2">',
+    '  <Document id="root_doc">'
+  ]
+
+  // 1) 每个区域一条 Style，Placemark 通过 styleUrl 引用
+  regions.forEach((region, i) => {
+    lines.push(
+      `    <Style id="style_${i}">`,
+      `      <LineStyle><color>${toKmlColor(region.color, 1)}</color><width>2</width></LineStyle>`,
+      `      <PolyStyle><color>${toKmlColor(region.color, 0.35)}</color></PolyStyle>`,
+      '    </Style>'
+    )
+  })
+
+  // 2) 每个区域一个 Placemark：名称 + 属性 + 面
+  regions.forEach((region, i) => {
+    const name = escapeXml(region.name)
+    const ring = [...region.ring]
+    const first = ring[0]
+    const last = ring[ring.length - 1]
+    // 规则 3：环首尾闭合，末点补首点
+    if (first && last && (first.lng !== last.lng || first.lat !== last.lat)) {
+      ring.push(first)
+    }
+
+    lines.push(
+      `    <Placemark id="region_${i + 1}">`,
+      `      <name>${name}</name>`,
+      `      <styleUrl>#style_${i}</styleUrl>`,
+      '      <ExtendedData>',
+      '        <SchemaData schemaUrl="#region.schema">',
+      `          <SimpleData name="BM_Name">${name}</SimpleData>`,
+      `          <SimpleData name="Code">R${String(i + 1).padStart(3, '0')}</SimpleData>`,
+      '        </SchemaData>',
+      '      </ExtendedData>',
+      '      <Polygon>',
+      '        <outerBoundaryIs><LinearRing><coordinates>',
+      ...ring.map((p) => `          ${p.lng},${p.lat},0`),
+      '        </coordinates></LinearRing></outerBoundaryIs>',
+      '      </Polygon>',
+      '    </Placemark>'
+    )
+  })
+
+  lines.push('  </Document>', '</kml>')
+  return lines.join('\n')
+}
+```
+
+**用法一：生成后直接加载（推荐，不落地文件、无网络请求）**
+
+```ts
+const kmlText = buildKml([
+  {
+    name: '一号作业区',
+    color: '#3d8bff',
+    ring: [
+      { lng: 104.05, lat: 30.65 },
+      { lng: 104.12, lat: 30.65 },
+      { lng: 104.12, lat: 30.72 }
+    ]
+  },
+  {
+    name: '二号作业区',
+    color: '#ff9f0a',
+    ring: [
+      { lng: 104.14, lat: 30.65 },
+      { lng: 104.21, lat: 30.65 },
+      { lng: 104.21, lat: 30.72 }
+    ]
+  }
+])
+
+const { features } = await api.loadKmlFromText(kmlText)
+features[0].name        // '一号作业区'（即 <name>，也是地图上的标签文字）
+features[0].properties  // { BM_Name: '一号作业区', Code: 'R001' }（来自 <ExtendedData>）
+```
+
+**用法二：生成为 Blob URL 后按地址加载**
+
+`loadKmlFromUrl` 支持 `blob:` 协议，因此无需部署静态文件也能走地址加载链路：
+
+```ts
+const blob = new Blob([kmlText], { type: 'application/vnd.google-earth.kml+xml' })
+const objectUrl = URL.createObjectURL(blob)
+try {
+  await api.loadKmlFromUrl(objectUrl)
+} finally {
+  URL.revokeObjectURL(objectUrl)
+}
+```
+
+**用法三：落地为 `.kml` 文件后由静态服务提供**
+
+把 `kmlText` 存成文件（如 `public/regions.kml`），再 `api.loadKmlFromUrl('/regions.kml')`。适合数据量较大、需被多次复用或由后端直接下发的场景。
+
+**关于名称标签**：`<name>` 的内容会渲染为地图上的名称标签，落点取面的包围盒中心（`MultiGeometry` 取面积最大的那个面；线取中点、点取自身坐标），文字默认白字黑描边。`showLabel` 默认为 `true`，不需要标签时加载传 `{ showLabel: false }` 即可；字号与颜色可经 `labelFontSize` / `labelColor` / `labelOutlineColor` 调整。
+
+#### 切换显隐 `setKmlVisible`
+
+```ts
+api.setKmlVisible(false) // 隐藏全部 KML 要素（保留数据）
+api.setKmlVisible(true)  // 重新显示
+```
+
+整体显隐与 KML 要素自身 `visibility` 叠加生效：KML 中 `visibility=0` 的要素不会被整体显隐强制显示。
+
+#### 清除数据 `clearKml`
+
+```ts
+api.clearKml() // 移除实体、清空数据并复位状态
+```
+
+#### 加载状态 `kmlState`
+
+响应式状态 `api.kmlState`，字段如下：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `status` | `'idle' \| 'loading' \| 'success' \| 'error'` | 加载状态 |
+| `source` | `'url' \| 'text' \| null` | 数据来源 |
+| `url` | `string` | 数据来源地址（`source` 为 `url` 时有效） |
+| `featureCount` | `number` | 要素（Placemark）数量 |
+| `polygonCount` | `number` | 面（Polygon）数量 |
+| `lineCount` | `number` | 线（LineString）数量 |
+| `pointCount` | `number` | 点（Point）数量 |
+| `visible` | `boolean` | 是否显示中 |
+| `error` | `string \| null` | 错误提示（`status` 为 `error` 时有效） |
+
+**错误提示说明**：加载失败时统一抛出 `KmlError`（含 `code` 与中文 `message`），并将提示写入 `kmlState.error`，两种方式可任选：
+
+```ts
+// 方式一：直接绑定状态渲染提示（无需 try/catch）
+api.loadKmlFromUrl(url).catch(() => {})
+
+// 方式二：捕获异常按错误码分支处理
+import { KmlError, KmlErrorCode } from 'bigmap-plugin'
+try {
+  await api.loadKmlFromText(text)
+} catch (error) {
+  if (error instanceof KmlError && error.code === KmlErrorCode.PARSE_FAILED) {
+    console.warn('KML 格式有误：', error.message)
+  }
+}
+```
+
+| 错误码 `KmlErrorCode` | 触发场景 |
+| --- | --- |
+| `INVALID_URL` | 地址为空、非字符串或不支持的协议 |
+| `INVALID_TEXT` | 文本为空或非字符串 |
+| `PARSE_FAILED` | XML 格式错误或根节点不是 `<kml>` |
+| `NO_FEATURES` | 解析成功但无任何可渲染几何（如空文档） |
+| `NETWORK_FAILED` | 请求发起失败或读取响应内容失败 |
+| `HTTP_ERROR` | 服务器返回非 2xx 状态码 |
+| `TIMEOUT` | 远程加载超时 |
+| `MAP_NOT_READY` | 地图尚未初始化完成 |
+| `LOAD_FAILED` | 其他异常的统一兜底 |
+
+---
+
 ## 5. Composable 独立使用
 
 除通过 `MapContainer` 组件使用外，也可在自定义 `<script setup>` 中直接组合 `composable`，获得更细粒度的控制。所有 composable 均通过具名导出引入：
@@ -1271,6 +1659,7 @@ import {
   useMapContour,
   useMapTrajectory,
   useMapMask,
+  useMapKml,
   useMapWeather,
   useMapLighting,
 } from 'bigmap-plugin'
@@ -1287,9 +1676,10 @@ import {
 | `useMapPopup(map, event?, options?)` | 点位弹窗 | `showPointPopup` / `removePopup` / `isPopupVisible` / `getCurrentPopupData` |
 | `useMapCircleWave(map)` | 圆形波动 | `addWave` / `removeWave` |
 | `useMapLayers(map)` | 图层管理 | `addImageryLayer` / `addWmtsLayer` / `removeLayer` / `removeAllLayers` / `setLayerVisible` / `setLayerOpacity` |
-| `useMapContour(map, config?)` | 等高线 | `setContourVisible` / `reapply` / `remove` |
+| `useMapContour(map, config?, deps?)` | 彩色等高线 | `setContourVisible` / `loadLabels` / `clearLabels` / `getLegendData` / `reapply` / `remove` |
 | `useMapTrajectory(map, config?, deps?)` | 轨迹回放 | `load` / `play` / `pause` / `stop` / `setSpeed` / `jumpTo` / `clear` / `reapply` / `destroy` |
 | `useMapMask(map, config?)` | 遮罩反选 | `setMask` / `setVisible` / `clear` / `reapply` / `remove` / `destroy` |
+| `useMapKml(map, config?)` | KML 数据加载 | `loadFromUrl` / `loadFromText` / `getFeatures` / `setVisible` / `flyTo` / `remove` / `clear` / `reapply` / `destroy` |
 | `useMapWeather(map, config?)` | 天气特效 | `setWeather` / `clear` / `destroy` |
 | `useMapLighting(map, config?, options?)` | 3D 光源 | `setEnabled` / `setPeriod` / `apply` / `destroy` |
 
@@ -1361,7 +1751,7 @@ const load = async () => {
 
 **Q5：等高线 / 3D 光源不生效？**
 
-两者**仅 3D 模式**有效，切到 2D 会自动关闭 / 还原。
+两者**仅 3D 模式**有效，切到 2D 会自动关闭 / 还原。等高线还需确认等高线库可访问：首次开启时会从 `libsUrl`（默认 `/libs`）加载 `libs/bigemap/BigemapElevationContourLayer.js`，若该资源不可达则开关会自动回退为关闭，控制台会输出加载失败日志。
 
 **Q6：轨迹加载后不动？**