@ywbgn/bgl-package 1.0.0 → 1.2.1

package/README.md

@@ -1,13 +1,19 @@
 # @ywbgn/bgl-package
 
-基于 Vue 3 与 `@arcgis/core` 的地图组件库：地图初始化、底图切换（含自定义矢量示例）、工具栏（缩放、复位、测距、测面、绘图、清绘）。
+基于 Vue 3 与 `@arcgis/core` 的地图组件库：地图初始化、底图切换、底图卷帘、工具栏（全图、全屏、缩放、定位、测距、测面、图层管理、业务卷帘、地图标注、条件查询）、**空间分析面板**（`SpatialAnalysisPanel`），业务图层加载 / Portal Token 注册，以及平移边界约束（`panBounds` / `applyPanBoundsConstraint`）。
 
 ## 安装依赖
 
 ```bash
-npm install @ywbgn/bgl-package vue @arcgis/core
+npm install @ywbgn/bgl-package vue @arcgis/core@~4.34.8
 ```
 
+**版本约定（作子系统模版时请对齐）：**
+
+- peer：`@arcgis/core@~4.34.8`（允许 `4.34.8`～`<4.35.0` 补丁，不自动升到 4.35）
+- 业务项目建议同样使用 `"@arcgis/core": "~4.34.8"`
+- 升级到 4.35+ 需先在本库回归验证，再同步改 peer 与各子系统依赖
+
 ## 引入依赖与注册
 
 ```js
@@ -21,47 +27,677 @@ app.use(VueArcgisMap)
 app.mount('#app')
 ```
 
-## 使用示例
+按需引入（不全局注册）：
+
+```js
+import {
+  ArcgisMap,
+  BasemapSwitch,
+  SwipeCompare,
+  MapToolbar,
+  provideBasemapKeys,
+  loadBusinessLayers,
+  registerPortalToken,
+  startPortalTokenRenewal,
+  applyPanBoundsConstraint,
+  goToFullExtent
+} from '@ywbgn/bgl-package'
+import type {
+  BasemapKeys,
+  BusinessLayerConfig,
+  MapReadyPayload,
+  ToolbarToolId,
+  LonLatExtent,
+  PanConstraintHandle
+} from '@ywbgn/bgl-package'
+```
+
+## 快速接入
+
+1. 先拿到底图密钥 / 系统参数（含 `minZoom` / `maxZoom` / 经纬度范围），再挂 `ArcgisMap`（密钥只在挂载时读一次，可用 `v-if` 等配置就绪后再渲染）。
+2. `@ready` 里用 `shallowRef` 保存 `view` / `sketchLayer` / `map`。
+3. 需要时再挂 `BasemapSwitch`、`SwipeCompare`、`MapLegend`、`MapScaleBar`、`MapToolbar`。
+4. 有经纬度范围时：给 `ArcgisMap` 传 `:pan-bounds`（自动限制拖动），给 `MapToolbar` 传 `:home-extent`（全图回到范围中心 + minZoom）。
+5. 在 `ready` 后 `startPortalTokenRenewal`（或 `registerPortalToken`）→ `loadBusinessLayers`；卸载时对续期调用 `stop()`。
+6. 切底图前同时拆除**底图卷帘**与**工具栏业务卷帘**。
 
 ```vue
 <template>
-  <div style="position: relative">
-    <ArcgisMap ref="mapRef" width="100%" height="600px" @ready="onReady" />
+  <div class="map-page">
+    <ArcgisMap
+      v-if="mapReady"
+      width="100%"
+      height="600px"
+      :zoom="zoom"
+      :center="center"
+      :min-zoom="minZoom"
+      :max-zoom="maxZoom"
+      :pan-bounds="extent"
+      @ready="onReady"
+    />
     <template v-if="view && sketchLayer">
-      <BasemapSwitch :view="view" />
-      <MapToolbar :view="view" :sketch-layer="sketchLayer" />
+      <BasemapSwitch :view="view" @before-change="onBeforeBasemapChange" />
+      <SwipeCompare ref="swipeCompareRef" :view="view" />
+      <MapLegend :view="view" position="left" :offset-x="12" :offset-y="14" />
+      <MapScaleBar :view="view" position="left" :offset-x="170" :offset-y="14" />
+      <MapToolbar
+        ref="mapToolbarRef"
+        :view="view"
+        :sketch-layer="sketchLayer"
+        :home-extent="extent"
+      />
     </template>
   </div>
 </template>
 
-<script setup>
-import { ref, shallowRef } from 'vue'
+<script setup lang="ts">
+import { onMounted, ref, shallowRef } from 'vue'
+import type MapView from '@arcgis/core/views/MapView.js'
+import type GraphicsLayer from '@arcgis/core/layers/GraphicsLayer.js'
+import {
+  ArcgisMap,
+  BasemapSwitch,
+  MapLegend,
+  MapScaleBar,
+  MapToolbar,
+  SwipeCompare,
+  loadBusinessLayers,
+  provideBasemapKeys,
+  registerPortalToken
+} from '@ywbgn/bgl-package'
+import type { BasemapKeys, BusinessLayerConfig, LonLatExtent, MapReadyPayload } from '@ywbgn/bgl-package'
+
+const mapReady = ref(false)
+const view = shallowRef<MapView | null>(null)
+const sketchLayer = shallowRef<GraphicsLayer | null>(null)
+const swipeCompareRef = ref<InstanceType<typeof SwipeCompare> | null>(null)
+const mapToolbarRef = ref<InstanceType<typeof MapToolbar> | null>(null)
+const zoom = ref(8)
+const center = ref<[number, number]>([116.4, 39.9])
+const minZoom = ref<number | null>(8)
+const maxZoom = ref<number | null>(18)
+const extent = ref<LonLatExtent | null>(null)
+
+const basemapKeys = ref<BasemapKeys>({})
+provideBasemapKeys(basemapKeys)
+
+let businessLayers: BusinessLayerConfig[] = []
 
-const mapRef = ref(null)
-const view = shallowRef(null)
-const sketchLayer = shallowRef(null)
+onMounted(async () => {
+  // 伪代码：从业务接口拉取密钥、缩放上下限、jw 范围、图层配置后再挂地图
+  // basemapKeys.value = ...
+  // minZoom.value = ...
+  // maxZoom.value = ...
+  // extent.value = { xmin, ymin, xmax, ymax }
+  // businessLayers = ...
+  mapReady.value = true
+})
 
-const onReady = ({ view: v, sketchLayer: layer }) => {
-  view.value = v
-  sketchLayer.value = layer
+const onReady = async (payload: MapReadyPayload) => {
+  view.value = payload.view
+  sketchLayer.value = payload.sketchLayer
+  // minZoom / maxZoom / panBounds 已由 ArcgisMap 内部应用
+
+  // 如需 Portal 鉴权再注册 token（生产建议后端签发，勿长期在前端存密码）
+  // await registerPortalToken({ portalUrl, username, password, extraServers, tokenServiceUrl })
+
+  loadBusinessLayers({
+    map: payload.map,
+    layers: businessLayers,
+    reverse: true
+  })
+}
+
+/** 切底图前拆除底图卷帘 + 业务图层卷帘 */
+const onBeforeBasemapChange = () => {
+  swipeCompareRef.value?.destroySwipe()
+  mapToolbarRef.value?.destroySwipe()
 }
 </script>
+
+<style scoped>
+.map-page {
+  position: relative;
+  --bgl-toolbar-bottom: 14px;
+}
+</style>
+```
+
+## 组件说明
+
+### 通用输入组件
+
+组件库提供统一深色主题样式的 `BglInput` 和 `BglSelect`，支持全局注册或按需引入。使用组件前请引入组件库样式：
+
+```ts
+import '@ywbgn/bgl-package/style.css'
+```
+
+使用 `app.use(VueArcgisMap)` 全局注册后，可以直接在模板中使用：
+
+```vue
+<template>
+  <BglInput v-model="keyword" placeholder="请输入关键字" />
+  <BglSelect v-model="status" :options="statusOptions" placeholder="请选择状态" />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const keyword = ref('')
+const status = ref('')
+const statusOptions = [
+  { value: 'active', label: '有效' },
+  { value: 'inactive', label: '无效' }
+]
+</script>
+```
+
+按需引入时，在页面组件中直接导入：
+
+```ts
+import { BglInput, BglSelect } from '@ywbgn/bgl-package'
+```
+
+#### BglInput
+
+```vue
+<BglInput
+  v-model="year"
+  type="number"
+  min="1900"
+  max="2200"
+  placeholder="请输入年份"
+  :disabled="loading"
+/>
+```
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelValue` | `string \| number` | `''` | `v-model` 双向绑定值 |
+| `type` | `string` | `'text'` | 原生输入类型，例如 `text`、`number` |
+| `placeholder` | `string` | `''` | 占位文案 |
+| `disabled` | `boolean` | `false` | 是否禁用输入框 |
+| `min` / `max` | `string \| number` | 无 | 原生数值范围属性 |
+
+输入内容变化时触发 `update:modelValue` 事件。即使 `type="number"`，组件发出的值仍是输入框产生的字符串，需要数值时请在业务侧自行转换。
+
+#### BglSelect
+
+选项值和当前绑定值均使用字符串：
+
+```vue
+<BglSelect
+  v-model="selectedStatus"
+  :options="statusOptions"
+  placeholder="请选择状态"
+  :disabled="loading"
+/>
+```
+
+```ts
+const selectedStatus = ref('')
+const statusOptions = [
+  { value: 'active', label: '有效' },
+  { value: 'inactive', label: '无效', disabled: true }
+]
+```
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelValue` | `string` | `''` | 当前选中值，支持 `v-model` |
+| `options` | `{ value: string; label: string; disabled?: boolean }[]` | `[]` | 下拉选项 |
+| `placeholder` | `string` | `'请选择'` | 没有匹配选中值时的占位文案 |
+| `open` | `boolean` | `false` | 是否展开下拉框，可用于受控展开 |
+| `disabled` | `boolean` | `false` | 是否禁用下拉框 |
+
+组件事件：
+
+- `update:modelValue(value)`：选中选项时触发，可通过 `v-model` 接收。
+- `select(value)`：选中选项时触发，参数为选项的 `value`。
+- `update:open(open)`：展开状态变化时触发。点击触发按钮、按 `Esc` 或点击组件外部时会更新为 `false`。
+
+需要由业务侧控制展开状态时：
+
+```vue
+<BglSelect
+  :model-value="selectedStatus"
+  :options="statusOptions"
+  :open="selectOpen"
+  @select="selectedStatus = $event"
+  @update:open="selectOpen = $event"
+/>
+```
+
+### ArcgisMap
+
+| Prop / 能力               | 说明                                                                                               |
+| ------------------------- | -------------------------------------------------------------------------------------------------- |
+| `width` / `height`    | 尺寸，支持数字（px）或 CSS 字符串                                                                  |
+| `zoom` / `center`     | 初始与可监听更新的缩放、中心`[经度, 纬度]`                                                       |
+| `keys`                  | 底图密钥；也可上层`provideBasemapKeys`                                                           |
+| `minZoom` / `maxZoom` | 写入`view.constraints` 的缩放上下限                                                              |
+| `panBounds`             | 经纬度矩形`{ xmin, ymin, xmax, ymax }`；传入后自动限制拖动，并在程序化 `goTo` 期间临时放开约束 |
+| 事件`ready`             | 载荷`MapReadyPayload`（`map` / `view` / `sketchLayer`）                                    |
+
+- 默认底图优先级：天地图影像 → 星图 → 吉林一号 → ArcGIS 影像
+- `panBounds` 在 view ready 后自动调用 `applyPanBoundsConstraint` + `wrapViewGoTo`；组件卸载时自动清理
+- 有 `panBounds` 时，初始会定位到范围中心 + `minZoom`（与「全图」一致）
+
+### BasemapSwitch（底图切换）
+
+- 必填 `view`
+- 可选 `keys`
+- 事件 `before-change`：成功切换底图**前**触发（用于拆卷帘）
+
+可选底图：天地图影像 / 矢量、星图地球、吉林一号、ArcGIS 影像。缺 Key 时可选中，切换时会提示。
+
+### SwipeCompare（底图卷帘）
+
+- 左下角入口，对比**底图影像**
+- 方法 `destroySwipe()`：拆除 Swipe 并移除左侧对比层
+
+### MapToolbar（工具栏）
+
+内置工具：全图、全屏、放大、缩小、坐标定位、距离测量、面积测量、图层管理、业务图层卷帘、地图标注、条件查询。
+
+| Prop / 能力                | 说明                                                                     |
+| -------------------------- | ------------------------------------------------------------------------ |
+| `view` / `sketchLayer` | 必填                                                                     |
+| `layerIdPrefix`          | 业务图层 id 前缀，默认`bgl-biz-`（需与 `loadBusinessLayers` 一致）   |
+| `tools`                  | 白名单；不传则全量                                                       |
+| `hiddenTools`            | 黑名单；与`tools` 同传时以 `tools` 为准                              |
+| `showCoordinate`         | 是否显示经纬度条，默认`true`                                           |
+| `homeExtent`             | 全图经纬度范围；优先调用`goToFullExtent`（minZoom + 范围中心）         |
+| `homeCenter`             | 无`homeExtent` 时回退：回到该中心 + `minZoom`                        |
+| `delegateFullExtent`     | 为`true` 时全图只抛 `fullExtent` 事件，由业务侧自行定位              |
+| `coordinateSystemConfig` | 坐标定位面板动态坐标系配置；不传则使用内置默认 5 项                 |
+| `#extra`                 | 工具条末尾自定义按钮                                                     |
+| 事件                       | `fullExtent` / `layerManage` / `swipeCompare` / `conditionQuery` |
+| `destroySwipe()`         | 拆除**业务图层**卷帘                                               |
+
+工具 id（`ToolbarToolId`）：
+
+`fullExtent` | `fullscreen` | `zoomIn` | `zoomOut` | `coordinateLocate` | `distanceMeasure` | `areaMeasure` | `layerManage` | `layerSwipe` | `mapLabel` | `conditionQuery`
+
+```vue
+<MapToolbar
+  :view="view"
+  :sketch-layer="sketchLayer"
+  :home-extent="extent"
+  :coordinate-system-config="coordinateSystemConfig"
+  :tools="['fullExtent', 'fullscreen', 'zoomIn', 'zoomOut', 'distanceMeasure', 'areaMeasure', 'layerManage']"
+  :show-coordinate="true"
+>
+  <template #extra>
+    <button type="button" data-tip="业务分析" aria-label="业务分析" @click="onBiz" />
+  </template>
+</MapToolbar>
+```
+
+```ts
+const coordinateSystemConfig = {
+  defaultWkid: 4509,
+  options: [
+    { wkid: 4490, label: '经纬度' },
+    { wkid: 4548, label: '3度带-不带号' },
+    { wkid: 4527, label: '3度带-带号' },
+    { wkid: 4509, label: '6度带-不带号' },
+    { wkid: 4498, label: '6度带-带号' }
+  ]
+}
+```
+
+#### 全图 / 全屏说明
+
+| 工具 | 行为                                                                                              |
+| ---- | ------------------------------------------------------------------------------------------------- |
+| 全图 | 有`homeExtent` 时：`goToFullExtent`（范围中心 + minZoom）；否则用 `homeCenter` / 仅 minZoom |
+| 全屏 | 对`document.documentElement` 请求整页全屏（接近 F11），再次点击或 Esc 退出                      |
+
+#### 内置面板说明
+
+| 工具     | 作用                                     | 注意                                                 |
+| -------- | ---------------------------------------- | ---------------------------------------------------- |
+| 图层管理 | 业务层显隐、透明度、排序、定位           | 仅识别`layerIdPrefix` 前缀图层；若加载时做过坐标系校验，不一致图层会标记「坐标系不一致」 |
+| 卷帘对比 | 选左右**业务层**做 Swipe           | 与底图卷帘互斥（应用时自动拆另一侧）                 |
+| 坐标定位 | 按所选坐标系输入或拾取坐标后定位         | `coordinateSystemConfig` 可由业务系统动态下发默认坐标系与可选项 |
+| 地图标注 | 按字段设置`labelingInfo`               | 仅**FeatureLayer**；MapImageLayer 不出现在列表 |
+| 条件查询 | 拼 WHERE →`queryFeatures` → 定位高亮 | 仅 FeatureLayer；字段值去重最多约 1000 条            |
+
+### MapLegend（图例，独立常开）
+
+与底图切换、卷帘一样单独挂载，**不在工具栏内**；默认常开，基于 ArcGIS `Legend` 微件。
+
+- 只展示业务图层（`idPrefix` 前缀，默认 `bgl-biz-`）
+- 排除 `listMode === 'hide'` 的图层（如绘制层）
+- `map.layers` 变化时自动同步图例项
+
+```vue
+<MapLegend
+  :view="view"
+  position="left"
+  :offset-x="12"
+  :offset-y="14"
+/>
+```
+
+| Prop         | 说明                                                             |
+| ------------ | ---------------------------------------------------------------- |
+| `view`     | 必填                                                             |
+| `idPrefix` | 业务层前缀，默认`bgl-biz-`（需与 `loadBusinessLayers` 一致） |
+| `position` | `'left'` \| `'right'`，默认 `left`（右侧有业务抽屉时用左） |
+| `offsetX`  | 水平边距（px），默认`12`                                       |
+| `offsetY`  | 相对地图底边抬高（px），默认`14`                               |
+
+默认尺寸 **150×240px**（可用 CSS 变量 `--bgl-legend-width` / `--bgl-legend-height` 覆盖）。
+层级默认约 `1050`，可用 `--bgl-legend-z` 覆盖。
+
+与比例尺同侧时，建议比例尺加大 `offsetX`（例如图例 `12`、比例尺 `170`），避免重叠。
+
+### MapScaleBar（比例尺，独立常开）
+
+独立挂载，**不在工具栏内**；封装 ArcGIS `ScaleBar`，缩放时自动更新。定位 API 与 `MapLegend` 对齐。
+
+```vue
+<MapScaleBar
+  :view="view"
+  position="left"
+  :offset-x="170"
+  :offset-y="14"
+  unit="metric"
+  bar-style="line"
+  :show-numeric-scale="true"
+  :numeric-scale-use-grouping="true"
+  :numeric-scale-formatter="(scale) => `比例 1:${scale.toLocaleString()}`"
+  panel-background="rgba(24, 32, 42, 0.94)"
+  panel-border-color="rgba(255, 255, 255, 0.18)"
+  graphic-label-color="#ffffff"
+  numeric-label-color="rgba(255, 255, 255, 0.96)"
+/>
+```
+
+| Prop                      | 说明                                                                                              |
+| ------------------------- | ------------------------------------------------------------------------------------------------- |
+| `view`                    | 必填                                                                                              |
+| `position`                | `'left'` \| `'right'`，默认 `left`                                                                |
+| `offsetX`                 | 水平边距（px），默认`12`                                                                          |
+| `offsetY`                 | 相对地图底边抬高（px），默认`14`                                                                  |
+| `unit`                    | `'metric'`（公制）\| `'imperial'`（英制）\| `'dual'`（双单位），默认 `metric`                   |
+| `barStyle`                | `'line'`（线型）\| `'ruler'`（尺型），默认 `line`                                                 |
+| `showNumericScale`        | 是否显示实时数字比例尺（如 `1:40,000`），默认 `false`                                             |
+| `numericScaleUseGrouping` | 数字比例尺是否显示千分位，默认 `true`                                                             |
+| `numericScaleFormatter`   | 自定义数字比例尺格式化函数 `(scale: number) => string`；传入后优先级高于 `numericScaleUseGrouping` |
+| `panelBackground`         | 外层容器背景色；不传则用默认深色                                                                  |
+| `panelBorderColor`        | 外层容器边框色                                                                                    |
+| `graphicLabelColor`       | 图形比例尺标题颜色                                                                                |
+| `numericLabelColor`       | 数字比例尺文字颜色                                                                                |
+
+说明：
+
+- 创建前会等待 `view.when()` 与一帧布局，避免容器宽高为 0 时算不出刻度长度
+- `view` / `unit` / `barStyle` 变化会重建微件；卸载时自动 `destroy`
+- 数字比例尺直接读取 ArcGIS `MapView.scale`，格式化为 `1:N` 文本，并随缩放、平移、全图、全屏和视口变化实时更新
+- `numericScaleUseGrouping` 可关闭千分位；如需完全自定义文本，直接传 `numericScaleFormatter`
+- `panelBackground` / `panelBorderColor` / `graphicLabelColor` / `numericLabelColor` 会以内联 CSS 变量方式写入，适合做轻量主题覆盖
+- 组件会读取 ArcGIS 原生图形比例尺标题文案，并在容器上方自行居中渲染，避免默认标题在定制样式下偏移
+- `showNumericScale` 开启后，会在图形比例尺下方追加一行数字比例尺文本；图形比例尺长度与刻度计算仍由 ArcGIS 原生 `ScaleBar` 负责
+- 图形标题自绘依赖当前 ArcGIS `ScaleBar` 内部 `.esri-scale-bar__label` 文案；升级 `@arcgis/core` 时请回归检查比例尺标题是否仍可正常读取
+- 容器 `pointer-events: none`，不挡地图拖拽
+- 层级默认 `100`（与底图切换、图例、工具栏一致），可用 `--bgl-scalebar-z` 覆盖
+
+## 平移边界约束
+
+基于 ArcGIS `view.constraints.geometry`（只约束**视图中心点**）：按当前可视范围反推中心点合法活动区域，效果上等价于「经纬度矩形始终不拖出屏幕」。所有缩放级别均生效；拖到边缘直接停住，不做回弹。
+
+推荐优先用组件 props（见上 `ArcgisMap.panBounds` + `MapToolbar.homeExtent`）。也可直接调用工具函数：
+
+```ts
+import {
+  applyPanBoundsConstraint,
+  goToFullExtent
+} from '@ywbgn/bgl-package'
+import type { LonLatExtent, PanConstraintHandle } from '@ywbgn/bgl-package'
+
+const extent: LonLatExtent = {
+  xmin: 116.3,
+  ymin: 43.8,
+  xmax: 119.4,
+  ymax: 45.4
+}
+
+// 手动挂约束（组件卸载时务必 handle.remove()）
+const handle: PanConstraintHandle = await applyPanBoundsConstraint(view, extent)
+handle.wrapViewGoTo(view) // 坐标定位等程序化 goTo 期间临时放开约束
+
+await goToFullExtent(view, extent) // 回到范围中心 + minZoom
+
+// 卸载
+handle.remove()
+```
+
+| API                                        | 说明                                                        |
+| ------------------------------------------ | ----------------------------------------------------------- |
+| `LonLatExtent`                           | `{ xmin, ymin, xmax, ymax }`，WGS84 经纬度                |
+| `applyPanBoundsConstraint(view, extent)` | 挂平移约束并初始定位到全图；返回`PanConstraintHandle`     |
+| `handle.wrapViewGoTo(view)`              | 包装`view.goTo`，定位期间临时放开约束                     |
+| `handle.remove()`                        | 释放 watch，恢复原始`goTo`，清空 `constraints.geometry` |
+| `goToFullExtent(view, extent)`           | 定位到范围中心 +`constraints.minZoom`                     |
+
+## 两套卷帘（务必区分）
+
+| 组件                    | 对比对象 | 入口       |
+| ----------------------- | -------- | ---------- |
+| `SwipeCompare`        | 底图     | 地图左下角 |
+| `MapToolbar` 卷帘对比 | 业务图层 | 底部工具栏 |
+
+应用任一侧卷帘时，库内会通过 `swipe-registry` **自动拆除另一侧**。切底图时仍建议两边都 `destroySwipe()`，或调用导出的 `destroyAllSwipes()`。
+
+## 业务图层与 Portal
+
+### loadBusinessLayers
+
+```ts
+import { loadBusinessLayers, BUSINESS_LAYER_ID_PREFIX } from '@ywbgn/bgl-package'
+import type { BusinessLayerConfig } from '@ywbgn/bgl-package'
+
+const layers = loadBusinessLayers({
+    map,
+    layers: configs,
+    reverse: true,
+    idPrefix: BUSINESS_LAYER_ID_PREFIX,
+    // labelConfigs: [...]  // 见下文「业务图层注记」
+    // expectedSpatialReferenceWkid: 8848, // 系统参数；8848=CGCS2000_Albers，其他为 WKID
+  })
 ```
 
-`ArcgisMap` 支持以下尺寸参数：
+`BusinessLayerConfig` 主要字段（对齐常见 `mapServiceSettings`）：
+
+- `id` / `mapServiceUrl` / `mapServiceName`
+- `layerVisible` / `layerOrder`
+- `mapServiceType`：`1`=MapServer，`2`=FeatureServer
+- `scaleConfig` / `minScale` / `maxScale`：仅当 `scaleConfig` 为真时写入图层的 `minScale`/`maxScale`；为假时不写配置值（保留服务端自带比例尺）
+
+加载规则简述：
+
+- MapServer **根地址** → `MapImageLayer`
+- FeatureServer 或 `MapServer/N` → `FeatureLayer`
+- 同 id 重复加载会先 `remove` 并 `destroy` 旧层
+- 可选传入 `expectedSpatialReferenceWkid`（通常来自系统参数 `systemCoordinate`）：
+  - `8848` 为业务哨兵，按 `CGCS2000_Albers` WKT 作为期望坐标系（与参考项目一致，不是 EPSG:8848）
+  - 其他值按 WKID 比较
+  - 比较规则：优先 `wkid/latestWkid`，否则规范化后比 `wkt`
+  - 结果分 `match` / `mismatch` / `unreadable`：仅 `mismatch` 登记图层管理红标；`unreadable` 只回调/打日志
+  - 默认 `console.warn`，**不拦截上图**
+- 不一致记录会登记到组件内，图层管理面板会显示「坐标系不一致」标记，并在顶部汇总数量
+- 注意：`systemCoordinate` 表示业务图层期望坐标系；坐标定位面板默认输入坐标系仍优先使用 `latitudeLongitude`（经纬度）
+
+### 业务图层注记（地图上显示属性字段）
 
-- `width`：默认 `100%`，支持 `String | Number`（`Number` 按 `px` 处理）
-- `height`：默认 `70vh`，支持 `String | Number`（`Number` 按 `px` 处理）
+对齐 forestpests：前端配置指定图层的 `labelingInfo`（Arcade + 描边样式），**不依赖**后端 mapServiceSettings。
+
+```ts
+import { loadBusinessLayers, applyBusinessLayerLabels } from '@ywbgn/bgl-package'
+import type { BusinessLayerLabelConfig } from '@ywbgn/bgl-package'
+
+const labelConfigs: BusinessLayerLabelConfig[] = [
+  {
+    title: '森林病虫害防治（亩）',
+    fields: ['fzmj', 'lycsh'],
+    fieldTemplate: '({0} 亩)({1})',
+    style: {
+      color: [26, 127, 55, 1],
+      fontSize: 11,
+      fontWeight: 'bold',
+      haloColor: [255, 255, 255, 1],
+      haloSize: 1.5,
+      labelPlacement: 'center-center'
+    }
+  },
+  {
+    // 也可按业务配置 id 匹配（自动加 bgl-biz- 前缀）
+    layerId: 12,
+    expression: '"(" + Text($feature["whmj"]) + " 亩)(" + Text($feature["hclx"]) + ")"',
+    style: { color: [207, 46, 6, 1], fontSize: 11, fontWeight: 'bold' }
+  }
+]
+
+loadBusinessLayers({
+  map,
+  layers: configs,
+  reverse: true,
+  labelConfigs
+})
+
+// 或图层已在图上时单独调用
+// applyBusinessLayerLabels(map, labelConfigs)
+```
+
+注意：仅 **FeatureLayer** 生效；与工具栏「地图标注」可并存（手动标注会覆盖该层 `labelingInfo`）。
+
+### registerPortalToken / startPortalTokenRenewal
+
+单次注册：
+
+```ts
+await registerPortalToken({
+  portalUrl: 'https://example.com',
+  username: '...',
+  password: '...',
+  expirationMinutes: 120,
+  extraServers: ['https://gis.example.com/server'],
+  // 开发环境可走本地代理，避免 generateToken 跨域
+  tokenServiceUrl: import.meta.env.DEV
+    ? '/gis-portal/portal/sharing/rest/generateToken'
+    : undefined
+})
+```
+
+长会话建议用自动续期（默认在过期前约 1/6 有效期刷新；页面卸载时 `stop()`）：
+
+```ts
+const renewal = await startPortalTokenRenewal({
+  portalUrl: 'https://example.com',
+  username: '...',
+  password: '...',
+  expirationMinutes: 120,
+  extraServers: ['https://gis.example.com/server'],
+  tokenServiceUrl: import.meta.env.DEV
+    ? '/gis-portal/portal/sharing/rest/generateToken'
+    : undefined,
+  // renewBeforeMinutes: 20,
+  onRenewError: (err) => console.error(err)
+})
+
+// 组件卸载时
+renewal.stop()
+```
 
-### 按需引入（不全局注册）
+注意：前端持有账号密码仅适合内网联调；生产应由后端签发 token。
+
+### 密钥怎么传
+
+推荐页面级 `provide` 一次：
 
 ```js
-import { ArcgisMap, BasemapSwitch, MapToolbar } from '@ywbgn/bgl-package'
+import { provideBasemapKeys } from '@ywbgn/bgl-package'
+
+const basemapKeys = {
+  tiandituKey: '',
+  geovisToken: '',
+  jl1mallMk: '',
+  jl1mallToken: ''
+}
+provideBasemapKeys(basemapKeys)
+```
+
+也可给组件传 `:keys`（优先于 inject）。
+
+导出：`BasemapKeys`、`BASEMAP_KEYS_KEY`、`provideBasemapKeys`、`useBasemapKeys`、`BASEMAP_OPTIONS`、`ToolbarToolId`、`DEFAULT_TOOLBAR_TOOLS`、`LonLatExtent`、`PanConstraintHandle`、`applyPanBoundsConstraint`、`goToFullExtent`。
+
+## 样式定制
+
+在地图、底图、卷帘、工具栏的**共同父节点**上设置 CSS 变量（父节点需 `position: relative`）。
+
+**位置**
+
+| 变量                        | 作用对象               | 默认                 |
+| --------------------------- | ---------------------- | -------------------- |
+| `--bgl-basemap-left`      | 底图入口               | `16px`             |
+| `--bgl-basemap-bottom`    | 底图入口               | `160px`            |
+| `--bgl-basemap-z`         | 底图入口               | `1100`             |
+| `--bgl-swipe-left`        | 底图卷帘入口           | `16px`             |
+| `--bgl-swipe-bottom`      | 底图卷帘入口           | `100px`            |
+| `--bgl-swipe-z`           | 底图卷帘入口           | `1100`             |
+| `--bgl-toolbar-left`      | 工具栏整体（含经纬度） | `50%`              |
+| `--bgl-toolbar-bottom`    | 工具栏整体             | `14px`             |
+| `--bgl-toolbar-transform` | 工具栏整体             | `translateX(-50%)` |
+| `--bgl-toolbar-z`         | 工具栏整体             | `1000`             |
+| `--bgl-legend-width`      | 图例宽度               | `150px`            |
+| `--bgl-legend-height`     | 图例高度               | `240px`            |
+| `--bgl-legend-z`          | 图例层级               | `1050`             |
+| `--bgl-scalebar-z`        | 比例尺层级             | `100`              |
+
+**背景与强调色**
+
+| 变量                 | 默认                      |
+| -------------------- | ------------------------- |
+| `--bgl-trigger-bg` | `rgba(62, 68, 85, 0.9)` |
+| `--bgl-panel-bg`   | `rgba(62, 68, 85, 0.9)` |
+| `--bgl-toolbar-bg` | `rgba(62, 68, 85, 0.9)` |
+| `--bgl-coord-bg`   | `rgba(40, 48, 58, 0.7)` |
+| `--bgl-accent`     | `#01b595`               |
+
+穿透补充（升级时 class 可能变化，优先用变量）：
+
+| class                                                          | 说明         |
+| -------------------------------------------------------------- | ------------ |
+| `.basemap-switch-wrap` / `.basemap-switch-trigger`         | 底图         |
+| `.swipe-compare-wrap` / `.swipe-compare-trigger`           | 底图卷帘     |
+| `.toolbar-wrap` / `.coordinate-display` / `.toolbar-box` | 工具栏       |
+| `.map-tool-panel`                                            | 通用浮层面板 |
+| `.map-legend` / `.map-legend__body`                        | 图例         |
+| `.map-scale-bar` / `.map-scale-bar__body`                  | 比例尺       |
+
+## TypeScript
+
+发布包提供 `dist/index.d.ts`。常用类型：
+
+```ts
+import type {
+  MapReadyPayload,
+  BasemapKeys,
+  BusinessLayerConfig,
+  ToolbarToolId,
+  LonLatExtent,
+  PanConstraintHandle,
+  SpatialReferenceMismatchInfo,
+  CoordinateSystemConfig
+} from '@ywbgn/bgl-package'
 ```
 
 ## 说明
 
-- **MapView、Layer 等 ArcGIS 对象不要用 `ref()` 做深度响应式**，请用 `shallowRef`（或 `markRaw`），否则会出现 `__accessor__` 与 Vue Proxy 冲突。本库子组件内部已对 props 做了 `toRaw` 处理，但业务侧仍建议用 `shallowRef` 保存 `view`。
-- 地图与测量能力依赖 Esri 服务与许可策略，部署与密钥请按官方文档配置。
-- 本包依赖 `@arcgis/core`，使用时需遵守 Esri 官方许可条款。
-- 若使用 UMD 产物，请注意 Rollup 对 `default` + 具名导出同时存在时的用法；推荐 ESM 方式引用。
+- **MapView、Layer 等不要用 `ref()` 做深度响应式**，请用 `shallowRef`（或 `markRaw`）。
+- 本包 peer 依赖 `@arcgis/core@~4.34.8`，使用时需遵守 Esri 许可条款。
+- 推荐 ESM 引用；UMD 场景请自行处理 `default` 与具名导出差异。