KML udostępnia trzy sposoby dodawania danych niestandardowych do funkcji KML. To, którą metodę wybierzesz, zależy od rodzaju danych, które dodajesz, oraz od tego, jak planujesz wykorzystać je w prezentacji KML. Element <ExtendedData> zawiera następujące mechanizmy:
- Element <Dane> – umożliwia dodawanie par nazwa-wartość do danych użytkownika niepowiązanych z konkretną funkcją (NetworkLink, Placemark, GroundOverlay, PhotoOverlay, ScreenOverlay, Document lub Folder). Te pary nazw i wartości są domyślnie wyświetlane w dymkach. Ta informacja może być również użyta do zamiany elementów w elemencie <text> tagu <BalloonStyle> (więcej informacji znajdziesz w sekcji Używanie elementu BalloonStyle jako szablonu).
- Elementy <Schema> i <SchemaData> umożliwiają dodawanie typów danych do danych użytkownika powiązanych z konkretną funkcją.
- Dowolne dane XML – umożliwiają zachowanie danych użytkownika w pliku KML. Google Earth przekazuje te dane wraz z plikiem i zapisuje je, ale nie używa ich.
Uwaga: te 3 mechanizmy można połączyć w tym samym pliku. Jeśli dodajesz różne typy danych z różnych źródeł, w przypadku niektórych danych niestandardowych warto zastosować typ danych (Schemat lub schema.org), a w przypadku innych – niestandardowe.
Które podejście zastosować?
W większości przypadków element <Dane> to najprostszy i najbardziej zaawansowany mechanizm dodawania danych niewpisanych do funkcji KML. Ta metoda jest stosunkowo prosta do wdrożenia i zaleta ułatwia wykorzystanie szablonu BalloonStyle, który można zastosować do wszystkich oznaczeń miejsc w pliku KML. Przykład takiego zastosowania znajdziesz w artykule Zastępowanie elementów rozszerzonych elementów danych.
Elementy <Schema> i <SchemaData> umożliwiają dodawanie danych użytkownika wpisanych. Te elementy są dostępne głównie dla użytkowników z danymi systemu informacji GIS. Jeśli masz wpisane dane używane przez zewnętrzną aplikację komputerową, prawdopodobnie do dodawania do obiektu funkcji musisz użyć elementów <Schema> i <SchemaData>. (Google Earth nie wykorzystuje wpisywanych informacji, ale inna aplikacja może ich wymagać). Zwykli użytkownicy prawdopodobnie nie potrzebują dodatkowych aspektów technicznych oferowanych przez ten mechanizm. Podobnie jak <Data>, <SchemaData> ułatwia używanie szablonów w BalloonStyle.
Jeśli chcesz po prostu przekazywać dane wraz z plikiem KML, a nie chcesz, aby program Google Earth przetwarzał dane, użyj funkcji dowolnych danych XML , która umożliwia odwołanie się do prefiksu przestrzeni nazw XML i przekazywanie danych w bieżącym kontekście KML. Więcej informacji znajdziesz w sekcji dotyczącej arbitralnych danych XML.
Dodawanie niezapisanych par nazw/wartości
Element <data> to prosty i wszechstronny mechanizm dodawania par nazwa-wartość do funkcji KML. Składnia tego elementu jest taka:
<ExtendedData>
<Data name="string">
<displayName>...</displayName> <!-- string -->
<value>...</value> <!-- string -->
</Data> </ExtendedData>
Atrybut name to unikalny identyfikator tego zbioru danych. Element <displayName> jest używany, gdy chcesz wyświetlić nazwę tych danych w przyjaznej dla użytkownika formie. Element <displayName> może zawierać element CDATA ze spacjami, adresami URL i hiperlinkami.
Oto przykład oznaczenia miejsca zawierające niestandardowe dane dotyczące kilku dołków na polu golfowym:
<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>
Ten zrzut ekranu pokazuje domyślnie, jak elementy <danych> są wyświetlane w tabeli w dymku oznaczenia miejsca:
Przykładowe użycie danych z użyciem domyślnego stylu dymków
![](https://developers-dot-devsite-v2-prod.appspot.com/static/kml/documentation/images/GolfCourse1.gif?authuser=9&hl=pl)
Omówienie: używanie elementu BalloonStyle jako szablonu
W pliku KML możesz zdefiniować styl raz i przypisać do niego identyfikator. Po zdefiniowaniu w ten sposób stylu możesz odwoływać się do niego wiele razy za pomocą pliku KML (lub innych plików KML), korzystając z elementu <styleUrl>. Styl zdefiniowany w ten sposób jest nazywany stylem wspólnym. Element <text> w tagu <BalloonStyle> obsługuje zamiennik elementu. Poszczególne wartości mogą być zastępowane poszczególnymi wartościami. Elementy standardowe, które można zastąpić:
- $[nazwa]
- Zastąpiono nazwą oznaczenia miejsca
- $[description]
- Zastąpiono opisem oznaczenia miejsca
- $[adres]
- Zastąpiono adresem oznaczenia miejsca
- $[identyfikator]
- Zastąpiono identyfikatorem oznaczenia miejsca
- $[fragment]
- Zastąpiono fragmentem oznaczenia miejsca
- $[geTrasa]
- Zastąpione wskazówkami dojazdu do/z trasy dojazdu oznaczenia miejsca
Zamiana elementów rozszerzonych elementów danych
Google Earth obsługuje też wymianę niektórych rozszerzonych elementów danych w elemencie <text> tagu <BalloonStyle>. W elemencie <text> można znaleźć te elementy:
Zmienna | Zastąpione przez | Przykład |
---|---|---|
$[name_attribute_of_Data_element] | Zawartość elementu <value> | liczba dziur, dołek |
$[nazwa_attribute_of_Data/wyświetlana_nazwa] | Zawartość elementu <displayName> | Numer otworu, dziura |
Oto przykład tworzenia szablonu <BalloonStyle> dla pola golfowego. W przypadku każdego dymka oznaczenia miejsca Google Earth zastępuje nazwę oznaczenia miejsca, a następnie zapisuje informacje o numerze, parze i siatce dla każdego otworu:
<?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>
Oto przykładowy zrzut ekranu:
Przykładowe użycie danych z użyciem domyślnego stylu dymków
![](https://developers-dot-devsite-v2-prod.appspot.com/static/kml/documentation/images/GolfCourse2.gif?authuser=9&hl=pl)
Oto bardziej realistyczny przykład użycia elementu <displayName>. Ta technika nadaje się do zlokalizowanego tekstu i ma bardziej rozbudowane formatowanie.
<?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>
Oto przykład balonu z tego szablonu:
![](https://developers-dot-devsite-v2-prod.appspot.com/static/kml/documentation/images/GolfCourse3.gif?authuser=9&hl=pl)
Dodawanie wpisywanych danych do obiektu
Elementy <Schema> i <SchemaData> umożliwiają dodawanie do obiektu danych wpisywanych. Niektóre aplikacje GIS i programy wymagają tej funkcji, ponieważ obsługują one wpisywane dane.
Omówienie dodawania wpisywanych danych
Aby dodać typ niestandardowy do funkcji KML, musisz wykonać 2 podstawowe zadania:
- Utwórz element <Schema>, który deklaruje nowy typ.
- Utwórz instancje nowego typu za pomocą elementu <SchemaData>.
Zadeklarowanie elementu schematu
Element schema.org deklaruje typ uporządkowanych danych. <Schema> jest zawsze podrzędny wobec elementu <Document>. Dokument może zawierać 0 lub więcej elementów schematu.
Atrybut id
Element <Schema> ma zawsze atrybut „identyfikator”, a informacje o tym są wywoływane podczas tworzenia wystąpień tego typu (przy użyciu elementu <SchemaData>). Ten identyfikator musi być unikalny w pliku KML.
Nazwa atrybutu
Atrybut name, który służy do zastępowania encji, jest opcjonalny.
Składnia
Element schema.org ma taką składnię:
<Schema name="string" id="ID"> <SimpleField type="string" name="string"> <displayName>...</displayName> <!-- string --> </SimpleField> </Schema>
Element <SimpleField> zawsze ma atrybuty name oraz type. Jeśli nie ma obu atrybutów, pole jest ignorowane. Atrybut name służy do zastępowania encji w elemencie <text> tagu <BalloonStyle>. Typem pola prostego może być jeden z tych typów:
string
int
uint
short
ushort
float
double
bool
Zdefiniuj każde wystąpienie danych
Użyj elementu <SchemaData>, aby utworzyć instancję typu zdefiniowanego przez użytkownika. Składnia <SchemaData> jest taka:
<ExtendedData> <SchemaData schemaUrl="anyURI"> <SimpleData name=""> ... </SimpleData> <!-- string --> </SchemaData> </ExtendedData>
Atrybut schemaUrl odwołuje się do id schematu, który deklaruje jego typ (tak samo jak styleUrl odwołuje się do id stylu, który został już zadeklarowany).Jeśli schemaUrl jest adresem http, Google Earth pobierze ten plik w sieci. Na oznaczenie miejsca może występować tylko jedno wystąpienie danego typu zdefiniowanego przez użytkownika.
Przykład
W poniższym przykładzie określono deklarowany przez użytkownika typ o nazwie ScenicVista. Ten typ zawiera 3 pola: TrailheadName, TrailLength i ElevationIncrease. Pole TrailheadName zawiera wartości typu string
. Pole TrailLengt h zawiera wartości typu double
. Pole ElevationIncrease zawiera wartości typu int
. Oznaczenie miejsca o nazwie Łatwe śledzenie zawiera instancję tego typu użytkownika. Ta wartość ma w polu TrailHeadName wartość „Pi in sky”, wartość 3, 14159 w polu TrailLength i 10 w polu ElevationIncrease.
<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>
Przykład schematu schema.org przy użyciu domyślnego stylu dymków
![](https://developers-dot-devsite-v2-prod.appspot.com/static/kml/documentation/images/SchemaTrails2.gif?authuser=9&hl=pl)
Zamiennik elementu displayName
Mechanizm Schema/SchemaData obsługuje też zastępowanie elementu w elemencie <text> elementu <BalloonStyle>.
Element <displayName> w <Schema> umożliwia udostępnienie przyjaznej dla użytkownika wersji niestandardowego typu danych. Zmienienie ciągu znaków w <Schemat> ma wpływ na wartość <displayName> dla wszystkich obiektów zawierających ten typ.
W elemencie <text> elementu <BalloonStyle> stosuj poniższą składnię, aby zakwalifikować element <displayName>:
$[TYPENAME/TYPEFIELD/displayName]
gdzie
- TYP
- to atrybut name atrybutu <Schema>
- TYPEFIELD
- to atrybut name elementu <SimpleField>
- wyświetlanaNazwa
- to element <displayName> w <SimpleField>
Poniższy kod dodaje szablon BalloonStyle do poprzedniego przykładu SchemaData. Tak jak w przykładzie z polem golfowym, szablon zostanie utworzony z użyciem elementów <Style>, <BalloonStyle> i <text> na początku dokumentu. Każde oznaczenie miejsca w pliku odwołuje się do tego szablonu stylu (noszącego nazwę „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>
Przykład schema.org przy użyciu szablonu BalloonStyle
Porównaj dymek utworzony za pomocą szablonu BalloonStyle z domyślnym stylem dymków w przypadku tych samych danych co podczas poprzedniego zrzutu ekranu.
![](https://developers-dot-devsite-v2-prod.appspot.com/static/kml/documentation/images/schemaTrails.gif?authuser=9&hl=pl)
Dodawanie dowolnych danych XML do funkcji
Najprostszym sposobem dodania danych użytkownika do funkcji jest dodanie ich bezpośrednio jako wartości <ExtendedData>. Google Earth zachowuje dane, ale ich nie przetwarza.
Niestandardowe elementy danych dodawane w ten sposób muszą zawierać prefiks prefiksu (xmlns:prefix="namespace”). Ten prefiks można dodać do elementu <json> lub do elementu <ExtendedData>. Prefiks zewnętrznej przestrzeni nazw musi kwalifikować się do każdego wystąpienia danych użytkownika, jak w tym przykładzie:
<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>