Overlay 從名字看,是覆蓋圖、覆蓋物的意思,主要的用途就是在地圖之上再覆蓋一層,用以顯示額外的可見元素,可見元素一般是 HTML 元素,利用 overlay,可以將可見元素放置到地圖的任意位置,形成地圖上再浮動一層的效果。例如在地圖上相應的坐標放置一個標志,標簽,利用 overlay 都可以做到,具體來說,點擊地圖上某位置,在點擊位置彈出彈出框就是利用了 overlay。
初始化屬性
overlay 初始化時可以接受很多的配置參數,這些配置參數是一個個的鍵值對,共同構成一個對象字面量(options),然后傳遞給其“構造函數”,如 `new ol.Overlay(options),此處的 options 便是參數鍵值對構成的對象字面量。可配置的鍵值對,定義如下:
/** * Object literal with config options for the overlay. * @typedef {{id: (number|string|undefined), * element: (Element|undefined), * offset: (Array.<number>|undefined), * position: (ol.Coordinate|undefined), * positioning: (ol.OverlayPositioning|string|undefined), * stopEvent: (boolean|undefined), * insertFirst: (boolean|undefined), * autoPan: (boolean|undefined), * autoPanAnimation: (olx.animation.PanOptions|undefined), * autoPanMargin: (number|undefined)}} * @api stable */ olx.OverlayOptions;
其含義分別如下:
- id,為對應的 overlay 設置一個 id,便於使用
ol.Map
的getOverlayById
方法取得相應的 overlay; - element,overlay 包含的 DOM element;
- offset,偏移量,像素為單位,overlay 相對於放置位置(position)的偏移量,默認值是 [0, 0],正值分別向右和向下偏移;
- position,在地圖所在的坐標系框架下,overlay 放置的位置;
- positioning,overlay 對於 position 的相對位置,可能的值包括
bottom-left
、bottom-center
、bottom-right
、center-left
、center-center
、center-right
、top-left
、top-center
、top-right
,默認是top-left
,也就是 element 左上角與 position 重合; - stopEvent,地圖的事件傳播是否停止,默認是
true
,即阻止傳播,可能不太好理解,舉個例子,當鼠標滾輪在地圖上滾動時,會觸發地圖縮放事件,如果在 overlay 之上滾動滾輪,並不會觸發縮放事件,如果想鼠標在 overlay 之上也支持縮放,那么將該屬性設置為false
即可; - insertFirst,overlay 是否應該先添加到其所在的容器(container),當 stopEvent 設置為 true 時,overlay 和 openlayers 的控件(controls)是放於一個容器的,此時將 insertFirst 設置為 true ,overlay 會首先添加到容器,這樣,overlay 默認在控件的下一層(CSS
z-index
),所以,當 stopEvent 和 insertFirst 都采用默認值時,overlay 默認在 控件的下一層; - autoPan,當觸發 overlay
setPosition
方法時觸發,當 overlay 超出地圖邊界時,地圖自動移動,以保證 overlay 全部可見; - autoPanAnimation,設置 autoPan 的效果動畫,參數類型是
olx.animation.panOptions
; - autoPanMargin,地圖自動平移時,地圖邊緣與 overlay 的留白(空隙),單位是像素,默認是 20像素;
支持的事件
支持的事件主要是繼承 ol.Object
而來的 change
事件,當 overlay 相關屬性或對象變化時觸發:
- change,當引用計數器增加時,觸發;
- change:element,overlay 對應的 element 變化時觸發;
- change:map,overlay 對應的 map 變化時觸發;
- change:offset,overlay 對應的 offset 變化時觸發;
- change:position,overlay 對應的 position 變化時觸發;
- change:positioning,overlay 對應的 positioning 變化時觸發;
- propertychange,overlay 對應的屬性變化時觸發;
那么怎么綁定相應的事件呢?openlayers 綁定事件遵循一般的 dom 事件綁定規則,包括 DOM 2 級事件綁定,以下是一個例子,這個例子說明了 overlay 的位置變化時在瀏覽器的控制台輸出字符串的例子。
// example overlay event binding
var overlay = new ol.Overlay({
// ... }); overlay.on("change:position", function(){ console.log("位置改變!"); })
方法
支持的方法這里我們只介紹 overlay 特有的方法,就不介紹其繼承而來的方法了,主要是針對 overlay 的屬性及其相關聯對象的 get 和 set 方法。
- getElement,取得包含 overlay 的 DOM 元素;
- getId,取得 overlay 的 id;
- getMap,獲取與 overlay 關聯的 map對象;
- getOffset,獲取 offset 屬性;
- getPosition,獲取 position 屬性;
- getPositioning,獲取 positioning 屬性;
- setElement;設置 overlay 的 element;
- setMap,設置與 overlay 的 map 對象;
- setOffset,設置 offset;
- setPosition,設置 position 屬性;
- setPositioning,設置 positioning 屬性。