如何使用映像範本

發行項
12/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 選項會先縮放影像範本，再將它套用至影像原件。影像套用至影像原件時，會轉換成 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 影像範本來轉譯符號圖層，如下列螢幕擷取畫面所示。

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

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

一旦影像範本載入地圖影像 Sprite，就可以將 LineString 新增至數據源並使用符號圖層lineSpacing搭配選項，並在選項iconOptions中image參考影像資源的標識碼，沿著線條的路徑轉譯。

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

提示

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

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

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

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

提示

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

搭配 HTML 標記使用影像範本

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

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

提示

影像範本也可用於地圖之外。 getImageTemplate 函式會傳回具有佔位符的 SVG 字串;{color}、、{scale}{secondaryColor}、{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

標記-粗邊

標記-圓形

標記 - 平面

標記圖示

標記-粗邊圖示

標記-圓形圖示

標記-平面圖示

標記-方形

標記-方形-叢集

標記-箭頭

標記-大頭針

標記-方形圖示

標記-方形-叢集圖示

標記-大頭針圖示

標記-方形-圓角

標記-方形-圓角-叢集

旗標

旗標-三角形

標記-方形-圓角圖示

標記-方形-圓角-叢集圖示

三角形

三角形-粗邊

三角形-箭號-向上

三角形-箭號-向左

三角形圖示

三角形-粗邊圖示

六邊形

六邊形 - 粗

六邊形-圓角

六邊形-圓角-粗邊

六邊形圖示

六邊形-粗邊圖示

六邊形-圓角圖示

六邊形-圓角-粗邊圖示

圖釘-圓形

圓角-方形

圓角-方形-粗邊

釘選圖示

圖釘-圓形圖示

圓角-方形圖示

圓角-方形-粗邊圖示

箭頭-向上

箭頭-向上-窄

汽車

汽車圖示

多邊形填滿圖樣

方格

方格-轉向

圓形

圓形-間隔

方格圖示

方格-轉向圖示

圓形圖示

圓形-間隔圖示

對角-線條-向上

對角-線條-向下

對角-帶狀線-向上

對角-帶狀線-向下

對角-線條-向上圖示

對角-線條-向下圖示

對角-帶狀線-向上圖示

對角-帶狀線-向下圖示

格線-線條

轉向-格線-線條

轉向-格線-帶狀線

x-填滿

格線-線條圖示

轉向-格線-線條圖示

轉向-格線-帶狀線圖示

x-填滿圖示

鋸齒

鋸齒-垂直

圓點

鋸齒圖示

鋸齒-垂直圖示

圓點圖示

預先載入的影像圖示

地圖會使用 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`