@3clear/basegis 0.1.0

package/README.md

@@ -0,0 +1,972 @@
+# @3clear/basegis
+
+`@3clear/basegis` 是 3clear 一张图项目抽出的 GIS 能力包。它提供一个统一入口 `BaseGIS`，把 Cesium / Leaflet 的差异收敛到适配层里；业务页面优先只操作 `BaseGIS`，复杂图层能力通过 `methods` 控制器组合 `BaseGIS` 公共方法完成。
+
+当前包包含：
+
+- `BaseGIS`：地图初始化、引擎切换、视角控制、底图切换、绘制、图层显隐、DEM、点击事件等基础能力。
+- `methods`：图片图层、网格图层、海量点、点位抽稀、等值线、等压线、风场、图形组等高级控制器。
+- `layers`：天地图、GeoServer 金字塔瓦片、WMS、WMTS 图层配置快捷构造器。
+- `assets`：GIS 示例资源。
+- `style.css`：Leaflet、GIS 图层和标注相关基础样式。
+
+## 安装
+
+```bash
+npm install @3clear/basegis leaflet axios pixi.js leaflet-pixi-overlay
+```
+
+使用样式：
+
+```js
+import '@3clear/basegis/style.css'
+```
+
+Cesium 当前不随 npm 包发布，宿主项目需要按原项目方式把 Cesium 静态资源放到 `public/lib/Cesium`，并保证初始化前能访问 `window.Cesium`。默认配置会从 `${BASE_URL}lib/Cesium/Cesium.js` 和 `${BASE_URL}lib/Cesium/Widgets/widgets.css` 加载。
+
+如果需要加载 GeoTIFF 网格，需要宿主项目提前提供 `window.GeoTIFF`。
+
+## 出口
+
+```js
+// 主入口
+import { BaseGIS } from '@3clear/basegis'
+
+// 高级能力控制器
+import {
+  GraphicGroupController,
+  ImageLayerController,
+  GridLayerController,
+  PointLargeLayerController,
+  PointDensityController,
+  ContourLayerController,
+  PressureContourLayer,
+  createPressureDataResolver,
+  buildPressureRenderData,
+  WindFieldMethods,
+} from '@3clear/basegis/methods'
+
+// 图层配置构造器
+import {
+  createTiandituLayer,
+  createGeoserverPyramidLayer,
+  createWmsLayer,
+  createWmtsLayer,
+} from '@3clear/basegis/layers'
+
+// 示例资源
+import { gisMarkerSample } from '@3clear/basegis/assets'
+```
+
+## 快速开始
+
+```vue
+<template>
+  <div id="map" class="map"></div>
+</template>
+
+<script setup>
+import { onBeforeUnmount, onMounted } from 'vue'
+import { BaseGIS } from '@3clear/basegis'
+import '@3clear/basegis/style.css'
+
+let mapCore = null
+
+onMounted(() => {
+  mapCore = new BaseGIS({
+    // 可选 cesium / leaflet。不传时使用默认配置 active: 'cesium'。
+    engineType: 'cesium',
+    // 也可以传 container: HTMLElement。
+    containerId: 'map',
+    config: {
+      view: {
+        // 可选 2d / 2.5d / 3d。
+        defaultSceneMode: '3d',
+        initialView: {
+          center: [104, 35],
+          // Cesium 使用 height，Leaflet 使用 zoom。
+          height: 5000000,
+          zoom: 5,
+          // Cesium 默认保持垂直俯视。
+          pitch: -90,
+        },
+      },
+    },
+  })
+
+  const result = mapCore.init()
+  if (!result.success) {
+    console.warn(result.message)
+  }
+})
+
+onBeforeUnmount(() => {
+  mapCore?.destroy()
+})
+</script>
+
+<style scoped>
+.map {
+  width: 100%;
+  height: 100%;
+}
+</style>
+```
+
+## 返回值约定
+
+多数方法返回统一结果对象：
+
+```js
+{
+  success: true,
+  message: 'operation message',
+  data: {}
+}
+```
+
+失败时：
+
+```js
+{
+  success: false,
+  message: 'error message',
+  code: 'NOT_INITIALIZED'
+}
+```
+
+Leaflet 不支持 3D、DEM 等能力时，会返回失败结果或控制台提示，不应直接打断页面。
+
+## BaseGIS 配置
+
+```js
+const mapCore = new BaseGIS({
+  engineType: 'cesium',
+  containerId: 'map',
+  config: {
+    engine: {
+      active: 'cesium',
+      cesium: {
+        // 本地 Cesium 静态资源地址。
+        scriptUrl: '/lib/Cesium/Cesium.js',
+        cssUrl: '/lib/Cesium/Widgets/widgets.css',
+      },
+      leaflet: {
+        sourceType: 'npm',
+      },
+    },
+    view: {
+      defaultSceneMode: '3d',
+      initialView: {
+        center: [121.4737, 31.2304],
+        height: 1800000,
+        zoom: 7,
+        heading: 0,
+        pitch: -90,
+        roll: 0,
+      },
+    },
+    basemap: {
+      defaultVisibleId: 'tianditu-imagery',
+      defaultAnnotationId: 'tianditu-vector-label',
+      list: [],
+    },
+    dem: {
+      defaultEnabled: true,
+      defaultVisibleId: 'ellipsoid-flat',
+      list: [],
+    },
+  },
+})
+```
+
+说明：
+
+- `containerId` 和 `container` 二选一即可；`init()` 时也可以再次传入。
+- 页面传入的 `config` 会覆盖内置默认配置。
+- Cesium 默认视角 `pitch: -90`，表示垂直俯视。
+- `BaseGIS` 只保存运行时配置，调用 `setConfig()` 不会自动重建地图，需要重新 `init()` 才会创建新地图实例。
+
+## BaseGIS 基础能力
+
+### 生命周期与实例
+
+```js
+mapCore.init({ containerId: 'map', engineType: 'leaflet' })
+mapCore.destroy()
+
+mapCore.setEngine('cesium')
+mapCore.setConfig({ view: { defaultSceneMode: '2d' } })
+
+mapCore.getEngineType()
+mapCore.getConfig()
+mapCore.getMapInstance()
+```
+
+### 视角与场景
+
+```js
+mapCore.zoomIn()
+mapCore.zoomOut()
+mapCore.resetView()
+
+mapCore.setSceneMode('2d')
+mapCore.setSceneMode('2.5d')
+mapCore.setSceneMode('3d')
+mapCore.getSceneMode()
+
+mapCore.setInitialView({
+  center: [104, 35],
+  height: 3000000,
+  zoom: 5,
+  pitch: -90,
+})
+```
+
+### 底图与普通图层
+
+```js
+mapCore.setBasemapById('tianditu-imagery')
+
+mapCore.setBasemap({
+  id: 'custom-wmts',
+  name: '自定义 WMTS',
+  type: 'wmts',
+  provider: 'custom',
+  url: 'https://example.com/wmts?...',
+})
+
+mapCore.addLayer(layerConfig)
+mapCore.showLayer({ layerId: 'custom-wmts' })
+mapCore.hideLayer({ layerId: 'custom-wmts' })
+mapCore.removeLayer({ layerId: 'custom-wmts' })
+```
+
+### 点线面文字
+
+```js
+mapCore.drawPoint({
+  id: 'point-1',
+  longitude: 104,
+  latitude: 35,
+  style: {
+    color: '#ff4d4f',
+    pixelSize: 10,
+  },
+})
+
+mapCore.drawLine({
+  id: 'line-1',
+  positions: [
+    [103, 34],
+    [105, 36],
+  ],
+  style: {
+    color: '#1677ff',
+    width: 3,
+  },
+})
+
+mapCore.drawPolygon({
+  id: 'polygon-1',
+  positions: [
+    [102, 33],
+    [106, 33],
+    [106, 36],
+    [102, 36],
+  ],
+  style: {
+    color: 'rgba(22, 119, 255, 0.25)',
+    outlineColor: '#1677ff',
+  },
+})
+
+mapCore.drawText({
+  id: 'text-1',
+  longitude: 104,
+  latitude: 35,
+  text: '示例文字',
+  style: {
+    color: '#ffffff',
+    font: '14px sans-serif',
+  },
+})
+
+mapCore.addMarker({
+  id: 'marker-1',
+  longitude: 104,
+  latitude: 35,
+  image: '/marker.png',
+  width: 32,
+  height: 32,
+})
+
+mapCore.removeGraphic({ id: 'marker-1' })
+mapCore.clearGraphics()
+```
+
+### 点击事件与投影
+
+```js
+const clickResult = mapCore.onClick({
+  id: 'station-click',
+  callback(event) {
+    // event 中通常包含 longitude / latitude / pickedObject 等信息，具体字段与引擎有关。
+    console.log(event)
+  },
+})
+
+mapCore.offClick({ id: 'station-click' })
+
+const point = mapCore.projectToContainerPoint({
+  longitude: 104,
+  latitude: 35,
+  height: 0,
+})
+
+const bounds = mapCore.getViewBounds()
+const viewListener = mapCore.onViewChange({
+  onStart() {},
+  onEnd() {},
+})
+viewListener.data?.off?.()
+```
+
+### DEM
+
+```js
+mapCore.loadDefaultDEM()
+mapCore.loadDEMById('ellipsoid-flat')
+mapCore.loadDEM({
+  id: 'custom-dem',
+  sourceType: 'url',
+  url: 'https://example.com/terrain',
+  options: {},
+})
+```
+
+DEM 当前主要面向 Cesium；Leaflet 调用会返回不支持结果。
+
+## 图层构造器
+
+构造器只返回标准配置对象，通常传给 `config.basemap.list` 或 `mapCore.addLayer()`。
+
+```js
+import {
+  createTiandituLayer,
+  createGeoserverPyramidLayer,
+  createWmsLayer,
+  createWmtsLayer,
+} from '@3clear/basegis/layers'
+
+const tianditu = createTiandituLayer({
+  id: 'tdt-img',
+  name: '天地图影像',
+  resourceKey: 'imagery',
+  category: 'basemap',
+  engineSupport: ['cesium', 'leaflet'],
+})
+
+const geoserverTile = createGeoserverPyramidLayer({
+  id: 'geoserver-tile',
+  name: 'GeoServer 瓦片',
+  url: 'https://example.com/tiles/{z}/{x}/{y}.png',
+})
+
+const wms = createWmsLayer({
+  id: 'wms-layer',
+  serviceUrl: 'https://example.com/geoserver/wms',
+  layers: 'workspace:layer',
+  parameters: {
+    transparent: true,
+    format: 'image/png',
+  },
+})
+
+const wmts = createWmtsLayer({
+  id: 'wmts-layer',
+  url: 'https://example.com/wmts?...TILEMATRIX={z}&TILEROW={y}&TILECOL={x}',
+  layer: 'workspace:layer',
+  tileMatrixSet: 'EPSG:3857',
+})
+```
+
+## GraphicGroupController
+
+用于一次性加载一组点、线、面、文字、marker。它只调用 `BaseGIS.drawPoint / drawLine / drawPolygon / drawText / addMarker`。
+
+```js
+import { GraphicGroupController } from '@3clear/basegis/methods'
+
+const graphics = new GraphicGroupController({ mapCore })
+
+graphics.load([
+  {
+    type: 'point',
+    id: 'p1',
+    longitude: 104,
+    latitude: 35,
+  },
+  {
+    type: 'line',
+    id: 'l1',
+    positions: [
+      [103, 34],
+      [105, 36],
+    ],
+  },
+  {
+    type: 'text',
+    id: 't1',
+    longitude: 104,
+    latitude: 35,
+    text: '站点',
+  },
+])
+
+graphics.clear()
+graphics.getState()
+```
+
+## ImageLayerController
+
+用于加载图片覆盖层或 TIF 图片集合，并提供上一张、下一张、显隐和销毁能力。
+
+```js
+import { ImageLayerController } from '@3clear/basegis/methods'
+
+const imageLayer = new ImageLayerController({
+  mapCore,
+  layerId: 'radar-image',
+  opacity: 0.85,
+  defaultArea: {
+    startLon: 73,
+    startLat: 18,
+    endLon: 135,
+    endLat: 54,
+  },
+})
+
+await imageLayer.load([
+  {
+    id: 'radar-001',
+    name: '雷达 001',
+    imageUrl: '/data/radar/001.png',
+    area: {
+      startLon: 73,
+      startLat: 18,
+      endLon: 135,
+      endLat: 54,
+    },
+    opacity: 0.8,
+  },
+  {
+    id: 'tif-001',
+    name: 'TIF 001',
+    tifUrl: '/data/grid/001.tif',
+    colorize: true,
+  },
+])
+
+await imageLayer.switchTo('radar-001')
+await imageLayer.next()
+await imageLayer.prev()
+imageLayer.hide()
+imageLayer.show()
+imageLayer.destroy()
+```
+
+常用字段：
+
+- `imageUrl`：普通图片地址。
+- `tifUrl`：GeoTIFF 地址。
+- `area`：图片四至范围，字段为 `startLon / startLat / endLon / endLat`。
+- `opacity`：透明度。
+- `showLabel / showProbe`：显示网格标注或探针。
+- `colorize / colorStops / colors`：色带渲染配置。
+
+## GridLayerController
+
+用于 TIF 网格、灰度图网格、外部数值网格。
+
+```js
+import { GridLayerController } from '@3clear/basegis/methods'
+
+const gridLayer = new GridLayerController({
+  mapCore,
+  layerId: 'temperature-grid',
+  showLabel: true,
+  showProbe: true,
+  decimalPlaces: 1,
+})
+
+await gridLayer.loadTif({
+  tifUrl: '/data/grid/temp.tif',
+  colorize: true,
+})
+
+await gridLayer.loadGrayImage({
+  imageUrl: '/data/grid/temp-gray.png',
+  area: {
+    startLon: 73,
+    startLat: 18,
+    endLon: 135,
+    endLat: 54,
+  },
+  colorize: true,
+})
+
+await gridLayer.loadData({
+  imageGridData: [
+    [12.1, 13.4],
+    [14.2, 15.6],
+  ],
+  area: {
+    startLon: 100,
+    startLat: 30,
+    endLon: 110,
+    endLat: 40,
+  },
+})
+
+gridLayer.update({ opacity: 0.7 })
+gridLayer.hide()
+gridLayer.show()
+gridLayer.destroy()
+```
+
+## PointLargeLayerController
+
+用于海量点位渲染，支持显隐、高亮、删除单点、批量删除、清空和状态读取。
+
+```js
+import { PointLargeLayerController } from '@3clear/basegis/methods'
+
+const largePoints = new PointLargeLayerController({
+  mapCore,
+  layerId: 'station-large',
+  idKey: 'staNum',
+  image: '/icons/station.png',
+  width: 24,
+  height: 24,
+  onClick(point) {
+    console.log('点击站点', point)
+  },
+})
+
+await largePoints.load({
+  points: [
+    { staNum: 'A001', longitude: 104, latitude: 35, name: 'A001' },
+    { staNum: 'A002', longitude: 105, latitude: 36, name: 'A002' },
+  ],
+})
+
+largePoints.setHighlight('A001')
+largePoints.clearHighlight()
+largePoints.removePoint('A002')
+largePoints.removePoints(['A001', 'A003'])
+largePoints.hide()
+largePoints.show()
+largePoints.clear()
+largePoints.destroy()
+largePoints.getState()
+```
+
+点位字段默认支持：
+
+- 经度：`longitude / lon / lng / x`
+- 纬度：`latitude / lat / y`
+- 高度：`height / altitude / z`
+- 唯一值：默认 `id`，可通过 `idKey` 指定
+
+## PointDensityController
+
+用于点位密度抽稀。地图移动、缩放后按屏幕网格重新计算可见点，适合站点、设备、告警等高密度点位。
+
+```js
+import { PointDensityController } from '@3clear/basegis/methods'
+
+const density = new PointDensityController({
+  mapCore,
+  layerId: 'station-density',
+  idKey: 'staNum',
+  gridSize: 150,
+  maxCount: 500,
+  priorityKey: 'level',
+  image: '/icons/station.png',
+  width: 28,
+  height: 28,
+  onClick(point) {
+    console.log(point)
+  },
+  onStateChange(state) {
+    console.log(state.visibleCount, state.hiddenCount)
+  },
+})
+
+await density.load({
+  points: [
+    { staNum: 'A001', longitude: 104, latitude: 35, level: 5 },
+    { staNum: 'A002', longitude: 104.01, latitude: 35.01, level: 3 },
+  ],
+})
+
+density.update({ gridSize: 120 })
+density.hide()
+density.show()
+density.toggle()
+density.refreshState()
+density.clear()
+density.destroy()
+```
+
+常用参数：
+
+- `enableThinning`：是否开启抽稀，默认开启。
+- `gridSize / pixelRange`：屏幕网格大小，单位像素。
+- `maxCount`：最多显示点数。
+- `priorityKey / priorityCallback`：同网格内优先显示哪个点。
+- `viewportBuffer`：Cesium 屏幕视野缓冲。
+- `cullByGlobe`：Cesium 3D 下是否剔除地球背面点。
+- `boundsBufferRatio`：Leaflet bounds 扩展比例。
+
+## ContourLayerController
+
+用于等值线图层，支持加载、更新、显隐、清空和销毁。
+
+```js
+import { ContourLayerController } from '@3clear/basegis/methods'
+
+const contour = new ContourLayerController({
+  mapCore,
+  layerId: 'temperature-contour',
+  visible: true,
+})
+
+await contour.load({
+  contours: [
+    {
+      value: 20,
+      lines: [
+        [
+          [30, 104],
+          [31, 105],
+          [32, 106],
+        ],
+      ],
+    },
+  ],
+  style: {
+    color: '#ff4d4f',
+    width: 2,
+  },
+})
+
+await contour.update({
+  style: {
+    color: '#1677ff',
+  },
+})
+
+contour.hide()
+contour.show()
+contour.clear()
+contour.destroy()
+```
+
+数据别名支持 `contours / isolines / isoline / lines / data / items`。
+
+## PressureContourLayer
+
+用于等压线和高低压中心标注。`buildPressureRenderData()` 可把 Windy 风格的 `press.json` 数据整理成渲染结构，`createPressureDataResolver()` 提供简单缓存。
+
+```js
+import {
+  PressureContourLayer,
+  createPressureDataResolver,
+} from '@3clear/basegis/methods'
+
+const resolvePressureData = createPressureDataResolver({
+  default: pressJson,
+  next: pressJson2,
+})
+
+const pressureLayer = new PressureContourLayer({
+  mapCore,
+  layerId: 'pressure',
+  color: 'rgba(255,255,255,0.82)',
+  width: 1.15,
+  smoothFactor: 0.2,
+  // Cesium 场景下用于定位容器尺寸，Leaflet 场景也可以传同一个地图容器 id。
+  mapContainerId: 'map',
+  // 标注层通过该函数读取当前数据，便于地图缩放后重建标签。
+  getData: () => resolvePressureData('default'),
+  isAnnotationVisible: () => true,
+})
+
+pressureLayer.mount()
+await pressureLayer.load(resolvePressureData('default'))
+await pressureLayer.update(resolvePressureData('next'))
+pressureLayer.hide()
+pressureLayer.destroy()
+```
+
+说明：
+
+- 等压线数据会被整理为 `isolines` 和 `centers`。
+- Leaflet 使用 `divIcon` 绘制 H/L 中心和线值标签。
+- Cesium 使用独立标注集合，地图变化时会调度刷新。
+
+## WindFieldMethods
+
+用于叠加 Canvas 风场粒子动画。它通过 `BaseGIS` 获取容器、投影、视野范围和视图变化事件，不直接依赖某个引擎。
+
+```js
+import { WindFieldMethods } from '@3clear/basegis/methods'
+
+const wind = new WindFieldMethods({ mapCore })
+
+wind.addWindField({
+  id: 'wind-main',
+  data: windData,
+  particleCount: 3000,
+  velocityScale: 0.01,
+  lineWidth: 1,
+  color: 'rgba(80, 180, 255, 0.8)',
+})
+
+wind.updateWindField({
+  id: 'wind-main',
+  particleCount: 5000,
+})
+
+wind.stopWindField('wind-main')
+wind.startWindField('wind-main')
+wind.hideWindField('wind-main')
+wind.showWindField('wind-main')
+wind.removeWindField('wind-main')
+wind.clearWindFields()
+wind.getState()
+```
+
+## 直接使用 BaseGIS 图层方法
+
+控制器适合页面长期维护状态。如果只是一次调用，也可以直接用 `BaseGIS` 方法。
+
+```js
+await mapCore.upsertImageLayer({
+  layerId: 'image-layer',
+  imageUrl: '/data/image.png',
+  area: {
+    startLon: 73,
+    startLat: 18,
+    endLon: 135,
+    endLat: 54,
+  },
+})
+mapCore.hideImageLayer({ layerId: 'image-layer' })
+mapCore.showImageLayer({ layerId: 'image-layer' })
+mapCore.removeImageLayer({ layerId: 'image-layer' })
+
+await mapCore.upsertGridLayer({
+  layerId: 'grid-layer',
+  tifUrl: '/data/grid.tif',
+})
+mapCore.removeGridLayer({ layerId: 'grid-layer' })
+
+await mapCore.upsertPointLargeLayer({
+  layerId: 'large-points',
+  points: [{ id: '1', longitude: 104, latitude: 35 }],
+})
+mapCore.setPointLargeHighlight({ layerId: 'large-points', pointId: '1' })
+mapCore.clearPointLargeHighlight({ layerId: 'large-points' })
+mapCore.removePointLargePoint({ layerId: 'large-points', pointId: '1' })
+mapCore.clearPointLargeLayer({ layerId: 'large-points' })
+mapCore.removePointLargeLayer({ layerId: 'large-points' })
+
+await mapCore.upsertPointDensityLayer({
+  layerId: 'density-points',
+  points: [{ id: '1', longitude: 104, latitude: 35 }],
+  gridSize: 150,
+})
+mapCore.getPointDensityLayerState({ layerId: 'density-points' })
+mapCore.removePointDensityLayer({ layerId: 'density-points' })
+
+await mapCore.upsertContourLayer({
+  layerId: 'contour',
+  contours: [],
+})
+await mapCore.updateContourLayer({ layerId: 'contour', contours: [] })
+mapCore.getContourLayerState({ layerId: 'contour' })
+mapCore.removeContourLayer({ layerId: 'contour' })
+```
+
+## 在 Vue 中封装 Hook
+
+推荐页面用 hook 管理生命周期，组件只处理 UI。
+
+```js
+import { onBeforeUnmount, onMounted, shallowRef } from 'vue'
+import { BaseGIS } from '@3clear/basegis'
+
+export function useBaseGIS(options = {}) {
+  const mapCore = shallowRef(null)
+
+  onMounted(() => {
+    mapCore.value = new BaseGIS(options)
+    mapCore.value.init()
+  })
+
+  onBeforeUnmount(() => {
+    mapCore.value?.destroy()
+    mapCore.value = null
+  })
+
+  return {
+    mapCore,
+  }
+}
+```
+
+使用：
+
+```vue
+<template>
+  <div id="map" class="map"></div>
+</template>
+
+<script setup>
+import { useBaseGIS } from './useBaseGIS'
+
+const { mapCore } = useBaseGIS({
+  engineType: 'cesium',
+  containerId: 'map',
+})
+</script>
+```
+
+## 能力支持说明
+
+| 能力 | Cesium | Leaflet |
+| --- | --- | --- |
+| 2D 地图 | 支持 | 支持 |
+| 2.5D / 3D 场景 | 支持 | 不支持 |
+| 放大、缩小、重置 | 支持 | 支持 |
+| 底图切换 | 支持 | 支持 |
+| 点线面文字 | 支持 | 支持 |
+| 图片覆盖层 | 支持 | 支持 |
+| 网格 / TIF | 支持 | 支持 |
+| 海量点 | 支持 | 支持 |
+| 点位密度抽稀 | 支持 | 支持 |
+| 等值线 | 支持 | 支持 |
+| 等压线标注 | 支持 | 支持 |
+| 风场 Canvas 动画 | 支持 | 支持 |
+| DEM 地形 | 支持 | 不支持 |
+
+## 本地开发与打包
+
+在仓库根目录执行：
+
+```bash
+npm run build:basegis
+npm run pack:basegis
+```
+
+`build:basegis` 会生成：
+
+```text
+packages/basegis/dist/basegis.js
+packages/basegis/dist/methods.js
+packages/basegis/dist/layers.js
+packages/basegis/dist/assets.js
+packages/basegis/dist/style.css
+```
+
+`pack:basegis` 会在仓库根目录生成类似文件：
+
+```text
+3clear-basegis-0.1.0.tgz
+```
+
+其他项目本地安装：
+
+```bash
+npm install ./3clear-basegis-0.1.0.tgz
+```
+
+## 发布到 npm
+
+只发布 `packages/basegis`，不要在项目根目录执行 `npm publish`，否则会把整个业务项目上传到 npm。
+
+发布前检查包内容：
+
+```bash
+npm pack --dry-run ./packages/basegis
+```
+
+发布 scoped 包：
+
+```bash
+npm publish ./packages/basegis --access public
+```
+
+如果只希望私有发布，保留 `packages/basegis/package.json` 中的：
+
+```json
+{
+  "publishConfig": {
+    "access": "restricted"
+  }
+}
+```
+
+如果希望公开发布，需要改为：
+
+```json
+{
+  "publishConfig": {
+    "access": "public"
+  }
+}
+```
+
+## 常见问题
+
+### Cesium 地图不显示
+
+检查宿主项目是否存在：
+
+```text
+public/lib/Cesium/Cesium.js
+public/lib/Cesium/Widgets/widgets.css
+```
+
+并确认页面初始化前能访问 `window.Cesium`。
+
+### Leaflet 样式异常
+
+确认已引入：
+
+```js
+import '@3clear/basegis/style.css'
+```
+
+### 调用方法返回 NOT_INITIALIZED
+
+说明地图还没有初始化成功。先执行：
+
+```js
+const result = mapCore.init()
+console.log(result.success, result.message)
+```
+
+### 切换配置后地图没有变化
+
+`setConfig()` 只更新 `BaseGIS` 内部配置，不会自动重建地图。需要销毁后重新初始化：
+
+```js
+mapCore.setConfig(nextConfig)
+mapCore.init()
+```
+
+`init()` 内部会先销毁旧适配器，再创建新实例。