新增自訂資料

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> 元素預設在「地標」說明框中的表格顯示方式:

使用說明框預設樣式的資料範例

檢查:使用 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>

以下是這個範例的螢幕畫面擷取:

使用說明框預設樣式的資料範例

以下是更實際的 <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>

以下是使用這個說明框樣式範本的說明框範例:

將輸入的資料新增至特徵

<Schema> 和 <SchemaData> 元素可讓您將輸入的資料加到「特徵」中。某些 GIS 和程式設計應用程式需要使用此功能,因此必須處理此功能。

新增輸入資料的總覽

如要在自訂地圖項目中加入自訂類型,請執行以下兩個基本工作:

  1. 建立 <Schema> 元素,以宣告新的類型。
  2. 使用 <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> 一律會包含 nametype 屬性。如果同時沒有這兩個屬性,系統會忽略這個欄位。名稱屬性是用來在 <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 所參照的 Styleid)。如果 schemaUrlhttp 地址,Google 地球就會擷取整個網路的檔案。每個地標只能有一個指定使用者定義類型的執行個體。

範例

下列範例宣告名為 ScenicVista 的使用者定義類型。此類型包含三個欄位:TrailHeadName、TadLengthElevationGetTrailHeadName 欄位包含 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 範例

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 範本建立的說明框,與上一個畫面擷取內容相同資料的預設氣球樣式。

在特徵中新增任意 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>

返回頁首