Персонализированные данные

Добавить персонализированные данные к компоненту KML можно тремя способами. Какой из них вы выберете зависит от характера добавляемых данных и от того, как они должны отображаться. В частности, элемент <ExtendedData> поддерживает указанные ниже механизмы.

  • Элемент <Data> позволяет добавлять нетипизированные пары "имя-значение" к пользовательским данным, связанным с компонентом KML (NetworkLink, Placemark, GroundOverlay, PhotoOverlay, ScreenOverlay, Document или Folder). Пары "имя-значение" по умолчанию отображаются во всплывающем окне с описанием. Они также могут служить для замещения объектов в элементе <text> внутри <BalloonStyle>. Подробнее…
  • Элементы <Schema> и <SchemaData> позволяют добавлять к пользовательским данным, связанным с компонентом KML, типизированные данные.
  • В KML-файл также можно включить любые пользовательские данные в формате XML. Google Планета Земля передает и сохраняет их вместе с файлом, однако никак не обрабатывает.

Примечание. Все три механизма можно применить в одном файле. Если разная информация добавляется из разных источников, рекомендуется использовать как типизированные данные (Schema/SchemaData), так и нетипизированные (Data).

Выбор механизма добавления данных

В большинстве случаев нетипизированные данные проще всего добавить к компоненту KML с помощью элемента <Data>. Для этого потребуется шаблон <BalloonStyle>, который можно применить ко всем компонентам Placemark в KML-файле. (Пример использования приведен в разделе Замещение объектов в элементах с расширенными данными.)

С помощью элементов <Schema> и <SchemaData> можно добавлять типизированные данные. Этот способ в первую очередь подойдет для передачи информации из географических информационных систем (ГИС). Если у вас есть типизированные данные из внешних приложений, используйте для добавления к компоненту структурированных типов элементы <Schema> и <SchemaData>. (Google Планета Земля не использует эти данные, но они могут требоваться другим приложениям.) Большинству пользователей, скорее всего, не потребуется знать остальные технические подробности этого механизма. Как и <Data>, элемент <SchemaData> упрощает работу с <BalloonStyle>.

Если вам требуется просто передать данные внутри KML-файла (без обработки в Google Планете Земля), достаточно записать их в формате XML. Для этого в KML-файле потребуется указать префикс пространства имен XML. Подробнее…

Добавление нетипизированных пар "имя-значение"

Элемент <Data> представляет собой достаточно простой и эффективный способ добавления нетипизированных пар "имя-значение" к компоненту KML. Ниже показан синтаксис этого элемента.

<ExtendedData>                       
 <Data name="string">
  <displayName>...</displayName>    <!-- string -->
    <value>...</value>                <!-- string -->
 </Data> </ExtendedData>

Атрибут name является уникальным идентификатором набора данных. Элемент <displayName> используется, если необходимо отобразить название набора данных в удобной для чтения форме. Добавьте в элемент <displayName> тег CDATA, чтобы использовать пробелы и гиперссылки.

Ниже показан пример кода для компонента Placemark, содержащего пользовательские данные о нескольких лунках на площадке для гольфа.

<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 можно определить элемент <Style>, присвоив ему идентификатор. После этого на стиль можно ссылаться с помощью <styleUrl> из того же или других KML-файлов. Определяемые таким образом стили называются общими. Элемент <text> внутри <BalloonStyle> поддерживает замещение объектов, т. е. для каждого экземпляра могут быть подставлены собственные значения. Ниже показан алгоритм замещения стандартных объектов.

$[name]
замещается названием метки.
$[description]
замещается описанием метки.
$[address]
замещается адресом метки.
$[id]
замещается идентификатором метки.
$[Snippet]
замещается фрагментом метки.
$[geDirections]
замещается инструкциями по навигации к метке или от нее.

Замещение объектов в элементах с расширенными данными

В Google Планете Земля поддерживается замещение объектов для некоторых расширенных данных, включенных в элемент <text> внутри <BalloonStyle>. В таблице ниже перечислены такие объекты.

Переменная Чем замещается Пример
$[name_attribute_of_Data_element] Содержание элемента <value> holeNumber, holeYardage
$[name_attribute_of_Data/displayName] Содержание элемента <displayName> Hole Number, Hole Yardage

Ниже показан код, в котором задается шаблон <BalloonStyle> для примера с лунками на площадке для гольфа. Во всплывающем окне с описанием каждой метки подставляется название метки и добавляется информация о номере лунки, паре и расстоянии до нее. 

<?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>
  <!-- Пример общего стиля:
        одно и то же окно с описанием используется для двух меток
  -->
  <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>
 <!-- Пример общего стиля:
 одно и то же окно с описанием используется для двух меток
 -->
 <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> позволяют добавить к компоненту типизированные данные. Эта функция полезна для передачи информации из ГИС и программных приложений, работающих с такими данными.

Что потребуется для добавления типизированных данных

Чтобы добавить к компоненту KML типизированные данные, выполните указанные ниже действия.

  1. Создайте элемент <Schema>, чтобы объявить новый тип.
  2. Создайте экземпляры нового типа с помощью элемента <SchemaData>.

Объявление элемента <Schema>

Элемент <Schema> служит для объявления структурированного типа данных и всегда является дочерним элементом элемента <Document>. Один <Document> может содержать любое количество элементов <Schema> или не содержать их вовсе.

Атрибут id

Элементу <Schema> всегда присваивается атрибут id, с помощью ссылок на который создаются экземпляры этого типа (используется элемент <SchemaData>). В KML-файле не должно быть двух одинаковых идентификаторов (id).

Атрибут name

Атрибут name используется для замещения объектов и не является обязательным.

Синтаксис

Ниже показан синтаксис элемента <Schema>.

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

Элементу <SimpleField> всегда присваиваются атрибуты name и type. Если хотя бы один из них отсутствует, поле пропускается. Атрибут name можно также использовать для замещения объектов в элементе <text> внутри <BalloonStyle>. Тип Simplefield может принимать следующие значения:

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

Определение экземпляров данных

С помощью элемента <SchemaData> можно создать экземпляр типа персонализированных данных. Ниже показан синтаксис этого элемента.

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

Атрибут schemaUrl ссылается на id элемента <Schema>, в котором объявляется тип (подобно тому, как styleUrl ссылается на id уже объявленного элемента Style).Если schemaUrl является http-адресом, Google Планета Земля получает файл из Интернета. Компоненту Placemark можно назначить только один экземпляр данного типа.

Пример

В примере ниже представлен тип пользовательских данных под названием ScenicVista. Он содержит три поля: TrailHeadName, TrailLength и ElevationGain. Поле TrailHeadName содержит значения типа string, поле TrailLength – значения типа double, а поле ElevationGain – значения типа int. Метка с названием Easy trail содержит экземпляр этого типа. Для экземпляра заданы следующие значения: Pi in the sky в поле TrailHeadName, 3.14159 в поле TrailLength и 10 в поле ElevationGain.

<kml xmlns="http://www.opengis.net/kml/2.2"> 
<Document>   
  <name>ExtendedData+SchemaData</name>   
  <open>1</open>

  <!-- определяем тип TrailHeadType с помощью 3 полей -->
  <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> 

<!-- Это аналогично добавлению трех полей в новый элемент типа TrailHead:

  <TrailHeadType>        
    <TrailHeadName>...</TrailHeadName>        
    <TrailLength>...</TrailLength>        
    <ElevationGain>...</ElevationGain>    
 </TrailHeadType>
--> <!-- Создадим экземпляры Placemark с полями TrailHeadType --> <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 также поддерживает замещение объектов в элементе <text> внутри <BalloonStyle>.

В <displayName> элемента <Schema> можно включить пользовательские данные в пригодной для просмотра форме. Если изменить строку в элементе <Schema>, изменится и атрибут <displayName> всех компонентов, содержащих этот тип.

В элементе <text> внутри <BalloonStyle> определите <displayName> следующим образом:

$[TYPENAME/TYPEFIELD/displayName]

TYPENAME
– это атрибут name элемента <Schema>;
TYPEFIELD
– это атрибут name элемента <SimpleField>;
displayName
– это элемент <displayName> внутри <SimpleField>.

Ниже показан код для добавления шаблона <BalloonStyle> в <SchemaData> из предыдущего примера. Как и в примере с площадкой для гольфа, в начале документа определяются элементы <Style>, <BalloonStyle> и <text>. Затем все элементы Placemark в файле ссылаются на этот шаблон (ExtendedData+SchemaData). 

<kml xmlns="http://www.opengis.net/kml/2.2"> 
<Document>   
  <name>ExtendedData+SchemaData</name>   
  <open>1</open>    
  <!-- Создадим шаблон, ссылающийся на пользовательский тип -->
  <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>     

  <!-- Объявим тип TrailHeadType с помощью 3 полей -->
  <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>       

  <!-- Создадим экземпляры Placemark с полями TrailHeadType -->    
  <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>

Пример SchemaData с шаблоном BalloonStyle

Сравните всплывающее окно, созданное с помощью шаблона <BalloonStyle>, с окном на предыдущем скриншоте, для которого оставлен стиль по умолчанию.

Добавление пользовательских XML-данных к компоненту

Самый простой способ добавить к компоненту пользовательские данные – указать их в теге <ExtendedData>. Google Планета Земля сохраняет, но не обрабатывает такие данные.

Пользовательские данные, добавленные этим способом, должны включать префикс пространства имен (xmlns:prefix="namespace"). Его можно указать в элементе <kml> внутри <ExtendedData>. Префикс пространства имен должен предварять каждый экземпляр пользовательских данных, как показано ниже. 

<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
  <name>ExtendedData Test</name>
  <Placemark>
    <name>CampsiteData</name>
    <!-- Импортированной схеме требуется префикс пространства имен -->
    <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>

Наверх