@ywbgn/bgl-package 1.1.1 → 1.2.2

package/README.md

@@ -1,6 +1,6 @@
 # @ywbgn/bgl-package
 
-基于 Vue 3 与 `@arcgis/core` 的地图组件库：地图初始化、底图切换、底图卷帘、工具栏（全图、全屏、缩放、定位、测距、测面、图层管理、业务卷帘、地图标注、条件查询），业务图层加载 / Portal Token 注册，以及平移边界约束（`panBounds` / `applyPanBoundsConstraint`）。
+基于 Vue 3 与 `@arcgis/core` 的地图组件库：地图初始化、底图切换、底图卷帘、工具栏（全图、全屏、缩放、上一/下一视图、定位、测距、测面、图层管理、业务卷帘、地图标注、条件查询、TXT 画图）、**空间分析面板**（`SpatialAnalysisPanel`）、通用表格（`BglDataTable`），业务图层加载 / Portal Token 注册与续期，以及平移边界约束（`panBounds` / `applyPanBoundsConstraint`）。
 
 ## 安装依赖
 
@@ -27,18 +27,32 @@ app.use(VueArcgisMap)
 app.mount('#app')
 ```
 
+组件库自身样式：ESM 入口构建时已注入 CSS；按需 / UMD 或样式丢失时再显式引入：
+
+```js
+import '@ywbgn/bgl-package/style.css'
+```
+
 按需引入（不全局注册）：
 
 ```js
 import {
   ArcgisMap,
   BasemapSwitch,
+  LayerSwitch,
   SwipeCompare,
   MapToolbar,
+  SpatialAnalysisPanel,
+  BglInput,
+  BglSelect,
+  BglDataTable,
   provideBasemapKeys,
   loadBusinessLayers,
+  setPendingBusinessLayers,
   registerPortalToken,
+  registerPortalAccessToken,
   startPortalTokenRenewal,
+  startPortalTokenRenewalWithFetcher,
   applyPanBoundsConstraint,
   goToFullExtent
 } from '@ywbgn/bgl-package'
@@ -48,7 +62,10 @@ import type {
   MapReadyPayload,
   ToolbarToolId,
   LonLatExtent,
-  PanConstraintHandle
+  PanConstraintHandle,
+  MapBounds,
+  BglDataTableColumn,
+  BglDataTableRow
 } from '@ywbgn/bgl-package'
 ```
 
@@ -56,9 +73,9 @@ import type {
 
 1. 先拿到底图密钥 / 系统参数（含 `minZoom` / `maxZoom` / 经纬度范围），再挂 `ArcgisMap`（密钥只在挂载时读一次，可用 `v-if` 等配置就绪后再渲染）。
 2. `@ready` 里用 `shallowRef` 保存 `view` / `sketchLayer` / `map`。
-3. 需要时再挂 `BasemapSwitch`、`SwipeCompare`、`MapLegend`、`MapScaleBar`、`MapToolbar`。
+3. 需要时再挂 `LayerSwitch`、`BasemapSwitch`、`SwipeCompare`、`MapLegend`、`MapScaleBar`、`MapToolbar`；空间分析挂 `SpatialAnalysisPanel`（不在工具栏内）。
 4. 有经纬度范围时：给 `ArcgisMap` 传 `:pan-bounds`（自动限制拖动），给 `MapToolbar` 传 `:home-extent`（全图回到范围中心 + minZoom）。
-5. 在 `ready` 后 `startPortalTokenRenewal`（或 `registerPortalToken`）→ `loadBusinessLayers`；卸载时对续期调用 `stop()`。
+5. 在 `ready` 后登记 Portal Token（生产用 `startPortalTokenRenewalWithFetcher`，内网联调可用 `startPortalTokenRenewal`）→ `loadBusinessLayers`；默认隐藏层用 `setPendingBusinessLayers`；卸载时对续期调用 `stop()`。
 6. 切底图前同时拆除**底图卷帘**与**工具栏业务卷帘**。
 
 ```vue
@@ -76,6 +93,7 @@ import type {
       @ready="onReady"
     />
     <template v-if="view && sketchLayer">
+      <LayerSwitch :view="view" />
       <BasemapSwitch :view="view" @before-change="onBeforeBasemapChange" />
       <SwipeCompare ref="swipeCompareRef" :view="view" />
       <MapLegend :view="view" position="left" :offset-x="12" :offset-y="14" />
@@ -97,6 +115,7 @@ import type GraphicsLayer from '@arcgis/core/layers/GraphicsLayer.js'
 import {
   ArcgisMap,
   BasemapSwitch,
+  LayerSwitch,
   MapLegend,
   MapScaleBar,
   MapToolbar,
@@ -165,6 +184,168 @@ const onBeforeBasemapChange = () => {
 
 ## 组件说明
 
+### 通用输入组件
+
+组件库提供统一深色主题样式的 `BglInput`、`BglSelect` 和 `BglDataTable`，支持全局注册或按需引入。使用组件前请引入组件库样式：
+
+```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, BglDataTable } 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"
+/>
+```
+
+#### BglDataTable
+
+通用数据表格：固定表头 + 可滚动表体 + 可选底部固定区。表头与表体分表渲染，纵向滚动时表头不跟着动；列宽按内容测量后对齐。空间分析面板结果表即使用此组件，业务侧也可单独用于统计排行等场景。
+
+父容器需要有明确高度（或处于 flex 列布局且 `min-height: 0`），表体才能内部滚动。
+
+```vue
+<BglDataTable
+  v-model:active-index="activeIndex"
+  :columns="columns"
+  :rows="rows"
+  align="center"
+>
+  <template #footer>
+    <span>共 {{ rows.length }} 条</span>
+  </template>
+</BglDataTable>
+```
+
+```ts
+import { ref } from 'vue'
+import type { BglDataTableColumn, BglDataTableRow } from '@ywbgn/bgl-package'
+
+const activeIndex = ref(-1)
+const columns: BglDataTableColumn[] = [
+  { title: '序号', key: 'index', width: '56px', render: (_row, index) => index + 1 },
+  { title: '名称', key: 'name' },
+  { title: '面积(亩)', key: 'area', render: (row) => Number(row.area || 0).toFixed(2) }
+]
+const rows = ref<BglDataTableRow[]>([
+  { name: '示例牧户', area: 12.5 }
+])
+```
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `columns` | `BglDataTableColumn[]` | `[]` | 列定义 |
+| `rows` | `BglDataTableRow[]` | `[]` | 行数据 |
+| `align` | `'left' \| 'center'` | `'left'` | 表头与单元格对齐 |
+| `activeIndex` | `number` | `-1` | 当前高亮行下标，`-1` 表示无；支持 `v-model:active-index` |
+
+`BglDataTableColumn`：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `title` | `string` | 表头文案 |
+| `key` | `string` | 列标识；默认从行对象取 `row[key]`，也作为单元格插槽名 |
+| `width` | `string` | 可选列宽，如 `'48px'`；未测量前作为最小宽度 |
+| `render` | `(row, index) => string \| number` | 可选单元格渲染；传入后优先于 `row[key]` |
+
+组件事件与插槽：
+
+- `update:activeIndex(index)`：点击行时触发，可通过 `v-model:active-index` 接收。
+- `#footer`：底部固定区；不传则不渲染。
+- `#cell-<key>`：按列覆盖单元格内容，作用域为 `{ row, index, column, value }`。
+
+暴露方法：`scrollToTop()`，将表体滚回左上角（切换 Tab 等场景使用）。
+
 ### ArcgisMap
 
 | Prop / 能力               | 说明                                                                                               |
@@ -180,10 +361,31 @@ const onBeforeBasemapChange = () => {
 - `panBounds` 在 view ready 后自动调用 `applyPanBoundsConstraint` + `wrapViewGoTo`；组件卸载时自动清理
 - 有 `panBounds` 时，初始会定位到范围中心 + `minZoom`（与「全图」一致）
 
+### LayerSwitch（图层显隐，独立入口）
+
+停靠在底图按钮**正上方**，与底图/卷帘同款 50×50 入口。点击弹出业务图层列表，用眼睛切换显隐。再点按钮或点击外部关闭。
+
+与工具栏「图层管理」独立：本组件只做显隐，不含排序 / 透明度 / 定位。
+
+```vue
+<LayerSwitch :view="view" appearance="frame" />
+```
+
+| Prop           | 说明                                                             |
+| -------------- | ---------------------------------------------------------------- |
+| `view`       | 必填                                                             |
+| `idPrefix`   | 业务层前缀，默认`bgl-biz-`（需与 `loadBusinessLayers` 一致） |
+| `appearance` | `'plain'` \| `'frame'`，默认 `frame`。`plain` 为纯色圆角面板；`frame` 用切图九宫格铺背景 |
+
+待创建隐藏层会出现在列表中，点眼睛显示后才真正上图（与图层管理勾选行为一致）。
+
+默认 `left: 16px`、`bottom: 390px`（底图默认 330px 之上留 50+10 空隙），可用 `--bgl-layer-left` / `--bgl-layer-bottom` / `--bgl-layer-z` 覆盖。
+
 ### BasemapSwitch（底图切换）
 
 - 必填 `view`
 - 可选 `keys`
+- 可选 `appearance`：`'plain'` \| `'frame'`，默认 `frame`（切图背景；工具栏弹框仍为 plain）
 - 事件 `before-change`：成功切换底图**前**触发（用于拆卷帘）
 
 可选底图：天地图影像 / 矢量、星图地球、吉林一号、ArcGIS 影像。缺 Key 时可选中，切换时会提示。
@@ -191,11 +393,12 @@ const onBeforeBasemapChange = () => {
 ### SwipeCompare（底图卷帘）
 
 - 左下角入口，对比**底图影像**
+- 可选 `appearance`：`'plain'` \| `'frame'`，默认 `frame`（与底图弹框一致）
 - 方法 `destroySwipe()`：拆除 Swipe 并移除左侧对比层
 
 ### MapToolbar（工具栏）
 
-内置工具：全图、全屏、放大、缩小、坐标定位、距离测量、面积测量、图层管理、业务图层卷帘、地图标注、条件查询。
+内置工具：全图、全屏、放大、缩小、上一视图、下一视图、坐标定位、距离测量、面积测量、图层管理、业务图层卷帘、地图标注、条件查询、TXT 画图。
 
 | Prop / 能力                | 说明                                                                     |
 | -------------------------- | ------------------------------------------------------------------------ |
@@ -214,7 +417,7 @@ const onBeforeBasemapChange = () => {
 
 工具 id（`ToolbarToolId`）：
 
-`fullExtent` | `fullscreen` | `zoomIn` | `zoomOut` | `coordinateLocate` | `distanceMeasure` | `areaMeasure` | `layerManage` | `layerSwipe` | `mapLabel` | `conditionQuery`
+`fullExtent` | `fullscreen` | `zoomIn` | `zoomOut` | `prevExtent` | `nextExtent` | `coordinateLocate` | `distanceMeasure` | `areaMeasure` | `layerManage` | `layerSwipe` | `mapLabel` | `conditionQuery` | `txtDraw`
 
 ```vue
 <MapToolbar
@@ -248,22 +451,25 @@ const coordinateSystemConfig = {
 
 | 工具 | 行为                                                                                              |
 | ---- | ------------------------------------------------------------------------------------------------- |
-| 全图 | 有`homeExtent` 时：`goToFullExtent`（范围中心 + minZoom）；否则用 `homeCenter` / 仅 minZoom |
-| 全屏 | 对`document.documentElement` 请求整页全屏（接近 F11），再次点击或 Esc 退出                      |
+| 全图     | 有`homeExtent` 时：`goToFullExtent`（范围中心 + minZoom）；否则用 `homeCenter` / 仅 minZoom |
+| 全屏     | 对`document.documentElement` 请求整页全屏（接近 F11），再次点击或 Esc 退出                      |
+| 上一视图 | 回退到上一次静止视野（平移 / 缩放后入栈，最多 30 条）；无历史时按钮禁用                         |
+| 下一视图 | 前进到回退前的视野；无可前进记录时按钮禁用                                                     |
 
 #### 内置面板说明
 
 | 工具     | 作用                                     | 注意                                                 |
 | -------- | ---------------------------------------- | ---------------------------------------------------- |
-| 图层管理 | 业务层显隐、透明度、排序、定位           | 仅识别`layerIdPrefix` 前缀图层；若加载时做过坐标系校验，不一致图层会标记「坐标系不一致」 |
+| 图层管理 | 业务层显隐、透明度、排序、定位           | 仅识别`layerIdPrefix` 前缀图层；待创建隐藏层会出现在列表中，勾选后才真正上图；若加载时做过坐标系校验，不一致图层会标记「坐标系不一致」 |
 | 卷帘对比 | 选左右**业务层**做 Swipe           | 与底图卷帘互斥（应用时自动拆另一侧）                 |
 | 坐标定位 | 按所选坐标系输入或拾取坐标后定位         | `coordinateSystemConfig` 可由业务系统动态下发默认坐标系与可选项 |
 | 地图标注 | 按字段设置`labelingInfo`               | 仅**FeatureLayer**；MapImageLayer 不出现在列表 |
 | 条件查询 | 拼 WHERE →`queryFeatures` → 定位高亮 | 仅 FeatureLayer；字段值去重最多约 1000 条            |
+| TXT 画图 | 上传经纬度 txt，在地图上绘面并计算亩数 | 仅 `.txt`，≤ 10MB；自动识别「经度,纬度」或「纬度,经度」；打开面板期间会暂停 `panBounds`，关闭约 3 秒后恢复 |
 
 ### MapLegend（图例，独立常开）
 
-与底图切换、卷帘一样单独挂载，**不在工具栏内**；默认常开，基于 ArcGIS `Legend` 微件。
+与底图切换、卷帘一样单独挂载，**不在工具栏内**；默认常开，基于 ArcGIS `LegendViewModel` 渲染。
 
 - 只展示业务图层（`idPrefix` 前缀，默认 `bgl-biz-`）
 - 排除 `listMode === 'hide'` 的图层（如绘制层）
@@ -275,19 +481,33 @@ const coordinateSystemConfig = {
   position="left"
   :offset-x="12"
   :offset-y="14"
+  appearance="plain"
 />
 ```
 
-| Prop         | 说明                                                             |
-| ------------ | ---------------------------------------------------------------- |
-| `view`     | 必填                                                             |
-| `idPrefix` | 业务层前缀，默认`bgl-biz-`（需与 `loadBusinessLayers` 一致） |
-| `position` | `'left'` \| `'right'`，默认 `left`（右侧有业务抽屉时用左） |
-| `offsetX`  | 水平边距（px），默认`12`                                       |
-| `offsetY`  | 相对地图底边抬高（px），默认`14`                               |
+切图背景模式：
+
+```vue
+<MapLegend
+  :view="view"
+  position="left"
+  :offset-x="12"
+  :offset-y="14"
+  appearance="frame"
+/>
+```
+
+| Prop           | 说明                                                             |
+| -------------- | ---------------------------------------------------------------- |
+| `view`       | 必填                                                             |
+| `idPrefix`   | 业务层前缀，默认`bgl-biz-`（需与 `loadBusinessLayers` 一致） |
+| `position`   | `'left'` \| `'right'`，默认 `left`（右侧有业务抽屉时用左） |
+| `offsetX`    | 水平边距（px），默认`12`                                       |
+| `offsetY`    | 相对地图底边抬高（px），默认`14`                               |
+| `appearance` | `'plain'` \| `'frame'`，默认 `plain`。`plain` 为纯色圆角面板；`frame` 用切图九宫格铺背景 |
 
 默认尺寸 **150×240px**（可用 CSS 变量 `--bgl-legend-width` / `--bgl-legend-height` 覆盖）。
-层级默认约 `1050`，可用 `--bgl-legend-z` 覆盖。
+层级默认 `100`（与底图切换、工具栏、比例尺一致），可用 `--bgl-legend-z` 覆盖。
 
 与比例尺同侧时，建议比例尺加大 `offsetX`（例如图例 `12`、比例尺 `170`），避免重叠。
 
@@ -342,6 +562,89 @@ const coordinateSystemConfig = {
 - 容器 `pointer-events: none`，不挡地图拖拽
 - 层级默认 `100`（与底图切换、图例、工具栏一致），可用 `--bgl-scalebar-z` 覆盖
 
+### SpatialAnalysisPanel（空间分析）
+
+独立面板，**不在工具栏内**。用于上传图斑、与九类业务图层叠加比对、统计压占面积，并导出 Word / TXT。可用工具栏 `#extra` 按钮控制显隐。
+
+叠加勾选项与图层 `title`（`BusinessLayerConfig.mapServiceName`）必须一致：
+
+| 面板勾选 | 图层 title |
+| -------- | ---------- |
+| 确权     | 草场确权   |
+| 草地     | 草地分布   |
+| 林地     | 林地分布   |
+| 湿地     | 湿地分布   |
+| 耕地     | 耕地分布   |
+| 保护区   | 保护区     |
+| 林保图   | 林保图     |
+| 生态红线 | 生态红线   |
+| 基本草原 | 基本草原   |
+
+默认勾选「确权」。勾选时按 title 显示图层；若该层尚未上图（已用 `setPendingBusinessLayers` 登记），会现场物化后再显示。找不到图层时控制台警告，不中断。
+
+```vue
+<SpatialAnalysisPanel
+  v-if="showAnalysis && map && view"
+  :map="map"
+  :view="view"
+  :system-coordinate-wkid="systemCoordinateWkid"
+  :map-bounds="mapBounds"
+/>
+```
+
+```ts
+import type Map from '@arcgis/core/Map.js'
+import type { MapBounds, MapReadyPayload } from '@ywbgn/bgl-package'
+
+const showAnalysis = ref(false)
+const map = shallowRef<Map | null>(null)
+const systemCoordinateWkid = ref<number | null>(null)
+const mapBounds = ref<MapBounds | null>(null)
+
+const onReady = async (payload: MapReadyPayload) => {
+  map.value = payload.map
+  view.value = payload.view
+  // mapBounds.value = { jwXMin, jwXMax, jwYMin, jwYMax }
+}
+```
+
+| Prop | 说明 |
+| ---- | ---- |
+| `map` / `view` | 必填；用 `shallowRef`，不要 `ref()` |
+| `systemCoordinateWkid` | 系统参数坐标系；`8848` 按 CGCS2000_Albers，其他按 WKID |
+| `mapBounds` | `{ jwXMin, jwXMax, jwYMin, jwYMax }`，分析范围约束；不传则全球范围 |
+
+操作流程：
+
+1. 勾选叠加类型（默认确权）。
+2. 「选择文件」→ 填数据类型（面 / 线 / 点）；线、点需填缓冲距离（米）。
+3. 上传 `.txt`（CGCS2000 经纬度 / `GCS_China_Geodetic_Coordinate_System_2000`，每行「经度,纬度」）或带 `.shp` / `.prj` / `.dbf` 的 `.zip`。TXT ≤ 10MB，ZIP ≤ 500MB。
+4. 上图后可编辑折点。
+5. 「分析」：与勾选图层求交，输出压占面积、牧户及分类明细。
+6. 「导出」Word（含地图截图）或 TXT 坐标。
+7. 「重置」清空图斑、结果与勾选（回到默认确权）。关闭面板会释放 Sketch 与分析图层。
+
+#### 结果区
+
+分析完成后，结果区按叠加类型分 Tab（左右箭头可滚动）。分析前展示全部 Tab；分析后只保留当前勾选类型。表格使用 `BglDataTable`（居中对齐），点击行高亮；切换 Tab 时滚动回到顶部。
+
+底部固定汇总：
+
+| 指标 | 说明 |
+| ---- | ---- |
+| 分析面积(亩) | 图斑面积；确权压占面积更大时取确权合计 |
+| 牧户/集体(个) | 当前 Tab 行数 |
+| 确权面积(亩) / 资源面积(亩) | 确权 Tab 汇总 `occupiedArea`；其余 Tab 汇总「小计」 |
+
+各 Tab 列概要（数字列保留两位小数）：
+
+| Tab | 列 |
+| --- | --- |
+| 确权 | 序号、牧户名称、覆盖面积(亩)、苏木镇、嘎查村 |
+| 草地 / 林地 / 湿地 / 耕地 / 基本草原 / 生态红线 | 序号、牧户名称、苏木镇、嘎查村、小计、各分类面积 |
+| 保护区 | 上列基础字段 + 保护区名称、核心区、缓冲区 |
+| 林保图 | 上列基础字段 + 乔木林地、灌木林地、宜林荒山荒地、其他 |
+
 ## 平移边界约束
 
 基于 ArcGIS `view.constraints.geometry`（只约束**视图中心点**）：按当前可视范围反推中心点合法活动区域，效果上等价于「经纬度矩形始终不拖出屏幕」。所有缩放级别均生效；拖到边缘直接停住，不做回弹。
@@ -351,7 +654,9 @@ const coordinateSystemConfig = {
 ```ts
 import {
   applyPanBoundsConstraint,
-  goToFullExtent
+  goToFullExtent,
+  suspendPanBounds,
+  resumePanBounds
 } from '@ywbgn/bgl-package'
 import type { LonLatExtent, PanConstraintHandle } from '@ywbgn/bgl-package'
 
@@ -378,6 +683,8 @@ handle.remove()
 | `applyPanBoundsConstraint(view, extent)` | 挂平移约束并初始定位到全图；返回`PanConstraintHandle`     |
 | `handle.wrapViewGoTo(view)`              | 包装`view.goTo`，定位期间临时放开约束                     |
 | `handle.remove()`                        | 释放 watch，恢复原始`goTo`，清空 `constraints.geometry` |
+| `handle.suspend()` / `handle.resume()` | 长期暂停 / 恢复约束（如 TXT 画图打开面板） |
+| `suspendPanBounds(view)` / `resumePanBounds(view)` | 按 view 查找已登记句柄后暂停 / 恢复 |
 | `goToFullExtent(view, extent)`           | 定位到范围中心 +`constraints.minZoom`                     |
 
 ## 两套卷帘（务必区分）
@@ -402,6 +709,7 @@ const layers = loadBusinessLayers({
     layers: configs,
     reverse: true,
     idPrefix: BUSINESS_LAYER_ID_PREFIX,
+    // accessToken, // 已登记 Portal token 时建议传入，保证首轮元数据请求带 token
     // labelConfigs: [...]  // 见下文「业务图层注记」
     // expectedSpatialReferenceWkid: 8848, // 系统参数；8848=CGCS2000_Albers，其他为 WKID
   })
@@ -428,6 +736,37 @@ const layers = loadBusinessLayers({
 - 不一致记录会登记到组件内，图层管理面板会显示「坐标系不一致」标记，并在顶部汇总数量
 - 注意：`systemCoordinate` 表示业务图层期望坐标系；坐标定位面板默认输入坐标系仍优先使用 `latitudeLongitude`（经纬度）
 
+### 默认隐藏层（延迟上图）
+
+`layerVisible` 为假的图层不要立刻 `loadBusinessLayers`，用 `setPendingBusinessLayers` 登记。图层管理勾选显示、或空间分析勾选对应叠加类型时，才会真正请求服务并 `reorderBusinessLayers`。
+
+```ts
+import {
+  loadBusinessLayers,
+  setPendingBusinessLayers,
+  clearPendingBusinessLayers,
+  resolveLayerVisible
+} from '@ywbgn/bgl-package'
+
+const visible = configs.filter((item) => resolveLayerVisible(item.layerVisible))
+const pending = configs.filter((item) => !resolveLayerVisible(item.layerVisible))
+
+loadBusinessLayers({
+  map,
+  layers: visible,
+  reverse: true,
+  accessToken
+})
+setPendingBusinessLayers(pending, {
+  allConfigs: configs,
+  accessToken,
+  reverse: true
+})
+
+// 页面卸载或重新上图前
+clearPendingBusinessLayers()
+```
+
 ### 业务图层注记（地图上显示属性字段）
 
 对齐 forestpests：前端配置指定图层的 `labelingInfo`（Arcade + 描边样式），**不依赖**后端 mapServiceSettings。
@@ -471,7 +810,41 @@ loadBusinessLayers({
 
 注意：仅 **FeatureLayer** 生效；与工具栏「地图标注」可并存（手动标注会覆盖该层 `labelingInfo`）。
 
-### registerPortalToken / startPortalTokenRenewal
+### Portal Token
+
+生产不要在前端持有 Portal 账号密码。由后端签发短期 token，前端只登记 / 续期。
+
+**生产推荐：后端代签 + 自动续期**
+
+```ts
+const renewal = await startPortalTokenRenewalWithFetcher({
+  portalUrl: 'https://example.com',
+  extraServers: ['https://gis.example.com/server'],
+  fetchToken: async () => {
+    const res = await fetch('/api/portal-token')
+    const data = await res.json()
+    // token 必填；expires 为毫秒时间戳，有则按此调度续期
+    return { token: data.token, expires: data.expires }
+  },
+  // expirationMinutes: 60, // fetch 未返回 expires 时的兜底有效期
+  onRenewError: (err) => console.error(err)
+})
+
+// 组件卸载时
+renewal.stop()
+```
+
+已有 token、无需续期时：
+
+```ts
+registerPortalAccessToken({
+  portalUrl: 'https://example.com',
+  token: accessToken,
+  extraServers: ['https://gis.example.com/server']
+})
+```
+
+**内网联调：前端 generateToken（勿用于生产）**
 
 单次注册：
 
@@ -505,11 +878,10 @@ const renewal = await startPortalTokenRenewal({
   onRenewError: (err) => console.error(err)
 })
 
-// 组件卸载时
 renewal.stop()
 ```
 
-注意：前端持有账号密码仅适合内网联调；生产应由后端签发 token。
+续期失败时库内会节流通知（首次立即，之后同一失败串最多约每 15 分钟一次），并每 5 分钟重试。`onRenewError` 仍建议业务侧做提示。
 
 ### 密钥怎么传
 
@@ -529,7 +901,7 @@ provideBasemapKeys(basemapKeys)
 
 也可给组件传 `:keys`（优先于 inject）。
 
-导出：`BasemapKeys`、`BASEMAP_KEYS_KEY`、`provideBasemapKeys`、`useBasemapKeys`、`BASEMAP_OPTIONS`、`ToolbarToolId`、`DEFAULT_TOOLBAR_TOOLS`、`LonLatExtent`、`PanConstraintHandle`、`applyPanBoundsConstraint`、`goToFullExtent`。
+导出：`BasemapKeys`、`BASEMAP_KEYS_KEY`、`provideBasemapKeys`、`useBasemapKeys`、`BASEMAP_OPTIONS`、`ToolbarToolId`、`DEFAULT_TOOLBAR_TOOLS`、`LonLatExtent`、`PanConstraintHandle`、`applyPanBoundsConstraint`、`goToFullExtent`、`suspendPanBounds`、`resumePanBounds`、`registerPortalAccessToken`、`startPortalTokenRenewalWithFetcher`、`setPendingBusinessLayers`、`MapBounds`、`BglDataTable`、`BglDataTableColumn`、`BglDataTableRow`。
 
 ## 样式定制
 
@@ -539,19 +911,22 @@ provideBasemapKeys(basemapKeys)
 
 | 变量                        | 作用对象               | 默认                 |
 | --------------------------- | ---------------------- | -------------------- |
+| `--bgl-layer-left`        | 图层入口               | `16px`             |
+| `--bgl-layer-bottom`      | 图层入口               | `390px`            |
+| `--bgl-layer-z`           | 图层入口               | `100`              |
 | `--bgl-basemap-left`      | 底图入口               | `16px`             |
 | `--bgl-basemap-bottom`    | 底图入口               | `160px`            |
-| `--bgl-basemap-z`         | 底图入口               | `1100`             |
+| `--bgl-basemap-z`         | 底图入口               | `100`              |
 | `--bgl-swipe-left`        | 底图卷帘入口           | `16px`             |
 | `--bgl-swipe-bottom`      | 底图卷帘入口           | `100px`            |
-| `--bgl-swipe-z`           | 底图卷帘入口           | `1100`             |
+| `--bgl-swipe-z`           | 底图卷帘入口           | `100`              |
 | `--bgl-toolbar-left`      | 工具栏整体（含经纬度） | `50%`              |
 | `--bgl-toolbar-bottom`    | 工具栏整体             | `14px`             |
 | `--bgl-toolbar-transform` | 工具栏整体             | `translateX(-50%)` |
-| `--bgl-toolbar-z`         | 工具栏整体             | `1000`             |
+| `--bgl-toolbar-z`         | 工具栏整体             | `100`              |
 | `--bgl-legend-width`      | 图例宽度               | `150px`            |
 | `--bgl-legend-height`     | 图例高度               | `240px`            |
-| `--bgl-legend-z`          | 图例层级               | `1050`             |
+| `--bgl-legend-z`          | 图例层级               | `100`              |
 | `--bgl-scalebar-z`        | 比例尺层级             | `100`              |
 
 **背景与强调色**
@@ -568,12 +943,15 @@ provideBasemapKeys(basemapKeys)
 
 | class                                                          | 说明         |
 | -------------------------------------------------------------- | ------------ |
+| `.layer-switch-wrap` / `.layer-switch-trigger` / `.layer-switch-panel` | 图层显隐     |
 | `.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-legend` / `.map-legend--plain` / `.map-legend--frame` / `.map-legend__body` | 图例         |
 | `.map-scale-bar` / `.map-scale-bar__body`                  | 比例尺       |
+| `.spatial-analysis-panel`                                  | 空间分析面板 |
+| `.bgl-data-table` / `.bgl-data-table__head` / `.bgl-data-table__wrap` / `.bgl-data-table__footer` | 通用数据表格 |
 
 ## TypeScript
 
@@ -588,7 +966,11 @@ import type {
   LonLatExtent,
   PanConstraintHandle,
   SpatialReferenceMismatchInfo,
-  CoordinateSystemConfig
+  CoordinateSystemConfig,
+  MapBounds,
+  PortalTokenRenewalHandle,
+  BglDataTableColumn,
+  BglDataTableRow
 } from '@ywbgn/bgl-package'
 ```