Map8 台灣圖霸 | `map8-js-route` 說明文件

Map8Route
- route
- getOrigin
- setOrigin
- getDestination
- setDestination
- reverse
- addWaypoint
- setWaypoint
- removeWaypoint
- getWaypoints
- removeRoutes
- on

Map8Route

Map8Route 控制元件 :

使用 Map8 API SDK Client for Javascript (gomp-web-service-js-client) 呼叫 Map8 Routes / Directions API.
接受 origin, destination, waypoints (並可傳入 style 以自訂) 等參數，就能直接為您在地圖上把路徑畫出來，很方便

Parameters

options Object
- options.styles Array 自訂路徑規劃的繪製樣式。請參照本頁右欄最后 自訂map8-js-route-styles樣式之範例 所示之 JSON 物件結構。。本參數若未被指定，則採用 Map8 之系統預設樣式。 (optional, default [])
- options.gompWebServiceJsClient Object Map8 API SDK Client 之 instance (i.e., 已經透過您所設定的 Map8 API key 初始化過的 GompWebServiceJsClient 物件實體)。本參數為必要。
- options.fitBoundsOptions Object 路徑規劃繪製出來時，本控制元件會對所連結的 gomp.Map 地圖物件，藉由操作 gomp.Map.fitBounds() 函式，將地圖的顯示範圍設定到以起訖點所形成之 bounding box。如果您不希望本元件自動控制地圖的顯示而想自行設定，請將本參數設定為 null。此外，本控制元件設定顯示範圍時，將以系統預設之動畫效果來做為過場 -- 若您希望自定過場的動畫效果，請將相關參數定義於本物件內 (請參照 gomp.Map.fitBounds() 與 gomp.AnimationOptions 與 gomp.CameraOptions 之說明)。 (optional, default {padding:80})

Examples

gomp.accessToken = '<您的 key>';
var map = new gomp.Map({
    container: 'map',
    style: 'https://api.map8.zone/styles/go-life-maps-tw-style-std/style.json', 
    center: [121.548728, 25.03625],
    zoom: 16,
    pitch: 50,
    maxZoom: 19.99,
    maxBounds: [[105, 15], [138.45858, 33.4]],
    localIdeographFontFamily: "'Microsoft YaHei', 'MS Gothic', 'Hiragino Kaku Gothic Pro', sans-serif",
    hash: true,
    speedLoad: false
});

var gompWebServiceJsClient = new GompWebServiceJsClient({        // 實體化一 Map8 API SDK Client
    key: gomp.accessToken
});

var route = new Map8Route({                                      // 建立本 `Map8Route` 地圖控制元件
    gompWebServiceJsClient: gompWebServiceJsClient,
    styles: routeStyles,                                         // 使用自訂的樣式；請參考後述之 `map8-js-route-styles` 範例    
});
map.addControl(route);                                           // 將本 `Map8Route` 地圖控制元件連結到目標地圖上

map.on('load', () => {
    map8Route.on('route', () => console.log('`route` event fired'));    // 攔截 / 監聽本元件的 `route` 事件 
                                                                        // (請參見 `on()` method 的說明內詳列了各事件)

    map8Route.route({                                            // 目標地圖必須載入完成後始得使用本 `Map8Route` 控制元件
        origin: [121.579839,25.065064], 
        destination: [121.579343,25.068134], 
        waypoints: [
            [121.576499,25.068178]
        ],
        profile: "foot"
    });

    console.log(map8Route.getOrigin());                          // 回傳起始點
    console.log(map8Route.getDestinations());                    // 回傳目的地
    console.log(map8Route.getWaypoints());                       // 回傳中途點 (陣列)

    map8Route.removeRoutes();                                    // 清除規劃的路徑、起訖點與中途點。
});

Returns Map8Route 本控制元件本身 (物件實體)

route

執行路徑規劃並直接在地圖上繪製路線 (於本 Map8Route 控制元件所連結之 gomp.Map 地圖物件上，以 constructor 內所指定的樣式來繪製)。

Parameters

options Object
- options.profile String 用以路徑規劃的交通工具。可為 car (汽車)、bicycle (自行車)、或 foot (步行)。此參數將用為呼叫 Map8 Routes / Directions API 說明文件之 <交通工具> 參數。本參數若未指定，則預設為car`。 (optional, default "car")
- options.origin Array 為起點之地理座標。格式是兩元素分別為 <經度>、<緯度> 之陣列。(請注意，座標格式是 <經度>,<緯度>，而非 <緯度>,<經度>)。
- options.destination Array 為目的地之地理座標。格式同上。
- options.waypoints Array 為一陣列，元素可為多個，而每個元素即代表一個中途點之地理座標 (每個元素之格式亦同上)。路徑規劃結果將從起點起，依此參數內各元素的次序，經過各中途點，乃至目的地為止。
- options.fitBoundsOptions Object? 路徑規劃繪製時的過場效果 (請參照本類別之建構子的說明)。此參數若未給，則上一回所設定的過場效果會被沿用 (包括透過建構子所給定者)。若有給，除指定方式同本類別之建構子的說明外，後續若未指定路徑規劃繪製時的過場效果，則將沿用本次的設定。

Returns Map8Route 本控制元件本身 (物件實體)

getOrigin

取得控制元件目前路徑的起始點。

Returns Object 起始點 (origin)

setOrigin

重新設定控制元件的起始點。

Parameters

query Array<Number> 為一陣列，格式為 [經度, 緯度]

Returns Map8Route 本控制元件本身 (物件實體)

getDestination

取得控制元件目前路徑之目的地。

Returns Object 目的地 (destination)

setDestination

重新設定控制元件之目的地。

Parameters

query Array<Number> 為一陣列，格式為 [經度, 緯度]

Returns Map8Route 本控制元件本身 (物件實體)

reverse

將控制元件的起始點與目的地對調。

Returns Map8Route 本控制元件本身 (物件實體)

addWaypoint

新增一中途點。

Parameters

index Number 新中途點所欲新增的位置 (也就是順序 -- 於 waypoints 陣列內的位置。位置從零起算)。
waypoint (Array<Number> | Point) 新中途點之座標。格式可為一 [經度, 緯度] 之陣列，或一 Point Feature 形式的 GeoJSON 物件。

Returns Map8Route 本控制元件本身 (物件實體)

setWaypoint

變更目前路徑中的某一中途點之座標。

Parameters

index Number 指明於 waypoints 陣列內的位置所代表的中途點 (位置從零起算)。
waypoint (Array<Number> | Point) 上述中途點所欲變更之座標。格式可為一 [經度, 緯度] 之陣列，或一 Point Feature 形式的 GeoJSON 物件。

Returns Map8Route 本控制元件本身 (物件實體)

removeWaypoint

移除目前路徑中的某一中途點。

Parameters

index Number 指明於 waypoints 陣列內的位置所代表的中途點 (位置從零起算)。

Returns Map8Route 本控制元件本身 (物件實體)

getWaypoints

取得目前路徑之全部中途點 (即 waypoints 陣列)。

Returns Array waypoints 陣列

removeRoutes

移除規劃的路徑、起訖點與中途點。

Returns Map8Route 本控制元件本身 (物件實體)

on

訂閱 / 監聽本控制元件發出的相關事件。

事件的名稱，與傳入之事件資料可為 :

事件名稱	傳入之事件資料	說明
clear	type	被移除之起始點 `origin` 或是目的地 `destination`
loading	type	被載入之起始點 `origin` 或是目的地 `destination`
profile	profile	被設定的交通工具。可為 `car` (汽車)、`bicycle` (自行車)、或 `foot` (步行)
origin	feature	當起始點被設定時觸發。傳入起始點 `origin`
destination	feature	當目的地被設定時觸發。傳入目的地 `destination`
route	route	當路徑被更新時觸發。傳入所規劃的路徑
error	error	當發生錯誤時觸發。傳入錯誤訊息 (為一字串)

Parameters

type String 事件的名稱。
fn Function 事件觸發時，將呼叫此 functin fn (並依照上表，傳入相關的事件資料物件)。

Returns Map8Route 本控制元件本身 (物件實體)

Examples

// 自訂 `map8-js-route-styles` 樣式之範例
var routeStyles = [{
    'id': 'directions-route-line-alt',
    'type': 'line',
    'source': 'directions',
    'layout': {
        'line-cap': 'round',
        'line-join': 'round'
    },
    'paint': {
        'line-color': '#ccc',
        'line-width': 5
    },
    'filter': [
        'all',
        ['in', '$type', 'LineString'],
        ['in', 'route', 'alternate']
    ]
}, 
{
    'id': 'directions-route-line-casing',
    'type': 'line',
    'source': 'directions',
    'layout': {
        'line-cap': 'round',
        'line-join': 'round'
    },
    'paint': {
        'line-color': '#111',
        "line-width": 8
    },
    'filter': [
        'all',
        ['in', '$type', 'LineString'],
        ['in', 'route', 'selected']
    ]
}, 
{
    'id': 'directions-route-line',
    'type': 'line',
    'source': 'directions',
    'layout': {
        'line-cap': 'butt',
        'line-join': 'round'
    },
    'paint': {
        'line-color': {
            'property': 'congestion',
            'type': 'categorical',
            'default': '#020d9e',
            'stops': [
                ['unknown', '#020d9e'],
                ['low', '#020d9e'],
                ['moderate', '#f09a46'],
                ['heavy', '#e34341'],
                ['severe', '#8b2342']
            ]
        },
        'line-width': 7
    },
    'filter': [
        'all',
        ['in', '$type', 'LineString'],
        ['in', 'route', 'selected']
    ]
}, 
{
    'id': 'directions-hover-point-casing',
    'type': 'circle',
    'source': 'directions',
    'paint': {
        'circle-radius': 8,
        'circle-color': '#bdbd3c'
    },
    'filter': [
        'all',
        ['in', '$type', 'Point'],
        ['in', 'id', 'hover']
    ]
}, 
{
    'id': 'directions-hover-point',
    'type': 'circle',
    'source': 'directions',
    'paint': {
        'circle-radius': 6,
        'circle-color': '#fffe54'
    },
    'filter': [
        'all',
        ['in', '$type', 'Point'],
        ['in', 'id', 'hover']
    ]
}, 
{
    'id': 'directions-waypoint-point-casing',
    'type': 'circle',
    'source': 'directions',
    'paint': {
        'circle-radius': 23,
        'circle-color': '#bdbd3c'
    },
    'filter': [
        'all',
        ['in', '$type', 'Point'],
        ['in', 'id', 'waypoint']
    ]
}, 
{
    'id': 'directions-waypoint-point',
    'type': 'circle',
    'source': 'directions',
    'paint': {
        'circle-radius':21,
        'circle-color': '#fffe54'
    },
    'filter': [
        'all',
        ['in', '$type', 'Point'],
        ['in', 'id', 'waypoint']
    ]
},
{
    'id': 'directions-waypoint-label',
    'type': 'symbol',
    'source': 'directions',
    'layout': {
        'text-field': '中途點',
        'text-font': ['Noto Sans Bold'],
        'text-size': 12
    },
    'paint': {
        'text-color': '#333'
    },
    'filter': [
        'all',
        ['in', '$type', 'Point'],
        ['in', 'id', 'waypoint']
    ]
}, 
{
    'id': 'directions-origin-point',
    'type': 'circle',
    'source': 'directions',
    'paint': {
        'circle-radius': 18,
        'circle-color': '#3bb2d0'
    },
    'filter': [
        'all',
        ['in', '$type', 'Point'],
        ['in', 'marker-symbol', 'O']
    ]
}, 
{
    'id': 'directions-origin-label',
    'type': 'symbol',
    'source': 'directions',
    'layout': {
        'text-field': '起點',
        'text-font': ['Noto Sans Bold'],
        'text-size': 12
    },
    'paint': {
        'text-color': '#fff'
    },
    'filter': [
        'all',
        ['in', '$type', 'Point'],
        ['in', 'marker-symbol', 'O']
    ]
}, 
{
    'id': 'directions-destination-point',
    'type': 'circle',
    'source': 'directions',
    'paint': {
        'circle-radius': 22,
        'circle-color': '#8a8bc9'
    },
    'filter': [
        'all',
        ['in', '$type', 'Point'],
        ['in', 'marker-symbol', 'D']
    ]
}, 
{
    'id': 'directions-destination-label',
    'type': 'symbol',
    'source': 'directions',
    'layout': {
        'text-field': '目的地',
        'text-font': ['Noto Sans Bold'],
        'text-size': 12
    },
    'paint': {
        'text-color': '#fff'
    },
    'filter': [
        'all',
        ['in', '$type', 'Point'],
        ['in', 'marker-symbol', 'D']
    ]
}];

Table of Contents

Map8Route

route

getOrigin

setOrigin

getDestination

setDestination

reverse

addWaypoint

setWaypoint

removeWaypoint

getWaypoints

removeRoutes

on