新增自訂資料

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> 一律會包含 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 範例

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>

返回頁首