添加自定义数据

KML 提供了三种方法将自定义数据添加到 KML 地图项。选择哪种方法取决于您添加的数据类型，以及您计划如何在 KML 演示中使用这些数据。具体而言，<ExtendedData> 元素提供了以下机制：

  • <Data> 元素 - 可让您向与给定地图项（NetworkLink、Placemark、GroundOverlay、PhotoOverlay、ScreenOverlay、Document 或 Folder）关联的用户数据添加非类型化名称/值对。默认情况下，这些名称/值对显示在提示框中。此信息也可以用于 <BalloonStyle> 的 <text> 元素中的实体替换（参见使用 BalloonStyle 元素作为模板部分）。
  • <Schema> 和 <SchemaData> 元素 - 可让您向与给定地图项关联的用户数据添加类型化数据。
  • 任意 XML 数据 - 可让您在 KML 文件内保留用户数据。Google 地球会将该数据与文件一起传递并进行保存，但不会使用该数据。

请注意：这三种机制可以在同一个文件中结合使用。如果您要从不同来源添加不同类型的数据，最好对某些自定义数据使用类型化数据的方法 (Schema/SchemaData)，对其他自定义数据使用非类型化数据的方法 (Data)。

您应该使用哪种方法？

大多数情况下，<Data> 元素可提供最简便、最强大的机制，来将非类型化数据添加到 KML 地图项。该方法相对来说容易实现，并且具有便于使用 BalloonStyle 模板的优势，该模板可应用于 KML 文件中的所有地标（有关此用法的示例，请参见扩展数据元素的实体替换）。

您可以通过 <Schema> 和 <SchemaData> 元素添加类型化用户数据。这些元素主要提供给有 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 中，您可以定义一次样式，并为它指定一个 ID。以这种方式定义该样式后，您可以使用 <styleUrl> 元素在该 KML 文件（或者其他 KML 文件）内多次进行引用。以这种方式定义的样式称为共享样式。<BalloonStyle> 内的 <text> 元素支持实体替换。对于每个实体实例而言，各个值都是可以替换的。可替换的标准实体如下：

$[name]
替换为地标的名称
$[description]
替换为地标的说明
$[address]
替换为地标的地址
$[id]
替换为地标的 ID
$[Snippet]
替换为地标的代码段
$[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 和编程应用需要该功能，因为它们要处理类型化数据。

关于添加类型化数据的概述

要向 KML 地图项添加自定义类型，可执行两项基本任务：

  1. 创建 <Schema> 元素以声明您的新类型。
  2. 使用 <SchemaData> 元素以创建新类型的实例。

声明 Schema 元素

Schema 元素可声明结构化类型。<Schema> 始终是 <Document> 的子元素。Document 可以不包含或包含多个 Schema 元素。

ID 属性

<Schema> 元素始终具有 ID 属性，创建该类型的实例（使用 <SchemaData>）时会引用该属性。该 ID 在 KML 文件内必须是唯一的。

name 属性

name 属性是可选的，用于实体替换。

语法

Schema 元素的语法如下：

<Schema name="string" id="ID">   
  <SimpleField type="string" name="string">     
    <displayName>...</displayName>            <!-- string -->   
  </SimpleField> 
</Schema>

<SimpleField> 始终具有 name 和 type 属性。如果未同时具备这两个属性，则忽略该字段。name 属性用于 <BalloonStyle> 的 <text> 元素中的实体替换。Simplefield 的类型可以是以下某一种：

  • string
  • int
  • uint
  • short
  • ushort
  • float
  • double
  • bool

定义数据的每个实例

使用 <SchemaData> 元素创建用户定义类型的实例。<SchemaData> 的语法如下：

<ExtendedData>                   
  <SchemaData schemaUrl="anyURI">
    <SimpleData name=""> ... </SimpleData>       <!-- string -->
  </SchemaData>
</ExtendedData>

schemaUrl 属性引用声明该类型的 Schema 的 ID（就像 styleUrl 引用已声明的 Style 的 ID 一样）。如果 schemaUrl 是一个 HTTP 地址，则 Google 地球将从网络上获取该文件。对于每个地标，只能有一个给定用户定义类型的实例。

示例

以下示例声明了名为 ScenicVista 的用户定义类型。该类型包含3个字段：TrailHeadName、TrailLength 和 ElevationGain。TrailHeadName 字段包含 string 类型的值。TrailLength 字段包含 double 类型的值。ElevationGain 字段包含 int 类型的值。名为“Easy trail”的地标包含该用户类型的实例。该实例中，TrailHeadName 字段的值为“Pi in the sky”，TrailLength 字段的值为3.14159，ElevationGain 字段的值为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 属性
TYPEFIELD
是 <SimpleField> 的 name 属性
displayName
是 <SimpleField> 内的 <displayName> 元素

以下代码会向上一个 SchemaData 示例添加 BalloonStyle 模板。与在高尔夫球场示例中一样，该模板是在 Document 开头使用 <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> 元素中。外部 namespace 前缀必须限定用户数据的每个实例，如以下示例所示：

<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>

返回页首