map_view_vue3 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,232 @@
+# map_view_vue3
+
+基于 Vue 3 + OpenLayers 的地图查看器组件，支持栅格图片、本地切片 XYZ、在线 XYZ、GeoJSON/SLD 数据加载，并提供坐标系切换、图层管理、拖拽加载等能力。
+
+## 目录结构
+
+```text
+map_view_vue3/
+├─ map_view_vue3.js          # ESM 构建产物
+├─ map_view_vue3.umd.cjs     # UMD 构建产物
+├─ map_view_vue3.css         # 组件样式
+├─ types/index.d.ts          # TypeScript 类型声明
+├─ favicon.svg
+└─ icons.svg
+```
+
+## 引入方式
+
+### 方式一：按需引入组件
+
+```ts
+import { createApp } from 'vue'
+import { MapViewVue3 } from './map_view_vue3/map_view_vue3.js'
+import './map_view_vue3/map_view_vue3.css'
+
+import App from './App.vue'
+
+const app = createApp(App)
+app.component('MapViewVue3', MapViewVue3)
+app.mount('#app')
+```
+
+### 方式二：全局插件式注册
+
+```ts
+import { createApp } from 'vue'
+import MapViewVue3 from './map_view_vue3/map_view_vue3.js'
+import './map_view_vue3/map_view_vue3.css'
+
+import App from './App.vue'
+
+const app = createApp(App)
+app.use(MapViewVue3)
+app.mount('#app')
+```
+
+## 基础用法
+
+```vue
+<template>
+  <MapViewVue3
+    theme="light"
+    data-crs="EPSG:3857"
+    :zoom="4.2"
+    width="1000px"
+    height="800px"
+    map-background="#ffffff"
+    :auto-load="autoLoad"
+    @view-changed="onViewChanged"
+    @active-map-changed="onActiveMapChanged"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const autoLoad = ref({
+  type: 'manifest',
+  url: 'http://localhost:7010/geojson/metadata.json',
+  baseUrl: 'http://localhost:7010/geojson'
+})
+
+function onViewChanged(state: { center: number[] | null; zoom: number | null; crs: string }) {
+  console.log('视野变化', state)
+}
+
+function onActiveMapChanged(payload: { id: number; name: string; kind: string }) {
+  console.log('当前地图变化', payload)
+}
+</script>
+```
+
+## Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `theme` | `'light' \| 'dark'` | `'light'` | 明暗主题 |
+| `dataCrs` | `string` | `'EPSG:3857'` | 初始数据坐标系 |
+| `zoom` | `number` | `4.2` | 初始缩放级别 |
+| `hidePanels` | `boolean` | `false` | 是否隐藏两侧面板 |
+| `width` | `string \| number \| null` | `null` | 固定宽度，如 `'1000px'` |
+| `height` | `string \| number \| null` | `null` | 固定高度，如 `'800px'` |
+| `mapBackground` | `string \| null` | `null` | 地图画布背景色 |
+| `autoLoad` | `AutoLoadConfig \| null` | `null` | 挂载后自动加载数据源 |
+
+## autoLoad 示例
+
+### 加载 GeoJSON 清单
+
+```ts
+const autoLoad = {
+  type: 'manifest',
+  url: 'https://example.com/geojson/metadata.json',
+  baseUrl: 'https://example.com/geojson'
+}
+```
+
+### 加载图片
+
+```ts
+const autoLoad = {
+  type: 'image',
+  url: 'https://example.com/map.png',
+  worldFile: 'https://example.com/map.pgw',
+  crs: 'EPSG:3857',
+  name: '示例地图'
+}
+```
+
+## 事件
+
+| 事件名 | 参数 | 说明 |
+| --- | --- | --- |
+| `theme-changed` | `theme: 'light' \| 'dark'` | 主题切换 |
+| `view-changed` | `{ center, zoom, crs }` | 视野变化 |
+| `active-map-changed` | `{ id, name, kind }` | 当前地图切换 |
+| `map-removed` | `{ id, name, kind }` | 地图删除 |
+| `layer-removed` | `{ isGroup, name, layerCount, group }` | 图层删除 |
+| `notify` | `{ message, type }` | 通知信息 |
+
+## 常用实例方法
+
+可以通过模板 `ref` 调用组件内部暴露的方法。
+
+```vue
+<template>
+  <MapViewVue3 ref="viewer" />
+  <button @click="loadLayers">加载图层</button>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const viewer = ref()
+
+async function loadLayers() {
+  await viewer.value?.loadGeoJsonFromData([
+    {
+      name: '道路',
+      geojson: { type: 'FeatureCollection', features: [] },
+      sld: '<StyledLayerDescriptor></StyledLayerDescriptor>'
+    }
+  ])
+}
+</script>
+```
+
+常用方法包括：
+
+| 方法 | 说明 |
+| --- | --- |
+| `waitViewerReady()` | 等待地图查看器初始化完成 |
+| `loadImageFromUrl(options)` | 通过 URL 加载图片地图 |
+| `addXyzLayer(options)` | 加载在线 XYZ 图层 |
+| `loadGeoJsonFromFiles(files)` | 加载 GeoJSON / SLD 文件 |
+| `loadGeoJsonFromManifest(manifest, baseUrl?)` | 通过 manifest 加载矢量数据 |
+| `loadGeoJsonFromData(layers)` | 直接传入 GeoJSON / SLD 数据 |
+| `fitActiveMap()` | 定位到当前地图 |
+| `fitToExtent(extent, projection?)` | 定位到指定范围 |
+| `getViewState()` | 获取当前视野状态 |
+| `getActiveMapInfo()` | 获取当前地图信息 |
+| `applyTheme(theme)` | 切换明暗主题 |
+| `normalizeEpsg(value)` | 规范化 EPSG 代码 |
+
+## 数据格式说明
+
+### GeoJSON / SLD 目录
+
+支持按文件名主干配对的 `.geojson` / `.json` 与 `.sld` / `.xml` 文件。
+
+```text
+layers/
+├─ roads.geojson
+├─ roads.sld
+├─ buildings.geojson
+└─ buildings.sld
+```
+
+### manifest 示例
+
+```json
+{
+  "layers": [
+    {
+      "name": "道路",
+      "geojson": "roads.geojson",
+      "sld": "roads.sld"
+    },
+    {
+      "name": "建筑",
+      "geojson": "buildings.geojson",
+      "sld": "buildings.sld"
+    }
+  ]
+}
+```
+
+如果 `metadata.json` 存在，会用于图层排序和标题显示。
+
+## 注意事项
+
+1. 使用前请确保项目已引入 Vue 3。
+2. 本组件依赖 OpenLayers 与 proj4，构建产物中通常已经打包；如果你使用源码方式集成，请确保项目里已安装相关依赖。
+3. 加载远程 GeoJSON、图片或切片时，注意目标服务是否允许跨域访问。
+4. 如果使用本地切片目录，推荐按 `z/x/y.png` 的 XYZ 结构组织数据。
+5. 如需在线获取 EPSG 定义，需要能访问 `epsg.io`。
+
+## TypeScript
+
+类型声明位于 `types/index.d.ts`，可以直接使用：
+
+```ts
+import type {
+  MapViewerProps,
+  MapViewerEmits,
+  MapViewerInstance
+} from './map_view_vue3/types'
+```
+
+## 许可证
+
+ISC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "map_view_vue3",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "",
   "main": "map_view_vue3.js",
   "types": "types/index.d.ts",