Vue3 + OpenLayers(OL) 加载天地图超详细教程（新手友好｜可直接复制运行）

Vue3 OpenLayers(OL) 加载天地图超详细教程新手友好可直接复制运行在Vue3项目中做地图开发天地图是国内合规、免费、稳定的首选地图源而OpenLayers简称OL是功能强大的开源地图库——两者结合既能享受天地图的合规性又能借助OL轻松实现遮罩、省份高亮、标记点等复杂功能比天地图原生API更灵活、更好用。本文从「天地图Key申请」开始一步步教你完成Vue3 OL加载天地图全程带代码、带截图示意图、避坑指南新手也能一次成功复制代码就能直接运行一、前置准备申请天地图Key必做天地图所有接口都需要Key也称TK才能调用申请完全免费步骤简单全程1分钟搞定。1. 进入天地图云中心打开天地图云中心官网https://cloudcenter.tianditu.gov.cn/示意图可自行截图补充进入后点击右上角「登录/注册」没有账号的话用手机号注册即可实名认证免费仅用于合规校验不收费。2. 创建应用获取Key登录后点击顶部导航「开发管理 → 应用管理」再点击「创建应用」填写应用信息应用名称随便填如「Vue3OL天地图测试」应用类型必须选「浏览器端」重点选其他类型会导致调用失败备注可选填方便后续管理点击「创建」创建成功后就能看到你的「KeyTK」复制保存好后续会用到。避坑提醒创建应用后可点击「设置」配置「域名白名单」本地开发可填localhost线上项目填实际域名避免跨域或调用失败。二、项目准备Vue3 Vite 环境搭建已有项目可跳过本文基于Vue3 Vite开发主流组合如果已有Vue3项目直接跳过这一步如果没有先快速搭建环境# 1. 创建Vue3项目Vitenpmcreate vitelatest vue3-ol-tianditu ----templatevue# 2. 进入项目目录cdvue3-ol-tianditu# 3. 安装依赖npminstall# 4. 启动项目npmrun dev三、核心步骤安装OpenLayersOLOpenLayers是开源地图库需要通过npm安装命令如下项目根目录执行npminstallol安装完成后无需额外配置直接在组件中引入即可Vite会自动处理依赖。四、完整实现Vue3 OL 加载天地图新建地图组件推荐新建 components/TiandituMap.vue复制下面代码只需替换自己的天地图Key就能直接运行每一步都有详细注释新手也能看懂。1. 组件完整代码可直接复制templategt!-- 地图容器必须设置宽高否则地图无法显示 --divrefmapContainerclassmap-container/div/templatescriptsetup// 引入Vue3核心钩子import{ref,onMounted,onUnmounted}fromvue// 引入OpenLayers核心模块importMapfromol/MapimportViewfromol/ViewimportTileLayerfromol/layer/Tile// 瓦片图层加载天地图核心importXYZfromol/source/XYZ// XYZ数据源适配天地图瓦片格式import{fromLonLat}fromol/proj// 坐标转换天地图经纬度转OL坐标// 地图容器DOM引用constmapContainerref(null)// 地图实例全局保存方便后续操作letmapnull// 替换成你自己的天地图Key重点constTIANDITU_KEY你的天地图Key// 组件挂载后初始化地图必须在DOM渲染完成后执行onMounted((){initMap()})// 初始化地图核心函数functioninitMap(){// 1. 加载天地图矢量底图最常用可切换成影像图、地形图consttiandituVecLayernewTileLayer({source:newXYZ({// 天地图矢量底图瓦片地址球面墨卡托投影适配OLurl:https://t{0-7}.tianditu.gov.cn/vec_w/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERvecSTYLEdefaultTILEMATRIXSETwFORMATtilesTILECOL{x}TILEROW{y}TILEMATRIX{z}tk${TIANDITU_KEY},// 天地图二级域名t0-t7随机切换避免单域名限流tileLoadFunction:(tile,url){tile.setSrc(url.replace({0-7},Math.floor(Math.random()*8)))}})})// 2. 加载天地图注记层文字、道路名称、地名必须单独加载否则底图没有文字consttiandituLabelLayernewTileLayer({source:newXYZ({url:https://t{0-7}.tianditu.gov.cn/cva_w/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERcvaSTYLEdefaultTILEMATRIXSETwFORMATtilesTILECOL{x}TILEROW{y}TILEMATRIX{z}tk${TIANDITU_KEY},tileLoadFunction:(tile,url){tile.setSrc(url.replace({0-7},Math.floor(Math.random()*8)))}})})// 3. 创建地图实例mapnewMap({target:mapContainer.value,// 挂载到DOM容器layers:[tiandituVecLayer,tiandituLabelLayer],// 加载底图 注记层顺序不能乱view:newView({center:fromLonLat([106.5,33]),// 地图中心点中国地理中心经纬度zoom:4,// 初始缩放级别3-18可调数字越大越清晰minZoom:3,// 最小缩放级别避免缩太小看到国外maxZoom:18,// 最大缩放级别天地图最大支持18级projection:EPSG:3857// 球面墨卡托投影OL默认适配天地图})})}// 组件销毁时销毁地图实例避免内存泄漏onUnmounted((){if(map){map.setTarget(null)// 解除地图与DOM的绑定mapnull// 清空实例}})/scriptstylescoped/* 地图容器必须设置宽高否则无法显示 */.map-container{width:100%;height:80vh;/* 占视口高度80%可自行调整 */}/style2. 组件使用在页面中引入在App.vue中引入上面创建的地图组件即可在页面中显示天地图templatedivclassapph1Vue3 OL 加载天地图/h1TiandituMap//div/templatescriptsetupimportTiandituMapfrom./components/TiandituMap.vue/scriptstyle.app{padding:20px;}/style3. 运行效果执行npm run dev启动项目打开浏览器就能看到天地图矢量底图正常显示带有地名、道路文字支持鼠标滚轮缩放、拖拽地图默认显示中国全貌缩放后能看到详细的省市、道路。示意图可自行截图补充页面顶部标题 下方完整天地图可正常操作。五、扩展功能切换天地图图层矢量/影像/地形天地图支持多种图层类型只需修改瓦片地址中的「图层标识」就能切换不同风格的地图以下是常用图层配置直接替换代码中的底图和注记地址即可图层类型底图瓦片地址替换vec_w注记瓦片地址替换cva_w矢量底图默认vec_wcva_w卫星影像图img_wcia_w地形晕渲图ter_wcta_w示例切换为卫星影像图// 卫星影像底图consttiandituVecLayernewTileLayer({source:newXYZ({url:https://t{0-7}.tianditu.gov.cn/img_w/wmts?xxxtk${TIANDITU_KEY},// 替换vec_w为img_wtileLoadFunction:(tile,url){tile.setSrc(url.replace({0-7},Math.floor(Math.random()*8)))}})})// 卫星影像注记consttiandituLabelLayernewTileLayer({source:newXYZ({url:https://t{0-7}.tianditu.gov.cn/cia_w/wmts?xxxtk${TIANDITU_KEY},// 替换cva_w为cia_wtileLoadFunction:(tile,url){tile.setSrc(url.replace({0-7},Math.floor(Math.random()*8)))}})})六、常见问题避坑指南新手必看很多新手加载失败都是踩了以下坑提前规避一次成功1. 地图空白不显示任何内容原因1天地图Key错误或应用类型不是「浏览器端」原因2地图容器没有设置宽高必须给.map-container设置width和height解决检查Key是否正确、应用类型确认容器宽高设置。2. 底图显示但没有文字地名、道路原因只加载了底图图层没有加载注记图层cva_w/cia_w解决必须同时加载「底图图层 注记图层」顺序不能乱底图在前注记在后。3. 控制台报错「跨域」原因没有配置域名白名单天地图限制了非法域名调用解决进入天地图云中心 → 应用管理 → 对应应用 → 设置 → 添加域名白名单本地开发填localhost线上填实际域名。4. 地图加载缓慢、卡顿原因没有使用随机二级域名t0-t7单域名限流解决保留代码中的tileLoadFunction实现随机切换二级域名提升加载速度。七、进阶功能预告后续可扩展基于本文的基础配置还能轻松实现以下常用功能适合后续扩展只显示中国地图添加遮罩隐藏国外区域加载省份边界GeoJSON实现点击省份高亮添加标记点、弹窗、轨迹线限制地图拖动范围禁止拖出中国实现地理编码地址转经纬度、POI搜索。八、总结Vue3 OpenLayers 加载天地图的核心流程申请天地图Key → 安装OL → 动态加载天地图瓦片 → 初始化地图全程没有复杂配置复制代码就能运行。相比天地图原生APIOL的优势在于功能更强大后续扩展省份高亮、遮罩等功能更简单而且完全免费、开源适合Vue3前端地图开发的各种场景个人项目、企业项目都适用。如果觉得本文有用欢迎收藏、转发后续会更新进阶功能教程帮助大家快速实现复杂地图需求注文档部分内容可能由 AI 生成