在 iOS SDK 中新增符號圖層 (預覽)

發行項
04/07/2024

本文會說明如何使用 Azure 地圖服務 iOS SDK，將資料來源中的點資料轉譯為地圖上的符號圖層。符號圖層會將點轉譯為地圖上的影像和文字。

注意

Azure 地圖服務 iOS SDK 淘汰

適用於 iOS 的 Azure 地圖服務原生 SDK 現在已被取代，將於 3/31/25 淘汰。若要避免服務中斷，請透過 3/31/25 移轉至 Azure 地圖服務 Web SDK。如需詳細資訊，請參閱 Azure 地圖服務 iOS SDK 移轉指南。

提示

根據預設，符號圖層會轉譯資料來源中所有幾何圖形的座標。若要限制圖層，使其只轉譯點幾何特徵，請將圖層的 filter 選項設為 NSPredicate(format: "%@ == \"Point\"", NSExpression.geometryTypeAZMVariable)。如果您想要同時包含 MultiPoint 特徵，請使用 NSCompoundPredicate。

必要條件

請務必完成快速入門：建立 iOS 應用程式文件中的步驟。本文中的程式碼區塊可以插入 ViewController 的 viewDidLoad 函式中。

新增符號圖層

您必須先執行幾個步驟，才能將符號圖層新增至地圖。首先，建立資料來源，並將其新增至地圖。建立符號圖層。然後，將資料來源傳入符號圖層，以從資料來源擷取資料。最後，將資料新增至資料來源，以便轉譯一些內容。

下列程式碼示範載入地圖之後應該新增至地圖的內容。此範例會使用符號圖層在地圖上轉譯單一點。

//Create a data source and add it to the map.
let source = DataSource()
map.sources.add(source)

//Create a point and add it to the data source.
source.add(geometry: Point(CLLocationCoordinate2D(latitude: 0, longitude: 0)))

//Create a symbol layer to render icons and/or text at points on the map.
let layer = SymbolLayer(source: source)

//Add the layer to the map.
map.layers.addLayer(layer)

有三種不同類型的點資料可以新增至地圖：

GeoJSON Point 幾何 - 此物件只包含點的座標，僅此而已。 Point init 方法可以用來輕鬆地建立這些物件。
GeoJSON MultiPoint 幾何 - 此物件包含多個點的座標，僅此而已。將座標陣列傳遞至 PointCollection 類別，以建立這些物件。
GeoJSON 特徵 - 此物件包含任何 GeoJSON 幾何以及一組屬性，其中包含與幾何相關聯的中繼資料。

如需詳細資訊，請參閱建立資料來源文件有關建立資料及將其新增至地圖的部分。

下列程式碼範例會建立 GeoJSON Point 幾何，並將其傳遞至 GeoJSON 特徵，將 title 值新增至其屬性。 title 屬性會顯示為地圖上符號圖示下方的文字。

// Create a data source and add it to the map.
let source = DataSource()
map.sources.add(source)

// Create a point feature.
let feature = Feature(Point(CLLocationCoordinate2D(latitude: 0, longitude: 0)))

// Add a property to the feature.
feature.addProperty("title", value: "Hello World!")

// Add the feature to the data source.
source.add(feature: feature)

// Create a symbol layer to render icons and/or text at points on the map.
let layer = SymbolLayer(
    source: source,
    options: [
        // Get the title property of the feature and display it on the map.
        .textField(from: NSExpression(forKeyPath: "title")),

        // Place the text below so it doesn't overlap the icon.
        .textAnchor(.top)
    ]
)

// Add the layer to the map.
map.layers.addLayer(layer)

下列螢幕擷取畫面顯示上述程式碼，使用具有符號圖層的圖示和文字標籤來轉譯點特徵。

顯示已新增至地圖之縮放控件的螢幕快照。

提示

根據預設，符號圖層會隱藏重疊的符號，以最佳化符號的轉譯。當您放大時，隱藏的符號就會變成可見。若要停用此功能並隨時轉譯所有符號，請將 iconAllowOverlap 和 textAllowOverlap 選項設定為 true。

將自訂圖示新增至符號圖層

使用 OpenGL 來轉譯符號圖層。所有這類資源 (例如圖示影像) 必須載入 OpenGL 內容中。此範例顯示如何將自訂圖示新增至地圖資源。接著，此圖示會用來在地圖上以自訂符號轉譯點資料。符號圖層的 textField 屬性需要指定運算式。在此案例中，我們想要轉譯溫度屬性。此外，我們想要將 "°F" 附加至其中。運算式可用來執行此串連：

NSExpression(
    forAZMFunctionJoin: [
        NSExpression(forKeyPath: "temperature"),
        NSExpression(forConstantValue: "°F")
    ]
)

// Load a custom icon image into the image sprite of the map.
map.images.add(UIImage(named: "showers")!, withID: "my-custom-icon")

// Create a data source and add it to the map.
let source = DataSource()
map.sources.add(source)

// Create a point feature.
let feature = Feature(Point(CLLocationCoordinate2D(latitude: 40.75773, longitude: -73.985708)))

// Add a property to the feature.
feature.addProperty("temperature", value: 64)

// Add the feature to the data source.
source.add(feature: feature)

// Create a symbol layer to render icons and/or text at points on the map.
let layer = SymbolLayer(
    source: source,
    options: [
        .iconImage("my-custom-icon"),
        .iconSize(0.5),
        // Get the title property of the feature and display it on the map.
        .textField(
            from: NSExpression(
                forAZMFunctionJoin: [
                    NSExpression(forKeyPath: "temperature"),
                    NSExpression(forConstantValue: "°F")
                ]
            )
        ),
        .textOffset(CGVector(dx: 0, dy: -1.5))
    ]
)

// Add the layer to the map.
map.layers.addLayer(layer)

在此範例中，下列影像會載入至應用程式的 assets 資料夾。


showers.png

下列螢幕擷取畫面顯示上述程式碼，使用具有符號圖層的自訂圖示和格式化文字標籤來轉譯點特徵。

顯示呈現點的地圖螢幕快照，使用符號圖層顯示自定義圖示和點特徵格式化的文字標籤。

提示

當您只想要轉譯具有符號圖層的文字時，您可以將圖示選項的 iconImage 屬性設定為 nil 來隱藏圖示。

預先定義的符號標記圖示

一開始，地圖有內建的預設標記圖示，此圖示已經載入地圖的影像原件中。如果未將任何項目設定為 iconImage 選項，則預設會使用這個項目。如果您需要手動執行此動作，請將 "marker-default" 設定為 iconImage 選項。

let layer = SymbolLayer(source: source, options: [.iconImage("marker-default")])

此外，Azure 地圖服務 iOS SDK 隨附一組預設 (深藍色) 標記圖示的預先定義色彩變化。若要存取這些標記圖示，請使用 UIImage 類別上的靜態變數，例如：UIImage.azm_markerRed。

若要使用非預設預先定義的標記影像，您應該將其新增至地圖的影像原件。

// Load a non-default predefined icon into the image sprite of the map.
map.images.add(.azm_markerRed, withID: "marker-red")

// Create a symbol layer to render icons and/or text at points on the map.
let layer = SymbolLayer(source: source, options: [.iconImage("marker-red")])

下列程式碼會列出內建圖示影像，這些影像都可作為 UIImage 類別的靜態變數。

UIImage.azm_markerDefault // Dark blue
UIImage.azm_markerBlack
UIImage.azm_markerBlue
UIImage.azm_markerRed
UIImage.azm_markerYellow

其他資訊

請參閱下列文章，以取得更多可新增至地圖的程式碼範例：

共用方式為