Maptalks GL Vue


基于 Maptalks GL 的 Vue 3 地图组件库，支持天地图、谷歌地图、OpenStreetMap 等多种地图源。

English Documentation

特性

- 🗺️ 多地图源支持: 支持天地图、谷歌地图和 OpenStreetMap
- 🎯 位置选择器: 交互式地图选择器,带搜索功能
- 🔍 地理编码: 内置地理编码和逆地理编码
- 🎨 可定制: 灵活的样式和配置选项
- 🔧 TypeScript: 完整的 TypeScript 支持
- ⚡ Vue 3: 使用 Vue 3 组合式 API 构建

安装

``bash
npm install maptalks-gl-vue
`

或

`bash
yarn add maptalks-gl-vue
`

或

`bash
pnpm add maptalks-gl-vue
`

对等依赖

此包需要以下对等依赖：

`bash
npm install vue maptalks-gl ant-design-vue
`

或

`bash
yarn add vue maptalks-gl ant-design-vue
`

或

`bash
pnpm add vue maptalks-gl ant-design-vue
`

快速开始

$3

`typescript
// main.ts
import { createApp } from "vue";
import App from "./App.vue";
import MaptalksGlVue from "maptalks-gl-vue";

const app = createApp(App);

app.use(MaptalksGlVue, {
tk: "你的天地图API密钥", // 可选: 天地图 API key
gk: "你的谷歌地图API密钥", // 可选: 谷歌地图 API key
defaultBaseLayer: "tdt", // 可选: 默认底图
defaultSearchEngine: "tdt", // 可选: 默认搜索引擎
searchEngineAuto: false // 可选: 是否自动切换搜索引擎
});

app.mount("#app");
`

`vue


`

$3

`vue



`

$3

`vue



`

API 文档

$3

| 属性 | 类型 | 默认值 | 说明 |
| ------------------- | -------------- | ------ | -------------------- |
| tk | string | - | 天地图 API 密钥 |
| gk | string | - | 谷歌地图 API 密钥 |
| defaultBaseLayer | tdt/google/osm | tdt | 默认底图 |
| defaultSearchEngine | tdt/google/osm | tdt | 默认搜索引擎 |
| searchEngineAuto | boolean | false | 是否自动切换搜索引擎 |

$3

| 属性 | 类型 | 默认值 | 说明 |
| --------------- | ------- | -------- | ------------------------- |
| modelValue | string | 必填 | 位置坐标 (经度,纬度 格式) |
| search | boolean | true | 启用搜索功能 |
| clickable | boolean | true | 允许点击地图选择位置 |
| dragPan | boolean | true | 启用地图拖动 |
| scrollWheelZoom | boolean | true | 启用鼠标滚轮缩放 |
| doubleClickZoom | boolean | true | 启用双击缩放 |
| pickerIcon | string | 默认图标 | 自定义选择器图标 URL |
| pickerSize | number | 65 | 选择器图标大小(像素) |
| toolbar | boolean | true | 显示地图工具栏 |

$3

| 属性 | 类型 | 默认值 | 说明 |
| ------------ | ------- | ------ | -------------- |
| toolbar | boolean | true | 显示地图工具栏 |
| isFullscreen | boolean | false | 全屏模式 |

$3

#### useMapInstance

访问地图实例:

`typescript
import { useMapInstance } from "maptalks-gl-vue";

const { viewer, container } = useMapInstance();
`

#### useMapGlobalState

管理地图状态:

`typescript
import { useMapGlobalState } from "maptalks-gl-vue";

const mapState = useMapGlobalState();

// 切换底图
mapState.switchBaseLayer({
value: "base_layer_tdt_img",
engine: "tdt"
});

// 控制缩放
mapState.switchZoom("plus");
mapState.switchZoom("minus");

// 重置视图
mapState.resetView();
`

#### useMapFullscreen

处理全屏模式:

`typescript
import { useMapFullscreen } from "maptalks-gl-vue";

const containerRef = ref();
const { isFullscreen, toggleFullscreen } = useMapFullscreen(containerRef);
`

高级用法

$3

`typescript
import { MarkerLayer, GeometryDecoratorType } from "maptalks-gl-vue";

const { viewer } = useMapInstance();
const markerLayer = new MarkerLayer("custom-markers", viewer);

markerLayer.addGeo({
geo: GeometryDecoratorType.MARKER,
id: "marker-1",
type: "custom",
coordinates: [118.5546748, 31.6976106],
options: {
symbol: {
markerFile: "/path/to/icon.png",
markerWidth: 32,
markerHeight: 32
}
}
});
`

$3

`typescript
import { LineLayer, AreaLayer, GeometryDecoratorType } from "maptalks-gl-vue";

// 线条
const lineLayer = new LineLayer("custom-lines", viewer);
lineLayer.addGeo({
geo: GeometryDecoratorType.LINE,
id: "line-1",
type: "route",
coordinates: [
[118.5, 31.6],
[118.6, 31.7]
],
options: {
symbol: {
lineColor: "#1978ff",
lineWidth: 3
}
}
});

// 区域
const areaLayer = new AreaLayer("custom-areas", viewer);
areaLayer.addGeo({
geo: GeometryDecoratorType.AREA,
id: "area-1",
type: "zone",
coordinates: [
[
[118.5, 31.6],
[118.6, 31.6],
[118.6, 31.7],
[118.5, 31.7]
]
],
options: {
symbol: {
polygonFill: "rgba(25, 120, 255, 0.3)",
polygonOpacity: 0.8,
lineColor: "#1978ff",
lineWidth: 2
}
}
});
`

$3

`typescript
import { getTDTSearchResultByKeword, getTDTSearchResultByGeocode } from "maptalks-gl-vue";

// 关键词搜索
const searchResult = await getTDTSearchResultByKeword({
postStr: JSON.stringify({
keyWord: "北京",
mapBound: "-180,-90,180,90",
level: 18,
queryType: 4,
start: 0,
count: 10
}),
type: "query",
tk: "你的API密钥"
});

// 逆地理编码
const geocodeResult = await getTDTSearchResultByGeocode({
postStr: JSON.stringify({
lon: 118.5546748,
lat: 31.6976106,
ver: 1
}),
type: "geocode",
tk: "你的API密钥"
});
`

环境变量配置

在 .env 中配置默认设置:

`env


天地图 API Key

VITE_TDT_MAP_KEY = ''

谷歌地图 API Key

VITE_GOOGLE_MAP_KEY = ''

默认底图: 'tdt' | 'google' | 'osm'

VITE_MAP_BASE_LAYER = 'tdt'

默认搜索引擎: 'tdt' | 'google' | 'osm'

VITE_MAP_SEARCH_ENGINE = 'tdt'

根据底图自动切换搜索引擎

VITE_MAP_SEARCH_ENGINE_AUTO = 'false'
`

获取 API 密钥

$3

1. 访问 天地图开放平台
2. 注册并登录
3. 进入"应用管理"创建新应用
4. 复制生成的 API Key

$3

1. 访问 Google Cloud Console
2. 创建新项目或选择现有项目
3. 启用 Maps JavaScript API
4. 创建凭据并获取 API Key

示例

查看 example 目录了解更多使用示例。

运行示例项目:

`bash
cd example
npm install
npm run dev
``

更新日志

详见 CHANGELOG.md

浏览器支持

- Chrome (最新版)
- Firefox (最新版)
- Safari (最新版)
- Edge (最新版)

开源协议

MIT

贡献

欢迎贡献代码! 详情请阅读我们的贡献指南。

支持

- 📧 邮箱: chenyyz1015@gmail.com
- 🐛 问题: GitHub Issues
- 💬 讨论: GitHub Discussions