# map

基礎(chǔ)庫(kù) 1.0.0 開(kāi)始支持，低版本需做兼容處理。

微信 Windows 版：支持

微信 Mac 版：支持

微信 鴻蒙 OS 版：支持

相關(guān)文檔: wx.createMapContext

渲染框架支持情況：Skyline （使用最新 Nightly 工具調(diào)試）、WebView

# 功能描述

地圖 v2.7.0 起支持同層渲染。

map組件提供了地圖展示、交互、疊加點(diǎn)線面及文字等功能，同時(shí)支持個(gè)性化地圖樣式，可結(jié)合地圖服務(wù) API 實(shí)現(xiàn)更豐富功能。

為了更好的提供地圖服務(wù)，請(qǐng)?jiān)谡{(diào)用 map 組件之前，先前往騰訊位置服務(wù)官網(wǎng)注冊(cè)一個(gè)專屬 KEY,在地圖開(kāi)發(fā)過(guò)程中，可以將這個(gè)專屬 KEY 通過(guò) subkey 參數(shù)傳入；后續(xù)如遇到地圖開(kāi)發(fā)問(wèn)題也可以在騰訊位置服務(wù)官網(wǎng)工單系統(tǒng)提交工單反饋解決；

# 地圖個(gè)性化樣式組件

地圖個(gè)性化樣式組件是騰訊位置服務(wù)為開(kāi)發(fā)者提供的地圖高級(jí)能力，開(kāi)發(fā)者可以在法律允許的范圍內(nèi)定制地圖風(fēng)格，支持定制背景面、背景線、道路、POI等地圖元素顏色、顯示層級(jí)等內(nèi)容；支持按照類型精細(xì)化管理POI的顯示、隱藏；靈活地設(shè)計(jì)貼合業(yè)務(wù)場(chǎng)景的心儀地圖。

購(gòu)買(mǎi)該能力后，您可以在 MP平臺(tái)「管理->付費(fèi)管理->概覽->地圖個(gè)性化樣式->去使用」中創(chuàng)建配置您的地圖個(gè)性化樣式，您可以選擇我們提供的基礎(chǔ)及高級(jí)模版，也可以通過(guò)在線編輯平臺(tái)，對(duì)多種地圖元素的樣式進(jìn)行自定義設(shè)置，以滿足在不同場(chǎng)景下的個(gè)性化需求。

注意：

1. 自2023年6月29日0點(diǎn)起，該能力需要先購(gòu)買(mǎi)再使用。若未購(gòu)買(mǎi)，屆時(shí)將無(wú)法使用該能力。具體購(gòu)買(mǎi)方式見(jiàn) 付費(fèi)管理。
2. 自2023年6月29日0時(shí)起，個(gè)性化地圖配置界面的入口統(tǒng)一為微信公眾平臺(tái)-付費(fèi)管理，請(qǐng)從此入口進(jìn)入，騰訊位置服務(wù)官網(wǎng)入口不再使用。已經(jīng)在小程序生效的個(gè)性化樣式配置，將于2023年6月29日0時(shí)變更為默認(rèn)樣式，如有個(gè)性化樣式配置需求，請(qǐng)于6月29日0時(shí)前，前往微信公眾平臺(tái)-付費(fèi)管理進(jìn)行相關(guān)能力的開(kāi)通和配置。

# 地圖服務(wù)API

地圖服務(wù)API 與map組件基于同一套數(shù)據(jù)體系，無(wú)縫貼合，疊加使用可實(shí)現(xiàn)更豐富的功能。 提供：地點(diǎn)搜索、關(guān)鍵詞輸入提示、正/逆地址解析（經(jīng)緯度與地址互轉(zhuǎn)）駕車與步行路線規(guī)劃等功能。

詳情見(jiàn)：地圖服務(wù)API在小程序中的使用方法

若開(kāi)發(fā)者使用通過(guò)LBS開(kāi)放平臺(tái)自行申請(qǐng)的服務(wù)賬號(hào)，在小程序連接并調(diào)用位置服務(wù)產(chǎn)品用于商業(yè)行為（政府公共事務(wù)及公益組織事務(wù)除外），騰訊位置服務(wù)有權(quán)收取商業(yè)授權(quán)費(fèi)，詳細(xì)內(nèi)容可以查看或咨詢騰訊微位置服務(wù)官網(wǎng)

# 深入控制地圖

通過(guò)微信小程序API中wx.createMapContext方法，創(chuàng)建 map 上下文 MapContext 對(duì)象，通過(guò)其實(shí)現(xiàn)更細(xì)粒度的地圖交互和功能，包括：控制地圖視野、獲取地圖位置與視角等信息、marker移動(dòng)（軌跡回放）、動(dòng)態(tài)創(chuàng)建個(gè)性化圖層、拉起地圖APP選擇導(dǎo)航等

# 小程序插件

現(xiàn)成插件簡(jiǎn)單接入，提供：路線規(guī)劃、地圖選點(diǎn)、城市選擇器、地鐵圖 常用功能。

詳情見(jiàn)：小程序地圖插件使用指南

# 開(kāi)源示例中心

包含Map組件、服務(wù)API、插件等功能使用方法，全面了解小程序下的所有地圖能力。示例內(nèi)容源碼開(kāi)放，降低各位開(kāi)發(fā)者接入成本。

# 地圖基礎(chǔ)屬性

# 屬性說(shuō)明

# regionchange 返回值

視野改變時(shí)，regionchange 會(huì)觸發(fā)兩次，返回的 type 值分別為 begin 和 end。

2.8.0 起 begin 階段返回 causedBy，有效值為 gesture（手勢(shì)觸發(fā)） & update（接口觸發(fā)）

2.3.0 起 end 階段返回 causedBy，有效值為 drag（拖動(dòng)導(dǎo)致）、scale（縮放導(dǎo)致）、update（調(diào)用更新接口導(dǎo)致）。

e = {causedBy, type, detail: {rotate, skew, scale, centerLocation, region}}

# setting

提供 setting 對(duì)象統(tǒng)一設(shè)置地圖配置。同時(shí)對(duì)于一些動(dòng)畫(huà)屬性如 rotate 和 skew，通過(guò) setData 分開(kāi)設(shè)置時(shí)無(wú)法同時(shí)生效，需通過(guò) settting 統(tǒng)一修改。

// 默認(rèn)值
const setting = {
  skew: 0,
  rotate: 0,
  showLocation: false,
  showScale: false,
  subKey: '',
  layerStyle: 1,
  enableZoom: true,
  enableScroll: true,
  enableRotate: false,
  showCompass: false,
  enable3D: false,
  enableOverlooking: false,
  enableSatellite: false,
  enableTraffic: false,
}

this.setData({
  // 僅設(shè)置的屬性會(huì)生效，其它的不受影響
  setting: {
    enable3D: true,
    enableTraffic: true
  }
})

# marker

標(biāo)記點(diǎn)用于在地圖上顯示標(biāo)記的位置。

注：可結(jié)合地圖服務(wù)API - 地點(diǎn)搜索 實(shí)現(xiàn)地圖搜索功能。

# marker 碰撞關(guān)系

在一定范圍內(nèi)繪制多個(gè) Marker 時(shí)，常會(huì)出現(xiàn) Marker 壓蓋的情況，3.4.3 起支持設(shè)置碰撞關(guān)系。

# 碰撞目標(biāo)

默認(rèn) Marker 不參與碰撞，collision 用于設(shè)置是否參與碰撞，支持枚舉值 poi、marker，多類型時(shí)按 "," 分割。 poi: 和 poi 點(diǎn)碰撞后隱藏 poi marker: 和 marker 碰撞后隱藏自己或被碰的 marker

發(fā)送碰撞時(shí)，按 zIndex 區(qū)分優(yōu)先級(jí)，優(yōu)先級(jí)低的將會(huì)被隱藏。

例如 collision 設(shè)置為 poi,marker，表示與 poi 和 marker 均會(huì)參與碰撞。

# 整體碰撞或區(qū)域碰撞

Marker 的各個(gè)部分，包括 iconPath、callout、label 等，可以作為一個(gè)整體參與碰撞，也可獨(dú)立開(kāi)來(lái)。

collision-relation 屬性支持 alone 和 together 兩種值。 together: 作為整體參與碰撞后隱藏，此時(shí)忽略各部件 callout 和 label 的 collision 屬性。 alone：獨(dú)立參與碰撞后隱藏，此時(shí)各部件 callout 和 label 可單獨(dú)設(shè)置 collision 屬性，未填寫(xiě)時(shí)則與主 Marker 保持一致。

# marker 上的氣泡 callout

# marker 上的自定義氣泡 customCallout

customCallout 存在時(shí)將忽略 callout 與 title 屬性。自定義氣泡采用 cover-view 定制，靈活度更高。

使用方式如下，map 組件下添加名為 callout 的 slot 節(jié)點(diǎn)，其內(nèi)部的 cover-view 通過(guò) marker-id 屬性與 marker 綁定。當(dāng) marker 創(chuàng)建時(shí)，該 cover-view 顯示的內(nèi)容將作為 callout 顯示在標(biāo)記點(diǎn)上方。

<map>
  <cover-view slot="callout">
    <cover-view marker-id="1"></cover-view>
    <cover-view marker-id="2"></cover-view>
  </cover-view>
</map>

示例DEMO： https://developers.weixin.qq.com/s/cZWIojm47pjN

# marker 上的氣泡 label

# 點(diǎn)聚合

當(dāng)?shù)貓D上需要展示的標(biāo)記點(diǎn) marker 過(guò)多時(shí)，可能會(huì)導(dǎo)致界面上 marker 出現(xiàn)壓蓋，展示不全，并導(dǎo)致整體性能變差。針對(duì)此類問(wèn)題，推出點(diǎn)聚合能力。

使用流程如下：

1. MapContext.initMarkerCluster 對(duì)聚合點(diǎn)進(jìn)行初始化配置（可選）；
2. MapContext.addMarkers 指定參與聚合的 marker；
3. MapContext.on('markerClusterCreate', callback) 觸發(fā)時(shí)，通過(guò) MapContext.addMarkers 更新聚合簇的樣式 （可選）；
4. MapContext.removeMarkers 移除參與聚合的 marker；

# 示例代碼

在開(kāi)發(fā)者工具中預(yù)覽效果

需注意的是：

1. 地圖上的 marker 分為普通的 marker 與參與聚合的 marker，參與聚合時(shí)需指定屬性 joinCluster 為 true；
2. 自定義聚合簇樣式時(shí)，同樣通過(guò) MapContext.addMarkers 進(jìn)行繪制，此時(shí)需攜帶 clusterId。

# polyline

指定一系列坐標(biāo)點(diǎn)，從數(shù)組第一項(xiàng)連線至最后一項(xiàng)。繪制彩虹線時(shí)，需指定不同分段的顏色，如 points 包含 5 個(gè)點(diǎn)，則 colorList 應(yīng)傳入 4 個(gè)顏色值；若 colorList 長(zhǎng)度小于 points.length - 1，則剩下的分段顏色與最后一項(xiàng)保持一致。

注：可結(jié)合 地圖服務(wù)API - 駕車路線規(guī)劃，實(shí)現(xiàn)路線計(jì)算與展示。

注：textStyle 與 segmentTexts 結(jié)合可在折線線段上面繪制文字，用來(lái)顯示路名。

# SegmentText

# TextStyle

level 字段表示與其它地圖元素的壓蓋關(guān)系，可選值如下：

# polygon

指定一系列坐標(biāo)點(diǎn)，根據(jù) points 坐標(biāo)數(shù)據(jù)生成閉合多邊形

# circle

在地圖上顯示圓

# control

在地圖上顯示控件，控件不隨著地圖移動(dòng)。即將廢棄，請(qǐng)使用 cover-view

# position

# bindregionchange 返回值

# 比例尺

# bindabilitysuccess、bindabilityfail 和 binderror 的返回值

bindabilitysuccess 和 bindabilityfail 事件具有額外的參數(shù) ability 來(lái)指示是何種地圖能力，可能的取值有: layer-style。

共同參數(shù)如下 errCode 的定義如下：

# 示例代碼

在開(kāi)發(fā)者工具中預(yù)覽效果

# Bug & Tip

1. tip：個(gè)性化地圖暫不支持工具中調(diào)試。請(qǐng)先使用微信客戶端進(jìn)行測(cè)試。
2. tip：地圖中的顏色值color/borderColor/bgColor等需使用6位（8位）十六進(jìn)制表示，8位時(shí)后兩位表示alpha值，如：#000000AA
3. tip：地圖組件的經(jīng)緯度必填, 如果不填經(jīng)緯度則默認(rèn)值是北京的經(jīng)緯度。
4. tip: map 組件使用的經(jīng)緯度是火星坐標(biāo)系，調(diào)用 wx.getLocation 接口需要指定 type 為 gcj02
5. tip：從 2.8.0 起 map 支持同層渲染，更多請(qǐng)參考原生組件使用限制
6. tip：請(qǐng)注意原生組件使用限制。
7. tip: 若當(dāng)前組件所在的頁(yè)面或全局開(kāi)啟了 enablePassiveEvent 配置項(xiàng)，該內(nèi)置組件可能會(huì)出現(xiàn)非預(yù)期表現(xiàn)（詳情參考 enablePassiveEvent 文檔）