如何使用映像範本

發行項
03/18/2024

影像可以搭配 Azure 地圖服務 Web SDK 內的 HTML 標記和各種圖層使用：

若地圖帶有影像圖示，符號圖層可以呈現地圖上的點。符號也可以沿著線條路徑呈現。
多邊形圖層可以透過填滿圖樣影像呈現。
HTML 標記可以使用影像和其他 HTML 元素來呈現點。

為了確保圖層有良好的效能，請先將影像載入地圖影像原件資源中再進行呈現。根據預設，SymbolLayer 的 IconOptions 會在地圖影像原件中預先載入幾個顏色的標記影像。這些標記影像和其他影像可做為 SVG 範本使用。它們可用來建立具有自訂尺規的影像，或做為客戶主要和次要顏色使用。總共提供 42 個影像範本：27 個符號圖示和 15 個多邊形填滿圖樣。

您可以使用 map.imageSprite.createFromTemplate 函式，將影像範本新增至地圖影像原件資源。此函式最多允許傳入五個參數；

createFromTemplate(id: string, templateName: string, color?: string, secondaryColor?: string, scale?: number): Promise<void>

id 是您建立的唯一識別碼。 id 影像新增至地圖影像原件時，系統會將它指派給影像。在圖層中使用這個標識符，指定要轉譯的影像資源。 templateName 會指定要使用的影像範本。 color 選項會設定影像的主要顏色，secondaryColor 選項則設定影像的次要顏色。 scale 選項會先縮放影像範本，再將它套用至影像原件。將映像套用至映射Sprite時，它會轉換成 PNG。為了確保清楚呈現，最好先放大影像範本再新增至原件，而不是在圖層中放大。

此函式會以非同步方式將影像載入影像原件中。因此會傳回 Promise，表示您可以等待此函式完成。

下列程式代碼示範如何從其中一個內建範本建立影像，然後將它與符號圖層搭配使用。

map.imageSprite.createFromTemplate('myTemplatedIcon', 'marker-flat', 'teal', '#fff').then(function () {

   //Add a symbol layer that uses the custom created icon.
   map.layers.add(new atlas.layer.SymbolLayer(datasource, null, {
      iconOptions: {
         image: 'myTemplatedIcon'
      }
   }));
});

搭配符號圖層使用影像範本

影像範本載入地圖影像原件中後，就可以參考 iconOptions 的 image 選項中的影像資源識別碼，將它呈現為符號圖層中的符號。

具有內建圖示範本的符號圖層範例示範如何使用具有主要色彩藍綠色和次要色彩白色的 marker-flat 影像範本來轉譯符號圖層，如下列螢幕擷取畫面所示。

如需此範例的原始程式碼，請參閱使用內建圖示範本程式碼的符號圖層。

沿著線條路徑使用影像範本

將影像範本載入地圖影像原件之後，即可將 LineString 新增至資料來源，並使用符號圖層搭配 lineSpacing 選項，參考 iconOptions 的 image 選項中的影像資源識別碼，沿著線條的路徑呈現。

使用內建圖示範本的線條圖層會示範如何執行這項操作。如下列螢幕擷取畫面所示，範例使用採用 car 影像範本並搭配主要顏色寶藍色和次要顏色白色的符號圖層，在地圖上呈現紅色線條。如需此範例的原始程式碼，請參閱使用內建圖示範本範例程式碼的線條圖層。

提示

如果影像範本向上指，若您想將符號圖層的圖示選項指向與線條相同的方向，請將符號圖層的圖示選項 rotation 設為 90。

搭配多邊形圖層使用影像範本

影像範本載入地圖影像原件中後，就可以參考 fillPattern 選項中的影像資源識別碼，將它呈現為多邊形圖層中的填滿圖樣。

使用內建圖示範本填滿多邊形範例示範如何使用具有主要色彩紅色和次要色彩透明色的 dot 影像範本來轉譯多邊形圖層，如下列螢幕擷取畫面所示。如需此範例的原始程式碼，請參閱使用內建圖示範本範例程式碼填滿圖層。

提示

設定填滿圖樣的次要顏色，可讓您更容易看到基礎地圖仍提供主要圖樣。

搭配 HTML 標記使用影像範本

您可以使用 altas.getImageTemplate 函式擷取影像範本，並做為 HTML 標記的內容。範本可以傳遞至標記的 htmlContent 選項，然後使用color、secondaryColor 和 text 選項加以自訂。

HTML 標記與內建圖示範本範例會示範使用具有主要色彩紅色、次要色彩粉紅色和文字值為 “00” 的 marker-arrow 範本，如下列螢幕擷取畫面所示。如需此範例的原始程式碼，請參閱使用內建圖示範本範例程式碼的 HTML 標記。

提示

影像範本也可用於地圖之外。 getImageTemplate 函式會傳回具有預留位置的 SVG 字串；{color}、{secondaryColor}、{scale}、{text}。取代這些預留位置值以建立有效的 SVG 字串。然後，您可以將 SVG 字串直接新增至 HTML DOM，或轉換成資料 URI 並插入影像標記中。例如：

//Retrieve an SVG template and replace the placeholder values.
var svg = atlas.getImageTemplate('marker').replace(/{color}/, 'red').replace(/{secondaryColor}/, 'white').replace(/{text}/, '').replace(/{scale}/, 1);

//Convert to data URI for use in image tags.
var dataUri = 'data:image/svg+xml;base64,' + btoa(svg);

建立自訂可重複使用的範本

如果應用程式使用相同的圖示搭配不同的模組，或您要建立新增更多影像範本的模組，您可以輕鬆從 Azure 地圖服務 Web SDK 新增和擷取這些圖示。在 atlas 命名空間上使用下列靜態函式。

名稱	傳回類型	描述
`addImageTemplate(templateName: string, template: string, override: boolean)`		將自訂 SVG 影像範本新增至圖集命名空間。
`getImageTemplate(templateName: string, scale?: number)`	string	依名稱擷取 SVG 範本。
`getAllImageTemplateNames()`	string[]	依名稱擷取 SVG 範本。

SVG 影像範本支援下列預留位置值：

預留位置	描述
`{color}`	主要顏色。
`{secondaryColor}`	次要顏色。
`{scale}`	SVG 影像新增至地圖影像原件時會轉換成 png 影像。此預留位置可用來在轉換範本之前縮放範本，確保能清楚呈現。
`{text}`	與 HTML 標記搭配使用時要呈現文字的位置。

如下列螢幕擷取畫面所示，將自訂圖示範本新增至 atlas 命名空間範例會示範如何取得 SVG 範本，並將其新增至 Azure 地圖服務 Web SDK 作為可重複使用的圖示範本。如需此範例的原始程式碼，請參閱將自訂圖示範本新增至 atlas 命名空間範例程式碼。

影像範本清單

下表列出 Azure 地圖服務 Web SDK 中目前可用的所有影像範本。範本名稱位於每個影像上方。根據預設，主要顏色為藍色，而次要顏色為白色。為了讓次要顏色在白色背景上更容易看到，下列影像會將次要顏色設定為黑色。

符號圖示範本

marker

標記-粗邊

標記-圓形

標記 - 平面

標記圖示

標記粗圖示

標記圓形圖示

marker-flat 圖示

標記-方形

標記-方形-叢集

標記-箭頭

標記-大頭針

標記方形圖示

marker-square-cluster 圖示

marker-ball-pin 圖示

標記-方形-圓角

標記-方形-圓角-叢集

旗標

旗標-三角形

marker-square-rounded 圖示

marker-square-rounded-cluster 圖示

三角形

三角形-粗邊

三角形-箭號-向上

三角形-箭號-向左

三角形圖示

三角形粗圖示

六邊形

六邊形 - 粗

六邊形-圓角

六邊形-圓角-粗邊

六邊形圖示

六邊形粗圖示

六邊形四捨五入圖示

hexagon-rounded-thick 圖示

圖釘-圓形

圓角-方形

圓角-方形-粗邊

釘選圖示

釘選圓形圖示

圓角方塊圖示

rounded-square-thick 圖示

箭頭-向上

箭頭-向上-窄

汽車

汽車圖示

多邊形填滿圖樣

方格

方格-轉向

圓形

圓形-間隔

檢查程序圖示

檢查程式旋轉圖示

圓形圖示

圓形間距圖示

對角-線條-向上

對角-線條-向下

對角-帶狀線-向上

對角-帶狀線-向下

對角線向上圖示

對角線向下圖示

對角線條紋向上圖示

對角線條紋向下圖示

格線-線條

轉向-格線-線條

轉向-格線-帶狀線

x-填滿

網格線圖示

rotated-grid-line 圖示

rotated-grid-stripes 圖示

x 填滿圖示

鋸齒

鋸齒-垂直

圓點

zig-zag 圖示

zig-zag-vertical 圖示

點圖示

預先載入的影像圖示

地圖會使用 marker、pin 和 pin-round 範本，預先將一組圖示預先載入地圖影像原件中。下表列出這些圖示的名稱及其色彩值。

圖示名稱	color	secondaryColor
`marker-black`	`#231f20`	`#ffffff`
`marker-blue`	`#1a73aa`	`#ffffff`
`marker-darkblue`	`#003963`	`#ffffff`
`marker-red`	`#ef4c4c`	`#ffffff`
`marker-yellow`	`#f2c851`	`#ffffff`
`pin-blue`	`#2072b8`	`#ffffff`
`pin-darkblue`	`#003963`	`#ffffff`
`pin-red`	`#ef4c4c`	`#ffffff`
`pin-round-blue`	`#2072b8`	`#ffffff`
`pin-round-darkblue`	`#003963`	`#ffffff`
`pin-round-red`	`#ef4c4c`	`#ffffff`