KML 可讓您透過三種方式在 KML 地圖項目中新增自訂資料。至於選用何種方法,則取決於您新增的資料類型,以及 KML 簡報資料的使用方式。具體來說,<ExtendedData> 元素提供下列機制:
- <Data> 元素 - 可讓您將未命名的名稱/值組合新增至與特定功能 (NetworkLink、地標、GroundOverlay、PhotoOverlay、ScreenOverlay、文件或資料夾) 相關聯的使用者資料。根據預設,這些名稱/值組合會顯示在說明框中。這項資訊在 <BalloonStyle> 的 <text> 元素中也可用於取代實體 (請參閱使用 BalloonStyle 元素做為範本一節)。
- <Schema> 與 <SchemaData> 元素 - 可讓您將輸入的資料新增至與特定「功能」相關的使用者資料。
- 任意 XML 資料 - 您可在 KML 檔案中保存使用者資料。「Google 地球」會與檔案一併傳送和儲存資料,但並不會使用。
注意:這三項機制可以合併在同一個檔案中。如要新增不同來源的資料類型,建議您針對某些自訂資料使用已分類的資料方法 (Schema/SchemaData),針對其他自訂資料使用未輸入的資料 (Data)。
這時應使用哪一種方法?
在多數情況下,<Data> 元素提供最簡單且最強大的機制,可將「未輸入的」資料新增至 KML 特徵。這種方法比較容易實作,且具備建立 BalloonStyle 範本的優勢,可應用於 KML 檔案中的所有地標。如需相關用途範例,請參閱擴充資料元素的實體替換。
<Schema> 與 <SchemaData> 元素可讓您加入 typed 使用者資料。這些元素主要提供給具有 GIS (地理資訊系統) 資料的使用者。如果您已輸入外部電腦應用程式所使用的資料類型,則可能需要使用 <Schema> 和 <SchemaData> 元素,為特徵新增結構化資料類型。(「Google 地球」並不會使用這類輸入的資訊,但是您在其他應用程式中使用此功能)。不肖人士或許不需要這項機制所提供的技術性資訊。和 <Data> 一樣,<SchemaData> 可讓 BalloonStyle 使用範本。
如果您只需要傳送 KML 檔案的資料,且不需要 Google 地球來處理資料,請使用任意 XML 資料功能,可讓您參照 XML 命名空間前置字元,然後在目前的 KML 內容中傳遞資料。詳情請參閱任意 XML 資料一節。
正在新增未命名的名稱/值組合
<Data> 元素是一個簡單又強大的機制,可將未輸入的名稱/值組合新增至 KML 地圖項目。此元素的語法如下:
<ExtendedData>
<Data name="string">
<displayName>...</displayName> <!-- string -->
<value>...</value> <!-- string -->
</Data> </ExtendedData>
name 屬性是這份資料的專屬 ID。當您想要以容易使用的形式顯示這項資料的名稱時,系統會使用 <displayName> 元素。<displayName> 可包含 CDATA,其中包含空格、網址和超連結。
以下是「地標」的地標,其中包含了高爾夫球場中多個洞的自訂資料:
<kml xmlns="http://www.opengis.net/kml/2.2"> <Document> <name>My Golf Course Example</name> <Placemark> <name>Club house</name> <ExtendedData> <Data name="holeNumber"> <value>1</value> </Data> <Data name="holeYardage"> <value>234</value> </Data> <Data name="holePar"> <value>4</value> </Data> </ExtendedData> <Point> <coordinates>-111.956,33.5043</coordinates> </Point>
</Placemark> <Placemark> <name>By the lake</name> <ExtendedData> <Data name="holeNumber"> <value>5</value> </Data> <Data name="holeYardage"> <value>523</value> </Data> <Data name="holePar"> <value>5</value> </Data> </ExtendedData> <Point> <coordinates>-111.95,33.5024</coordinates> </Point>
</Placemark> </Document> </kml>
以下螢幕截圖顯示 <Data> 元素預設在「地標」說明框中的表格顯示方式:
使用說明框預設樣式的資料範例
![](https://developers.google.cn/static/kml/documentation/images/GolfCourse1.gif?authuser=3&hl=zh-tw)
檢查:使用 BalloonStyle 元素做為範本
在 KML 中,您可以定義樣式一次,並指定一個樣式。以這種方式定義樣式後,您可以使用 <styleUrl> 元素,在 KML 檔案 (或其他 KML 檔案中) 多次參照該樣式。以這種方式定義的樣式稱為「共用樣式」。<BalloonStyle> 內的 <text> 元素支援實體替換。您可以針對實體的每個例項替換個別的值。可取代的標準實體如下:
- $[姓名]
- 替換為地標的名稱
- $[說明]
- 替換為地標說明
- $[地址]
- 替換為地標的地址
- $[ID]
- 替換為地標 ID
- $[程式碼片段]
- 替換為地標的摘要
- $[geDirections] 替換為地標的「出發/出發」行車路線
擴充資料元素的實體替換
Google 地球也支援在 <BalloonStyle> 的 <text> 元素中取代某些延伸資料元素。 <text> 元素中可以參照下列實體:
變數 | 取代為 | 範例 |
---|---|---|
$[name_attribute_of_Data_element] | <value> 元素的內容 | holeNumber、holeYardage |
$[name_attribute_of_Data/displayName]敬上 | <displayName> 元素的內容 | 孔洞、孔洞 |
以下是為高爾夫球場範例建立 <BalloonStyle> 範本的範例。針對每個「地標」說明框,「Google 地球」會取代「地標」的名稱,並寫出每個孔的孔洞號碼、面數和庭院數:
<?xml version="1.0" encoding="UTF-8"?> <kml xmlns="http://www.opengis.net/kml/2.2"> <Document> <name>Data+BalloonStyle</name> <Style id="golf-balloon-style"> <BalloonStyle> <text> <![CDATA[ This is $[name] This is hole $[holeNumber] The par for this hole is $[holePar] The yardage is $[holeYardage] ]]> </text> </BalloonStyle> </Style> <!-- Shared style sample Two Placemarks use the same balloon template --> <Placemark> <name>Club house</name> <styleUrl>#golf-balloon-style</styleUrl> <ExtendedData> <Data name="holeNumber"> <value>1</value> </Data> <Data name="holeYardage"> <value>234</value> </Data> <Data name="holePar"> <value>4</value> </Data> </ExtendedData> <Point> <coordinates>-111.956,33.5043</coordinates> </Point> </Placemark> <Placemark> <name>By the lake</name> <styleUrl>#golf-balloon-style</styleUrl> <ExtendedData> <Data name="holeNumber"> <value>5</value> </Data> <Data name="holeYardage"> <value>523</value> </Data> <Data name="holePar"> <value>5</value> </Data> </ExtendedData> <Point> <coordinates>-111.95,33.5024</coordinates> </Point> </Placemark> </Document> </kml>
以下是這個範例的螢幕畫面擷取:
使用說明框預設樣式的資料範例
![](https://developers.google.cn/static/kml/documentation/images/GolfCourse2.gif?authuser=3&hl=zh-tw)
以下是更實際的 <displayName> 元素使用方式範例。這項技巧對文字進行本地化,以及更精細的格式。
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
<name>Entity-Replacement</name>
<Style id="displayName-value">
<BalloonStyle>
<text>
<![CDATA[
This is $[name]<br/>
$[holeNumber/displayName] $[holeNumber]<br/>
$[holePar/displayName] $[holePar]<br/>
$[holeYardage/displayName] $[holeYardage]
]]>
</text>
</BalloonStyle>
</Style>
<!-- Shared style sample
Two Placemarks use the same balloon template
-->
<Placemark>
<name>Club house</name>
<styleUrl>#displayName-value</styleUrl>
<ExtendedData>
<Data name="holeNumber">
<displayName><![CDATA[
<b>This is hole </b>
]]></displayName>
<value>1</value>
</Data>
<Data name="holePar">
<displayName><![CDATA[
<i>The par for this hole is </i>
]]></displayName>
<value>4</value>
</Data>
<Data name="holeYardage">
<displayName><![CDATA[
<b><i>The yardage is </i></b>
]]></displayName>
<value>234</value>
</Data>
</ExtendedData>
<Point>
<coordinates>-111.956,33.5043</coordinates>
</Point>
</Placemark>
<Placemark>
<name>By the lake</name>
<styleUrl>#Entity-Replacement</styleUrl>
<ExtendedData>
<Data name="holeNumber">
<displayName><![CDATA[
<b>This is hole </b>
]]></displayName>
<value>5</value>
</Data>
<Data name="holePar">
<displayName><![CDATA[
<i>The par for this hole is </i>
]]></displayName>
<value>5</value>
</Data>
<Data name="holeYardage">
<displayName><![CDATA[
<b><i>The yardage is </i></b>
]]></displayName>
<value>523</value>
</Data>
</ExtendedData>
<Point>
<coordinates>-111.95,33.5024</coordinates>
</Point>
</Placemark>
</Document>
</kml>
以下是使用這個說明框樣式範本的說明框範例:
![](https://developers.google.cn/static/kml/documentation/images/GolfCourse3.gif?authuser=3&hl=zh-tw)
將輸入的資料新增至特徵
<Schema> 和 <SchemaData> 元素可讓您將輸入的資料加到「特徵」中。某些 GIS 和程式設計應用程式需要使用此功能,因此必須處理此功能。
新增輸入資料的總覽
如要在自訂地圖項目中加入自訂類型,請執行以下兩個基本工作:
- 建立 <Schema> 元素,以宣告新的類型。
- 使用 <SchemaData> 元素建立新類型的執行個體。
宣告結構定義元素
結構定義元素會宣告結構化類型。<Schema> 一律為 <Document> 的子項。文件可以包含零或多個 Schema 元素。
ID 屬性
<Schema> 元素一律包含 ID 屬性,使用 <SchemaData> 建立這種類型的例項時,則會參照該 ID。KML 檔案內的編號不得重複。
name 屬性
用於取代實體的 name 屬性為選用項目。
語法
結構定義元素的語法如下:
<Schema name="string" id="ID"> <SimpleField type="string" name="string"> <displayName>...</displayName> <!-- string --> </SimpleField> </Schema>
<SimpleField> 一律會包含 name 和 type 屬性。如果同時沒有這兩個屬性,系統會忽略這個欄位。名稱屬性是用來在 <BalloonStyle> 的 <text> 元素中用於取代實體。Simplefield 的類型可以是下列其中一種:
string
int
uint
short
ushort
float
double
bool
定義資料的每個例項
使用 <SchemaData> 元素建立使用者定義的類型例項。<SchemaData> 的語法如下:
<ExtendedData> <SchemaData schemaUrl="anyURI"> <SimpleData name=""> ... </SimpleData> <!-- string --> </SchemaData> </ExtendedData>
schemaUrl 屬性會參照宣告類型的結構定義的 id (如同 styleUrl 所參照的 Style 的 id)。如果 schemaUrl 是 http 地址,Google 地球就會擷取整個網路的檔案。每個地標只能有一個指定使用者定義類型的執行個體。
範例
下列範例宣告名為 ScenicVista 的使用者定義類型。此類型包含三個欄位:TrailHeadName、TadLength 和 ElevationGet。TrailHeadName 欄位包含 string
類型的值。PathLengt 欄位包含 double
類型的值。ElevationGet 欄位包含 int
類型的值。「簡易步道」這個地標包含這種使用者類型的執行個體。這個執行個體的 TrailHeadName 欄位含有「Pi in the sky」(天空中的 P) 值、以 TrailLength 欄位填入 3.14159 的值,ElevationGet 欄位則是 10。
<kml xmlns="http://www.opengis.net/kml/2.2"> <Document> <name>ExtendedData+SchemaData</name> <open>1</open> <!-- Declare the type "TrailHeadType" with 3 fields --> <Schema name="TrailHeadType" id="TrailHeadTypeId"> <SimpleField type="string" name="TrailHeadName"> <displayName><![CDATA[<b>Trail Head Name</b>]]></displayName> </SimpleField> <SimpleField type="double" name="TrailLength"> <displayName><![CDATA[<i>Length in miles</i>]]></displayName> </SimpleField> <SimpleField type="int" name="ElevationGain"> <displayName><![CDATA[<i>Change in altitude</i>]]></displayName> </SimpleField> </Schema> <!-- This is analogous to adding three fields to a new element of type TrailHead: <TrailHeadType> <TrailHeadName>...</TrailHeadName> <TrailLength>...</TrailLength> <ElevationGain>...</ElevationGain> </TrailHeadType>
--> <!-- Instantiate some Placemarks extended with TrailHeadType fields --> <Placemark> <name>Easy trail</name> <ExtendedData> <SchemaData schemaUrl="#TrailHeadTypeId"> <SimpleData name="TrailHeadName">Pi in the sky</SimpleData> <SimpleData name="TrailLength">3.14159</SimpleData> <SimpleData name="ElevationGain">10</SimpleData> </SchemaData> </ExtendedData> <Point> <coordinates>-122.000,37.002</coordinates> </Point> </Placemark> <Placemark> <name>Difficult trail</name> <ExtendedData> <SchemaData schemaUrl="#TrailHeadTypeId"> <SimpleData name="TrailHeadName">Mount Everest</SimpleData> <SimpleData name="TrailLength">347.45</SimpleData> <SimpleData name="ElevationGain">10000</SimpleData> </SchemaData> </ExtendedData> <Point> <coordinates>-121.998,37.0078</coordinates> </Point> </Placemark> </Document> </kml>
使用說明框預設樣式的 schemaData 範例
![](https://developers.google.cn/static/kml/documentation/images/SchemaTrails2.gif?authuser=3&hl=zh-tw)
displayName 取代實體
另外,Schema/SchemaData 機制也支援在 <BalloonStyle> 元素的 <text> 元素中取代實體。
<Schema> 的 <displayName> 可讓您為自訂資料類型提供容易理解的版本。在 <Schema> 中一次變更字串後,將針對包含該類型的所有特徵變更 <displayName>。
在 <BalloonStyle> 元素的 <text> 元素中,使用下列語法限定 <displayName>:
$[TYPENAME/TYPEFIELD/displayName]
其中
- TYPENAME
- 是 <Schema> 的 name 屬性
- 輸入欄位
- 是 <SimpleField> 的 name 屬性
- displayName
- 是 <SimpleField> 中的 <displayName> 元素
以下程式碼將 BalloonStyle 範本新增至之前的 SchemaData 範例。如同「高爾夫課程」範例,系統會使用文件開頭的 <Style>、<BalloonStyle> 和 <text> 元素建立範本。檔案中每個地標都會參照這個樣式範本 (名為「ExtendedData+SchemaData」)。
<kml xmlns="http://www.opengis.net/kml/2.2"> <Document> <name>ExtendedData+SchemaData</name> <open>1</open> <!-- Create a balloon template referring to the user-defined type --> <Style id="trailhead-balloon-template"> <BalloonStyle> <text> <![CDATA[ <h2>My favorite trails!</h2> <br/><br/> The $[TrailHeadType/TrailHeadName/displayName] is <i>$[TrailHeadType/TrailHeadName]</i>. The trail is $[TrailHeadType/TrailLength] miles. <br/> The climb is $[TrailHeadType/ElevationGain] meters. <br/><br/> ]]> </text> </BalloonStyle> </Style> <!-- Declare the type "TrailHeadType" with 3 fields --> <Schema name="TrailHeadType" id="TrailHeadTypeId"> <SimpleField type="string" name="TrailHeadName"> <displayName><![CDATA[<b>Trail Head Name</b>]]></displayName> </SimpleField> <SimpleField type="double" name="TrailLength"> <displayName><![CDATA[<i>The length in miles</i>]]></displayName> </SimpleField> <SimpleField type="int" name="ElevationGain"> <displayName><![CDATA[<i>change in altitude</i>]]></displayName> </SimpleField> </Schema> <!-- Instantiate some Placemarks extended with TrailHeadType fields --> <Placemark> <name>Easy trail</name> <styleUrl>#trailhead-balloon-template</styleUrl> <ExtendedData> <SchemaData schemaUrl="#TrailHeadTypeId"> <SimpleData name="TrailHeadName">Pi in the sky</SimpleData> <SimpleData name="TrailLength">3.14159</SimpleData> <SimpleData name="ElevationGain">10</SimpleData> </SchemaData> </ExtendedData> <Point> <coordinates>-122.000,37.002</coordinates> </Point> </Placemark> <Placemark> <name>Difficult trail</name> <styleUrl>#trailhead-balloon-template</styleUrl> <ExtendedData> <SchemaData schemaUrl="#TrailHeadTypeId"> <SimpleData name="TrailHeadName">Mount Everest</SimpleData> <SimpleData name="TrailLength">347.45</SimpleData> <SimpleData name="ElevationGain">10000</SimpleData> </SchemaData> </ExtendedData> <Point> <coordinates>-121.998,37.0078</coordinates> </Point> </Placemark> </Document> </kml>
使用 BalloonStyle 範本的 schemaData 範例
比較使用 BalloonStyle 範本建立的說明框,與上一個畫面擷取內容相同資料的預設氣球樣式。
![](https://developers.google.cn/static/kml/documentation/images/schemaTrails.gif?authuser=3&hl=zh-tw)
在特徵中新增任意 XML 資料
最簡單的方法就是將資料加入「特徵」,是直接將資料新增為 <ExtendedData> 的值。「Google 地球」會保留這項資料,但不會處理這些資料。
以這種方式新增的自訂資料元素必須包含 namespace 前置字串 (xmlns:prefix="namespace”)。這個前置字串可以新增至 <KML> 元素或 <ExtendedData> 元素。外部命名空間前置字串必須符合各個使用者資料執行個體的資格,如以下範例所示:
<kml xmlns="http://www.opengis.net/kml/2.2"> <Document> <name>ExtendedData Test</name> <Placemark> <name>CampsiteData</name> <!-- Imported schema requires use of namespace prefix --> <ExtendedData xmlns:camp="http://campsites.com"> <camp:number>14</camp:number> <camp:parkingSpaces>2</camp:parkingSpaces> <camp:tentSites>4</camp:tentSites> </ExtendedData> <Point> <coordinates>-114.041,53.7199</coordinates> </Point> </Placemark> </Document> </kml>