更新记录

2.0.0（2026-03-30） 下载此版本

v2.0.0 (2026.03.30)

• 初始版本发布

平台兼容性

uni-app(4.23)

ZMap 组件使用文档

概述

ZMap 是一个基于 OpenLayers 的 uni-app 跨平台地图组件，支持 H5 和 App 端。提供地图初始化、中心点绘制、批量点位、几何图形绘制、GeoJSON 加载和热力图等功能。

安装依赖

npm install ol

组件引入

<template>
  <z-map ref="mapRef" @ready="onMapReady" />
</template>

<script setup>
import ZMap from '@/components/z-map/z-map.vue';
import { ref } from 'vue';

const mapRef = ref(null);
const onMapReady = () => {
  mapRef.value?.mapInit({
    sourceParams: { /* 瓦片源配置 */ },
    mapOptions: { /* 地图选项 */ },
    controlOptions: { /* 控件选项 */ }
  });
};
</script>

Props

Events

地图初始化方法

mapInit(mapConfig)

初始化地图实例，必须在 ready 事件后调用。

参数:

示例：

mapRef.value?.mapInit({
  sourceParams: {
    tdt: 'https://t0.tianditu.gov.cn/...'
  },
  mapOptions: {
    center: [118.050, 24.621],
    zoom: 12
  },
  controlOptions: {
    zoom: false,
    attribution: false
  }
});

地图中心控制方法

mapChangeCenter({ lat, lng, projection, zoom })

移动地图中心点。

参数：

示例：

mapRef.value?.mapChangeCenter({
  lat: 24.620,
  lng: 119.055,
  zoom: 10
});

图标绘制方法

注意 若在App端进行使用，则需安装依赖：

npm install image-tools

对路径资源进行base64化处理。

mapDrawCenterPoint(iconConfig)

在地图中心点绘制图标。

参数：

清除：

使用mapDrawCenterPoint('remove')， 传入 'remove'即可 清除当前中心点图标。

示例：

const centerIcon = await pathToBase64('/static/z-map/nav-up.png')
zMapRef.value?.mapDrawCenterPoint({
    lng: 118.050,
    lat: 24.621,
    url: centerIcon,
    scale: 0.6
});

注意

H5可直接使用静态资源路径，但若在App中运行则需使用pathToBase64转为base64格式，否则在真机中不显示图标

mapDrawBatchIcon(listConfig)

批量绘制点位图标。

参数：

清除：

使用mapDrawBatchIcon('remove')， 传入 'remove'即可 清除当前中心点图标。

示例：

const iconPath = await pathToBase64('/static/z-map/location.png');
const listConfig = {
    config: {
        scale: 0.5,
        enableCluster: false
    },
    list: [{
            lng: 118.051,
            lat: 24.621,
            iconPath,
            id: 'p1',
            name: '点位 1'
        },
        {
            lng: 118.052,
            lat: 24.621,
            iconPath,
            id: 'p2',
            name: '点位 2'
        },
        {
            lng: 118.053,
            lat: 24.621,
            iconPath,
            id: 'p3',
            name: '点位 3'
        },
        {
            lng: 118.054,
            lat: 24.621,
            iconPath,
            id: 'p4',
            name: '点位 4'
        },
    ]
};

zMapRef.value?.mapDrawBatchIcon(listConfig);

几何图形绘制方法

mapDrawCircle(circleConfig)

绘制圆形标记。

参数：

清除：

使用mapDrawCircle('remove')，传入 'remove' 清除所有圆形。

示例：

const circleConfig = {
    style: {
        radius: 50,
        fill: 'rgba(118, 91, 189, 0.3)',
        stroke: '#765BBD'
    },
    list: [{
            lng: 118.061,
            lat: 24.621,
            id: 'c1',
            name: '区域 1'
        },
        {
            lng: 118.072,
            lat: 24.621,
            id: 'c2',
            name: '区域 2'
        },
        {
            lng: 118.083,
            lat: 24.621,
            id: 'c3',
            name: '区域 3'
        },
    ]
};

zMapRef.value?.mapDrawCircle(circleConfig);

mapDrawPolygonPath(pathConfig)

绘制多边形。

参数：

清除：

使用mapDrawPolygonPath('remove')，传入 'remove' 清除多边形。

示例：

const pathConfig = {
    style: {
        fill: 'rgba(37, 198, 122, 0.3)',
        stroke: '#28dd98',
        width: 2
    },
    path: [{
            lng: 118.050,
            lat: 24.621
        },
        {
            lng: 118.083,
            lat: 24.624
        },
        {
            lng: 118.084,
            lat: 24.685
        },
        {
            lng: 118.055,
            lat: 24.686
        },
    ],
    projection: 'EPSG:4326',
    calculateArea: true,
    areaUnit: 'mu',
    polygonCenter: true,
    polygonCenterZoom: 14
};

zMapRef.value?.mapDrawPolygonPath(pathConfig);

mapDrawLinePath(lineConfig)

绘制线段路径。

参数：

清除：

使用mapDrawLinePath('remove')，传入 'remove' 清除线段。

示例：

onst lineConfig = {
    style: {
        stroke: '#6ed718',
        width: 3
    },
    path: [
        [118.055, 24.621],
        [118.056, 24.621],
        [118.057, 24.621],
        [118.058, 24.621],
        [118.059, 24.620],
        [118.059, 24.619],
        [118.055, 24.620],
    ],
    distanceUnit: 'm'
};

zMapRef.value?.mapDrawLinePath(lineConfig);

数据图层方法

mapDrawGeoJson(geoJsonConfig)

加载 GeoJSON 图层。

参数：

清除：

使用mapDrawGeoJson('remove')，传入 'remove' 清除 GeoJSON 图层。

示例：

import GEOJSON_XIAMEN from '@/static/geojson/xiamen.json';

const geoJsonConfig = {
    style: {
        fill: 'rgba(240, 255, 96, 0.1)',
        stroke: '#fff700',
        width: 2
    },
    geoJsonData: GEOJSON_XIAMEN
};

zMapRef.value?.mapDrawGeoJson(geoJsonConfig);

mapDrawHotMap(hotMapConfig)

加载热力图。

参数：

清除：

使用mapDrawHotMap('remove')，传入 'remove' 清除热力图。

示例：

import GEOJSON_HOTMAP from '@/static/geojson/qywz.json';

const hotMapConfig = {
    options: {
        blur: 10,
        radius: 5,
    },
    hotMapData: GEOJSON_HOTMAP
};

zMapRef.value?.mapDrawHotMap(hotMapConfig);

注意事项

0. 平台兼容性：本组件仅支持 H5 和 App 端，小程序端不可用。

1. 依赖安装：使用前必须安装 ol 依赖。

2. 瓦片服务：推荐使用天地图或其他支持跨域的瓦片服务。

3. 图标路径：本地图标建议放在 /static 目录下，直接使用相对路径。

4. 性能优化：当点位数量超过 500 时，建议启用 enableCluster 聚合簇。

更新日志

v2.0.0 (2026.03.30)

• 初始版本发布