簡介
KML 是 XML 資料格式的延伸，用來代表地圖上的地理資料。您可以使用此公用程式，將 KML 物件轉換成地理形狀，然後算繪為疊加在地圖上的圖層。如要在地圖中新增或移除 KML 資料，請分別呼叫 addLayerToMap() 和 removeLayerFromMap()。如要存取 KML 物件的屬性，請在任何地標、區域疊加層、文件或資料夾上呼叫 getProperties()。
在地圖中新增 KML 圖層
如要在地圖中加入資料層，請先建立 KmlLayer 類別的例項；目前有兩種方式可以把 KmlLayer 執行個體化。
如要從本機資源匯入並算繪 KML 資料集，您需要下列項目：
GoogleMap物件，也就是要算繪圖層的地方。- 包含 KML 資料的本機資源檔案。
Context物件，這是開啟本機資源檔案的必要物件。
Kotlin
val layer = KmlLayer(map, R.raw.geojson_file, context)
Java
KmlLayer layer = new KmlLayer(map, R.raw.geojson_file, context);
如要從本機串流匯入並算繪 KML 資料集，您需要下列項目：
GoogleMap物件，也就是要算繪圖層的地方。- 包含 KML 資料的
InputStream。 Context物件，這是開啟本機資源的必要物件。
Kotlin
val inputStream: InputStream? = // InputStream containing KML data
val layer = KmlLayer(map, inputStream, context)
Java
InputStream inputStream = // InputStream containing KML data
KmlLayer layer = new KmlLayer(map, inputStream, context);
建立 KmlLayer 後，呼叫 addLayerToMap()() 即可將匯入的資料新增至地圖。
Kotlin
layer.addLayerToMap()
Java
layer.addLayerToMap();
清除 KML 圖層
假設您已建立下列 KmlLayer：
Kotlin
val inputStream: InputStream? = // InputStream containing KML data
val layer = KmlLayer(map, inputStream, context)
Java
InputStream inputStream = // InputStream containing KML data
KmlLayer layer = new KmlLayer(map, inputStream, context);
如要將圖層從地圖中移除，請呼叫 removeLayerFromMap()：
Kotlin
layer.removeLayerFromMap()
Java
layer.removeLayerFromMap();
存取 KML 容器
如要存取已新增至圖層的任何容器，您可以在已建立的圖層上呼叫 getContainers()。如要查看是否有任何容器包含巢狀容器，可以呼叫 hasContainers()。如要存取這些巢狀容器，做法與在圖層中的操作類似，您可以呼叫 getContainers()
如要存取 KmlLayer 或 KmlContainer: 中「非」巢狀結構的容器：
Kotlin
for (containers in layer.containers) {
// Do something to container
}
Java
for (KmlContainer containers : layer.getContainers()) {
// Do something to container
}
如要存取 KmlLayer 或 KmlContainer 中「是」巢狀結構的容器：
Kotlin
fun accessContainers(containers: Iterable<KmlContainer>) {
for (container in containers) {
if (container.hasContainers()) {
accessContainers(container.containers)
}
}
Java
public void accessContainers(Iterable<KmlContainer> containers) {
for (KmlContainer container : containers) {
if (container.hasContainers()) {
accessContainers(container.getContainers());
}
}
}
存取 KML 地標和 KML 區域疊加層
如要存取已新增至圖層的任何地標或區域疊加層，您可以在圖層或容器中呼叫 getPlacemarks() 或 getGroundOverlays()。呼叫這兩項分別會傳回 KmlPlacemarks 或 KmlGroundOverlays 的疊代。
例如，如要從圖層存取 KmlPlacemark 物件：
Kotlin
for (placemark in layer.placemarks) {
// Do something to Placemark
}
Java
for (KmlPlacemark placemark : layer.getPlacemarks()) {
// Do something to Placemark
}
存取 KML 屬性
如要存取容器或地標中的任何屬性，請呼叫 getProperty() 並為其提供屬性鍵。您也可以呼叫 hasProperty() 來確認該屬性是否存在。下例顯示如果容器有屬性值「name」，要如何從中擷取。
Kotlin
for (container in layer.containers) {
if (container.hasProperty("name")) {
Log.i("KML", container.getProperty("name"))
}
}
Java
for (KmlContainer container : layer.getContainers()) {
if (container.hasProperty("name")) {
Log.i("KML", container.getProperty("name"));
}
}
KML 幾何圖形點擊事件
您可以使用 KmlLayer.OnFeatureClickListener() 監聽地圖上幾何圖形地圖項目的點擊事件。下例顯示使用者點選地圖項目時，系統會記錄該地圖項目的 ID：
Kotlin
// Set a listener for geometry clicked events.
layer.setOnFeatureClickListener { feature ->
Log.i(
"KML",
"Feature clicked: " + feature.id
)
}
Java
// Set a listener for geometry clicked events.
layer.setOnFeatureClickListener(new KmlLayer.OnFeatureClickListener() {
@Override
public void onFeatureClick(Feature feature) {
Log.i("KML", "Feature clicked: " + feature.getId());
}
});
查看試用版應用程式
如需示例瞭解如何匯入 KML 檔案並以此建立圖層，可以透過公用程式庫隨附的試用版應用程式，參考 KmlDemoActivity 看看。設定指南會示範如何執行試用版應用程式。
KML 支援的功能
| KML 元素 | 是否支援？ | 註解 |
|---|---|---|
| <address> | 部分支援 | 儲存為屬性值 |
| <AddressDetails> | 否 | |
| <Alias> | 否 | |
| <altitude> | 否 | |
| <altitudeMode> | 否 | |
| <atom:author> | 否 | |
| <atom:link> | 否 | |
| <atom:name> | 否 | |
| <BalloonStyle> | 部分支援 | 僅支援 <text> |
| <begin> | 不適用 | 不支援 <TimeSpan> |
| <bgColor> | 否 | |
| <bottomFov> | 不適用 | 不支援 <PhotoOverlay> |
| <Camera> | 否 | |
| <Change> | 部分支援 | 僅支援樣式變更 |
| <color> | 部分支援 | 包含 #AABBGGRR 和 #BBGGRR；<ScreenOverlay> 和 <GroundOverlay> 不支援 |
| <colorMode> | 是 | |
| <cookie> | 否 | 不支援 <NetworkLinkControl> |
| <coordinates> | 是 | |
| <Create> | 否 | |
| <Data> | 否 | |
| <Delete> | 否 | |
| <description> | 是 | 僅支援純文字，不支援 HTML 內容 |
| <displayMode> | 否 | |
| <displayName> | 否 | |
| <Document> | 是 | |
| <drawOrder> | 是 | |
| <east> | 是 | |
| <end> | 不適用 | 不支援 <TimeSpan> |
| <expires> | 否 | 不支援 <NetworkLinkControl> |
| <ExtendedData> | 部分支援 | 僅支援未經類型宣告的 <Data>，不支援 <SimpleData> 或 <Schema>，也不支援 form$[dataName] 的實體替代項目。 |
| <extrude> | 否 | |
| <fill> | 是 | |
| <flyToView> | 否 | 不支援 <NetworkLinkControl> |
| <Folder> | 是 | |
| <gridOrigin> | 不適用 | 不支援 <PhotoOverlay> |
| <GroundOverlay> | 是 | |
| <heading> | 是 | |
| <hotSpot> | 是 | |
| <href> | 是 | |
| <httpQuery> | 否 | |
| <Icon> | 是 | |
| <IconStyle> | 是 | |
| <ImagePyramid> | 不適用 | 不支援 <PhotoOverlay> |
| <innerBoundaryIs> | 是 | 依 <LinearRing> 順序默示 |
| <ItemIcon> | 不適用 | 不支援 <ListStyle> |
| <key> | 是 | |
| <kml> | 是 | |
| <LabelStyle> | 否 | |
| <latitude> | 是 | |
| <LatLonAltBox> | 否 | |
| <LatLonBox> | 是 | |
| <leftFov> | 不適用 | 不支援 <PhotoOverlay> |
| <LinearRing> | 是 | |
| <LineString> | 是 | |
| <LineStyle> | 是 | |
| <Link> | 否 | |
| <linkDescription> | 不適用 | 不支援 <NetworkLinkControl> |
| <linkName> | 不適用 | 不支援 <NetworkLinkControl> |
| <linkSnippet> | 不適用 | 不支援 <NetworkLinkControl> |
| <listItemType> | 不適用 | 不支援 <ListStyle> |
| <ListStyle> | 否 | |
| <Location> | 不適用 | 不支援 <Model> |
| <Lod> | 是 | |
| <longitude> | 是 | |
| <LookAt> | 否 | |
| <maxAltitude> | 否 | |
| <maxFadeExtent> | 否 | |
| <maxHeight> | 不適用 | 不支援 <PhotoOverlay> |
| <maxLodPixels> | 否 | |
| <maxSessionLength> | 否 | |
| <maxWidth> | 不適用 | 不支援 <PhotoOverlay> |
| <message> | 否 | |
| <minAltitude> | 否 | |
| <minFadeExtent> | 否 | |
| <minLodPixels> | 否 | |
| <minRefreshPeriod> | 否 | <NetworkLink> |
| <Model> | 否 | |
| <MultiGeometry> | 是 | |
| <name> | 是 | |
| <near> | 不適用 | 不支援 <PhotoOverlay> |
| <NetworkLink> | 否 | |
| <NetworkLinkControl> | 否 | |
| <north> | 是 | |
| <open> | 是 | 儲存為屬性值 |
| <Orientation> | 不適用 | 不支援 <Model> |
| <outerBoundaryIs> | 是 | 依 <LinearRing> 順序默示 |
| <outline> | 是 | |
| <overlayXY> | 否 | |
| <Pair> | 是 | |
| <phoneNumber> | 部分支援 | 儲存為屬性值 |
| <PhotoOverlay> | 否 | |
| <Placemark> | 是 | |
| <Point> | 是 | |
| <Polygon> | 是 | |
| <PolyStyle> | 是 | |
| <range> | 是 | |
| <refreshInterval> | 否 | |
| <refreshMode> | 否 | |
| <refreshVisibility> | 否 | |
| <Region> | 是 | |
| <ResourceMap> | 不適用 | 不支援 <Model> |
| <rightFov> | 不適用 | 不支援 <PhotoOverlay> |
| <roll> | 不適用 | 不支援 <Camera> 和 <Model> |
| <rotation> | 是 | |
| <rotationXY> | 否 | |
| <Scale> | 不適用 | 不支援 <Model> |
| <scale> | 是 | |
| <Schema> | 否 | |
| <SchemaData> | 否 | |
| <ScreenOverlay> | 否 | |
| <screenXY> | 不適用 | 不支援 <ScreenOverlay> |
| <shape> | 不適用 | 不支援 <PhotoOverlay> |
| <SimpleData> | 不適用 | 不支援 <SchemaData> |
| <SimpleField> | 不適用 | 不支援 <Schema> |
| <size> | 是 | |
| <Snippet> | 否 | |
| <south> | 是 | |
| <state> | 不適用 | 不支援 <ListStyle> |
| <Style> | 是 | |
| <StyleMap> | 部分支援 | 不提供醒目顯示樣式。不支援內嵌 StyleMap |
| <styleUrl> | 是 | |
| <targetHref> | 否 | 不支援 <Alias> |
| <tessellate> | 否 | |
| <text> | 是 | |
| <textColor> | 否 | |
| <tileSize> | 不適用 | 不支援 <PhotoOverlay> |
| <tilt> | 否 | |
| <TimeSpan> | 否 | |
| <TimeStamp> | 否 | |
| <topFov> | 不適用 | 不支援 <PhotoOverlay> |
| <Update> | 不適用 | 不支援 <NetworkLinkControl> |
| <value> | 是 | |
| <viewBoundScale> | 否 | |
| <viewFormat> | 否 | |
| <viewRefreshMode> | 否 | |
| <viewRefreshTime> | 否 | |
| <ViewVolume> | 不適用 | 不支援 <PhotoOverlay> |
| <visibility> | 是 | |
| <west> | 是 | |
| <when> | 不適用 | 不支援 <TimeStamp> |
| <width> | 是 |