map_view_vue2 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,171 @@
+# map_view_vue2 地图查看器组件
+
+> 基于 OpenLayers + proj4 的 Vue 2 地图查看器组件，支持 PNG 栅格地图（世界文件定位）、GeoJSON + SLD 矢量图层、多坐标系切换、明暗主题，开箱即用。
+
+## 安装
+
+```bash
+# npm
+npm install map_view_vue2 --save
+
+# yarn
+yarn add map_view_vue2
+```
+
+```bash
+// main.js
+import MapView from 'map_view_vue2'
+import 'map_view_vue2/map_view_vue2.css'
+Vue.use(MapView)
+
+```
+
+## 快速上手
+
+完整绑定示例（全部 props 与全部事件）：
+
+```vue
+<template>
+  <div id="app">
+    <mapView
+      ref="viewer"
+      :theme="theme"
+      :data-crs="dataCrs"
+      :zoom="zoom"
+      :hide-panels="hidePanels"
+      :show-loader="showLoader"
+      :width="viewerWidth"
+      :height="viewerHeight"
+      :map-background="mapBackground"
+      :auto-load="autoLoad"
+      @layer-removed="onLayerRemoved"
+      @view-changed="onViewChanged"
+      @theme-changed="onThemeChanged" />
+  </div>
+</template>
+
+<script>
+export default {
+  data () {
+    return {
+      theme: 'light',       // light | dark
+      dataCrs: 'EPSG:3857', // 初始数据坐标系
+      zoom: 4.2,            // 初始缩放级别
+      hidePanels: false,     // 嵌入模式隐藏两侧面板
+      viewerWidth: '1000px',  // 查看器宽度：数字按 px，字符串原样使用；null 铺满父容器
+      viewerHeight: '800px',  // 查看器高度：数字按 px，字符串原样使用；null 铺满父容器
+      mapBackground: '#ffffff', // 地图画布背景色；null 跟随明暗主题默认背景
+      autoLoad: {
+        type: 'manifest',   // manifest=矢量清单 / image=PNG 栅格地图
+        url: 'http://your-server.com/geojson/metadata.json',
+        baseUrl: 'http://your-server.com/geojson'
+      }
+    };
+  },
+  methods: {
+    // 图层删除：info = { isGroup, name, layerCount, group }
+    onLayerRemoved ({ isGroup, name, layerCount, group }) {
+      // isGroup :true --- 点击的是图层组的删除， false----点击的是图层组下面的删除
+      if (isGroup) {
+        console.log('删除了图层组：' + name + '，包含 ' + layerCount + ' 个图层');
+      } else {
+        console.log('删除了图层：' + name);
+      }
+    },
+    // 视图变化（moveend）：state = { center, zoom, crs, ... }
+    onViewChanged (state) {},
+    // 主题切换：theme = light | dark
+    onThemeChanged (theme) {}
+  }
+};
+</script>
+```
+## Props
+
+| Prop | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| theme | String | 'light' | 初始主题：light / dark，可在查看器内切换。 |
+| dataCrs | String | 'EPSG:3857' | 初始数据坐标系（EPSG 代码）。 |
+| zoom | Number | 4.2 | 初始缩放级别。 |
+| hidePanels | Boolean | false | 隐藏两侧面板（嵌入模式）。 |
+| width | String / Number | null | 固定查看器宽度：数字按 px，字符串原样使用（如 600 → 600px、100% → 100%）。不传则铺满父容器。 |
+| height | String / Number | null | 固定查看器高度：同上（如 800 → 800px、100vh）。不传则铺满父容器。 |
+| mapBackground | String | null | 地图画布背景色（任意 CSS 颜色值）。不传则跟随明暗主题默认背景。 |
+| autoLoad | Object | null | 挂载后自动加载的数据源，见下方说明。 |
+
+## autoLoad 自动加载数据源
+
+组件挂载后按 `autoLoad` 配置自动加载地图，`type` 支持两种：
+
+### type: manifest —— 矢量地图（GeoJSON + SLD 清单）
+
+```js
+autoLoad: {
+  type: 'manifest',
+  url: 'http://xxx.xxx.xxx.xx:xx/geojson/metadata.json',   // 清单接口地址
+  baseUrl: 'http://xxx.xxx.xxx.xx:xx/geojson'               // 清单内相对文件名的前缀
+}
+```
+
+- 清单支持三种格式：URL 数组、`{ files: [...] }`、QGIS 导出的 `{ name, layers: [{ title, geojson, sld }] }`
+- `.geojson` / `.json` 识别为矢量图层，`.sld` 按**同名主干**自动配对到对应 GeoJSON
+- `metadata.json` 作为元数据使用（图层排序与标题）
+
+### type: image —— PNG 栅格地图
+
+```js
+autoLoad: {
+  type: 'image',
+  url: 'http://xxx.xxx.xxx.xx:xx/333.png',        // PNG 图片地址
+  worldFile: 'http://xxx.xxx.xxx.xx:xx/333.pgw',   // 世界文件地址
+  name: '矿区底图'                                 // 可选：地图条目显示名称
+}
+```
+
+- 世界文件扩展名支持：`.pgw` / `.pwg` / `.jgw` / `.gfw` / `.wld` / `.pngw` / `.jpgw`
+- 世界文件只提供地理范围与分辨率，**不含坐标系**，务必通过 `crs` 指定
+
+## Events
+
+| 事件 | 载荷 | 触发时机 |
+| --- | --- | --- |
+| map-added | { id, name, kind, extent, projection } | 新地图加载完成并加入列表。 |
+| active-map-changed | { id, name, kind } | 当前活动地图切换。 |
+| map-removed | { id, name, kind } | 地图条目被删除。 |
+| layer-removed | { isGroup, name, layerCount, group } | 图层被移除。 |
+| view-changed | { center, zoom, crs, ... } | 视图移动/缩放结束（moveend）。 |
+| theme-changed | theme（light / dark） | 明暗主题切换。 |
+
+## TypeScript
+
+包内自带类型声明（`index.d.ts`），TypeScript 项目无需额外安装 `@types`：
+
+```ts
+import mapView from 'map_view_vue2'
+
+// autoLoad / 事件载荷等均有完整类型提示
+const autoLoad: import('map_view_vue2').AutoLoadSource = {
+  type: 'manifest',
+  url: 'http://xxx.xxx.xxx.xx:xx/geojson/metadata.json',
+  baseUrl: 'http://xxx.xxx.xxx.xx:xx/geojson'
+};
+```
+
+## 内置功能
+
+- 侧栏右缘拖拽调宽（280 ~ 620px），缩放、全屏、比例尺、版权信息自动跟随
+- 侧栏收起 / 展开
+- 视图坐标系切换（所有图层自动重投影）
+- GeoJSON 数据坐标系自动识别（优先读取文件声明的 CRS，如 CRS84 → EPSG:4326）
+- 图层显隐、缩放定位、删除，GeoJSON 按 layer 属性自动分组
+- 明暗主题切换
+
+## 注意事项
+
+1. 所有远程数据（清单、GeoJSON、SLD、PNG、世界文件）通过浏览器加载，跨域时数据服务必须返回 `Access-Control-Allow-Origin` 响应头
+2. 世界文件只提供地理位置与尺寸，不含坐标系信息，加载 PNG 地图时务必通过 `crs` 指定正确坐标系
+3. 组件依赖 `ol` 与 `proj4`，安装包时会自动带入
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,138 @@
+/**
+ * map_view_vue2 地图查看器组件类型声明（Vue 2）
+ *
+ * 组件基于 OpenLayers + proj4，支持 PNG 栅格地图（世界文件定位）、
+ * GeoJSON + SLD 矢量图层、多坐标系切换与明暗主题。
+ */
+import Vue from 'vue';
+
+/** 主题类型 */
+export type MapViewTheme = 'light' | 'dark';
+
+/** autoLoad：矢量清单数据源 */
+export interface AutoLoadManifest {
+  type: 'manifest';
+  /** 清单接口地址：支持 URL 数组、{ files: [...] } 与 QGIS 导出 { layers: [{ title, geojson, sld }] } */
+  url: string;
+  /** 清单内相对文件名的前缀 */
+  baseUrl?: string;
+}
+
+/** autoLoad：PNG 栅格数据源 */
+export interface AutoLoadImage {
+  type: 'image';
+  /** PNG 图片地址 */
+  url: string;
+  /** 世界文件地址（支持 .pgw / .pwg / .jgw / .gfw / .wld / .pngw / .jpgw） */
+  worldFile?: string;
+  /** 世界文件文本内容（传入时优先于 worldFile） */
+  worldText?: string;
+  /** 数据坐标系：世界文件不含坐标系信息；不传时自动按范围猜测中国高斯投影带号，未命中默认按 EPSG:3857 解析 */
+  crs?: string;
+  /** 地图条目显示名称 */
+  name?: string;
+  /** 固定地理范围 [minx, miny, maxx, maxy]，传入时忽略世界文件 */
+  extent?: [number, number, number, number];
+}
+
+/** autoLoad 数据源配置 */
+export type AutoLoadSource = AutoLoadManifest | AutoLoadImage;
+
+/** 地图条目信息（map-added / active-map-changed / map-removed 事件载荷） */
+export interface MapInfo {
+  id: number;
+  name: string;
+  /** 地图类型：image / geojson / xyz 等 */
+  kind: string;
+  /** 数据范围 [minx, miny, maxx, maxy]（仅 map-added 提供） */
+  extent?: number[];
+  /** 数据坐标系代码（仅 map-added 提供） */
+  projection?: string;
+}
+
+/** 图层删除事件载荷 */
+export interface LayerRemovedInfo {
+  /** 是否为图层组 */
+  isGroup: boolean;
+  /** 图层（组）名称 */
+  name: string;
+  /** 图层组包含的图层个数（仅图层组时提供） */
+  layerCount: number | null;
+  /** 所属分组名（仅图层组时提供） */
+  group: string | null;
+}
+
+/** 视图变化事件载荷（view-changed） */
+export interface ViewState {
+  center: number[];
+  zoom: number;
+  crs: string;
+  [key: string]: unknown;
+}
+
+/** 组件实例方法：通过模板 ref 调用，如 this.$refs.viewer.loadImageFromUrl({...}) */
+export interface MapViewInstance extends Vue {
+  /** 加载在线 XYZ 切片图层 */
+  addXyzLayer (options: {
+    url: string;
+    crs?: string;
+    minZoom?: number;
+    maxZoom?: number;
+    extent?: number[] | null;
+    extentCrs?: string | null;
+  }): Promise<unknown>;
+  /** 从 URL 加载 PNG 栅格地图（可选世界文件地址或文本） */
+  loadImageFromUrl (options: {
+    url: string;
+    name?: string | null;
+    crs?: string;
+    worldFileUrl?: string | null;
+    worldText?: string | null;
+    extent?: number[] | null;
+  }): Promise<unknown>;
+  /** 从清单对象加载矢量图层 */
+  loadGeoJsonFromManifest (manifest: unknown, baseUrl?: string): Promise<unknown>;
+  /** 从内联数据加载矢量图层：layers = [{ name, geojson, sld }]，顺序即图层顺序 */
+  loadGeoJsonFromData (layers: Array<{ name: string; geojson: unknown; sld?: string }>): Promise<unknown>;
+  /** 从 File 列表加载 GeoJSON + SLD（同名主干自动配对） */
+  loadGeoJsonFromFiles (files: File[]): Promise<unknown>;
+  /** 定位到当前活动地图的地理范围 */
+  fitActiveMap (): void;
+}
+
+/** 组件 Props 定义 */
+export interface MapViewProps {
+  /** 初始主题：light / dark */
+  theme?: MapViewTheme;
+  /** 初始数据坐标系（EPSG 代码） */
+  dataCrs?: string;
+  /** 初始缩放级别 */
+  zoom?: number;
+  /** 隐藏两侧面板（嵌入模式） */
+  hidePanels?: boolean;
+  /** 是否显示「加载地图」按钮与对话框 */
+  showLoader?: boolean;
+  /** 固定查看器宽度：数字按 px，字符串原样使用；null 铺满父容器 */
+  width?: string | number | null;
+  /** 固定查看器高度：数字按 px，字符串原样使用；null 铺满父容器 */
+  height?: string | number | null;
+  /** 地图画布背景色（任意 CSS 颜色值）；null 跟随明暗主题默认背景 */
+  mapBackground?: string | null;
+  /** 挂载后自动加载的数据源 */
+  autoLoad?: AutoLoadSource;
+}
+
+/**
+ * 地图查看器组件（Vue 2）
+ *
+ * @example
+ * import mapView from 'map_view_vue2'
+ * import 'map_view_vue2/map_view_vue2.css'
+ *
+ * export default {
+ *   components: { mapView }
+ * }
+ */
+declare const MapView: Vue.ComponentOptions<Vue> & MapViewProps;
+
+export default MapView;