KML cung cấp 3 cách để thêm dữ liệu tuỳ chỉnh vào một Tính năng KML. Phương pháp bạn chọn phụ thuộc vào loại dữ liệu bạn đang thêm cũng như cách bạn dự định sử dụng dữ liệu trong bản trình bày KML của mình. Cụ thể, phần tử <ExtendedData> cung cấp các cơ chế sau:
- Phần tử <Data> - cho phép bạn thêm các cặp tên/giá trị chưa nhập vào dữ liệu người dùng được liên kết với một Tính năng nhất định (NetworkLink, Timestamp, GroundOverlay, PhotoOverlay, ScreenOverlay, Document hoặc Thư mục). Theo mặc định, các cặp giá trị/tên này xuất hiện trong hộp chú giải. Thông tin này cũng có thể dùng để thay thế thực thể trong phần tử <text> của <BalloonStyle>. (Xem phần Sử dụng phần tử BalloonStyle làm mẫu.)
- Phần tử <Schema> và <SchemaData> – cho phép bạn thêm dữ liệu đã nhập vào dữ liệu người dùng được liên kết với một Tính năng nhất định.
- Dữ liệu XML tuỳ ý - cho phép bạn lưu giữ dữ liệu người dùng trong một tệp KML. Google Earth sẽ chuyển dữ liệu này cùng với tệp và lưu lại, nhưng không sử dụng nó.
Lưu ý: Bạn có thể kết hợp ba cơ chế này trong cùng một tệp. Nếu đang thêm các loại dữ liệu khác nhau từ các nguồn khác nhau, bạn nên sử dụng phương pháp nhập dữ liệu (Schema/SchemaData) cho một số dữ liệu tùy chỉnh và sử dụng dữ liệu chưa nhập (Dữ liệu) cho dữ liệu tùy chỉnh khác.
Bạn nên áp dụng phương pháp tiếp cận nào?
Trong hầu hết các trường hợp, phần tử <Data> cung cấp cơ chế đơn giản và hiệu quả nhất để thêm dữ liệu chưa nhập vào Tính năng KML. Phương pháp này tương đối dễ triển khai và phương pháp này mang lại lợi thế là tạo điều kiện sử dụng mẫu BalloonStyle, có thể áp dụng cho tất cả các Dấu vị trí trong tệp KML. (Xem bài viết Thay thế thực thể cho Phần tử dữ liệu mở rộng để tham khảo ví dụ về cách sử dụng này.)
Các phần tử <Schema> và <SchemaData> cho phép bạn thêm dữ liệu người dùng được nhập. Các phần tử này chủ yếu được cung cấp cho người dùng có dữ liệu GIS (Hệ thống thông tin địa lý). Nếu bạn đã nhập dữ liệu mà một ứng dụng máy tính bên ngoài sử dụng, thì có thể bạn sẽ phải dùng các phần tử <Schema> và <SchemaData> để thêm các loại dữ liệu có cấu trúc vào một Tính năng. (Google Earth không sử dụng thông tin được nhập này, nhưng ứng dụng khác của bạn có thể yêu cầu thông tin đó.) Người dùng thông thường có thể sẽ không cần thêm các khía cạnh kỹ thuật do cơ chế này cung cấp. Giống như <Data>, <SchemaData> hỗ trợ việc sử dụng mẫu cho BalloonStyle.
Nếu bạn chỉ cần truyền dữ liệu cùng với tệp KML và không cần Google Earth để xử lý dữ liệu, hãy sử dụng tính năng dữ liệu XML tuỳ ý để cho phép bạn tham chiếu đến tiền tố không gian tên XML và truyền dữ liệu trong ngữ cảnh KML hiện tại. Để biết thêm thông tin, hãy xem phần nội dung về Dữ liệu XML tuỳ ý.
Thêm cặp tên/giá trị chưa nhập
Phần tử <Data> là một cơ chế đơn giản nhưng mạnh mẽ để thêm các cặp giá trị/tên chưa nhập vào một Tính năng KML. Cú pháp cho phần tử này như sau:
<ExtendedData>
<Data name="string">
<displayName>...</displayName> <!-- string -->
<value>...</value> <!-- string -->
</Data> </ExtendedData>
Thuộc tính name là mã nhận dạng duy nhất cho phần dữ liệu này. Phần tử <displayName> được dùng khi bạn muốn hiển thị tên của dữ liệu này ở dạng thân thiện với người dùng. <displayName> có thể chứa InMobi chứa dấu cách, URL và siêu liên kết.
Dưới đây là ví dụ về Dấu vị trí chứa dữ liệu tùy chỉnh về một số lỗ trong sân gôn:
<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>
Ảnh chụp màn hình này hiển thị cách các phần tử <Data> được hiển thị trong một bảng trong hộp chú giải của Dấu vị trí theo mặc định:
Ví dụ về dữ liệu sử dụng kiểu mặc định cho hộp chú giải
![](https://developers-dot-devsite-v2-prod.appspot.com/static/kml/documentation/images/GolfCourse1.gif?authuser=5&hl=vi)
Xem xét: Sử dụng phần tử BalloonStyle làm mẫu
Trong KML, bạn có thể xác định Kiểu một lần và gán mã nhận dạng cho kiểu đó. Sau khi xác định Kiểu theo cách này, bạn có thể tham chiếu đến văn bản đó nhiều lần trong tệp KML (hoặc trong các tệp KML khác) bằng phần tử <styleUrl>. Kiểu được xác định theo cách này được gọi là kiểu dùng chung. Phần tử <text> trong <BalloonStyle> hỗ trợ thay thế thực thể. Bạn có thể thay thế các giá trị riêng lẻ cho từng bản sao của thực thể. Các thực thể chuẩn có thể được thay thế như sau:
- $[tên]
- Đã thay thế bằng tên của Dấu vị trí
- $[description]
- Đã thay thế bằng nội dung mô tả của Dấu vị trí
- $[địa chỉ]
- Đã thay thế bằng địa chỉ của Dấu vị trí
- [mã]
- Đã thay thế bằng mã của Dấu vị trí
- $[Đoạn mã]
- Đã thay thế bằng Đoạn mã của Dấu vị trí
- $[geDirections]
- Đã thay thế bằng thông tin chỉ đường đến/từ đường đi của Dấu vị trí
Thay thế thực thể cho phần tử dữ liệu mở rộng
Google Earth cũng hỗ trợ thay thế thực thể của một số phần tử dữ liệu mở rộng nhất định trong phần tử <text> của <BalloonStyle>. Các thực thể sau có thể được tham chiếu trong phần tử <text>:
Biến | Đã thay thế bằng | Ví dụ: |
---|---|---|
$[name_attribute_of_Data_element] | Nội dung của phần tử <value> | lỗ số |
$[tên_attribute_of_Data/displayName] | Nội dung của phần tử <displayName> | Số lỗ, âm tường |
Sau đây là ví dụ về việc tạo mẫu <BalloonStyle> cho ví dụ về sân gôn. Đối với mỗi bong bóng Dấu vị trí, Google Earth thay thế tên của Dấu vị trí, sau đó ghi lại thông tin chứa số lỗ, dấu phân chia và kích thước cho từng lỗ riêng lẻ:
<?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>
Sau đây là ảnh chụp màn hình của ví dụ này:
Ví dụ về dữ liệu sử dụng kiểu mặc định cho hộp chú giải
![](https://developers-dot-devsite-v2-prod.appspot.com/static/kml/documentation/images/GolfCourse2.gif?authuser=5&hl=vi)
Sau đây là một ví dụ thực tế hơn về cách sử dụng phần tử <displayName>. Kỹ thuật này hỗ trợ bản địa hoá văn bản và định dạng phức tạp hơn.
<?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>
Dưới đây là ví dụ về hộp chú giải sử dụng mẫu kiểu hộp chú giải này:
![](https://developers-dot-devsite-v2-prod.appspot.com/static/kml/documentation/images/GolfCourse3.gif?authuser=5&hl=vi)
Thêm dữ liệu đã nhập vào một tính năng
Các phần tử <Schema> và <SchemaData> cho phép bạn thêm dữ liệu đã nhập vào một Tính năng. Một số ứng dụng GPS và lập trình nhất định yêu cầu tính năng này vì chúng xử lý dữ liệu đã nhập.
Tổng quan về cách thêm dữ liệu được nhập
Để thêm loại tùy chỉnh vào một Tính năng KML, bạn thực hiện hai tác vụ cơ bản:
- Tạo phần tử <Schema> để khai báo loại mới của bạn.
- Tạo các thực thể của loại mới bằng phần tử <SchemaData>.
Khai báo phần tử của giản đồ
Phần tử Giản đồ khai báo loại có cấu trúc. <Schema> luôn là phần tử con của <Document>. Một tài liệu có thể chứa giá trị không hoặc nhiều phần tử Giản đồ.
Thuộc tính mã nhận dạng
Phần tử <Schema> luôn có thuộc tính id, whish được tham chiếu khi loại này được tạo (sử dụng <SchemaData>). ID này phải là duy nhất trong tệp KML.
Thuộc tính tên
Không bắt buộc phải có thuộc tính name (dùng để thay thế thực thể).
Cú pháp
Phần tử Giản đồ có cú pháp sau:
<Schema name="string" id="ID"> <SimpleField type="string" name="string"> <displayName>...</displayName> <!-- string --> </SimpleField> </Schema>
Một <SimpleField> luôn có cả thuộc tính name và type. Nếu không có cả hai thuộc tính này, thì trường sẽ bị bỏ qua. Thuộc tính tên được dùng để thay thế thực thể trong phần tử <text> của <BalloonStyle>. Loại của Simplefield có thể là một trong những loại sau:
string
int
uint
short
ushort
float
double
bool
Xác định từng bản sao của dữ liệu
Sử dụng phần tử <SchemaData> để tạo một bản sao của loại do người dùng xác định. Cú pháp cho <SchemaData> như sau:
<ExtendedData> <SchemaData schemaUrl="anyURI"> <SimpleData name=""> ... </SimpleData> <!-- string --> </SchemaData> </ExtendedData>
Thuộc tính schemaUrl tham chiếu đến id của Schema khai báo loại này (cũng giống như styleUrl tham chiếu đến id của style đã được khai báo).Nếu schemaUrl là một địa chỉ http, thì Google Earth sẽ tìm nạp tệp này trên mạng. Chỉ có thể có một bản sao của loại do người dùng xác định cho mỗi Dấu vị trí.
Ví dụ:
Ví dụ sau đây khai báo một loại do người dùng xác định có tên Scenic Vista. Loại này chứa ba trường: PathHeadName, TrailLength và ElevationReceive. Trường PathHeadName chứa các giá trị thuộc loại string
. Trường TrailLength chứa các giá trị thuộc loại double
. Trường ElevationReceive chứa các giá trị thuộc loại int
. Dấu vị trí có tên Đường nhỏ dễ dàng chứa một bản sao của loại người dùng này. Phiên bản này có giá trị "Pi in sky" cho trường PathHeadName, giá trị 3, 14159 cho trường PathLength và giá trị 10 cho trường ElevationReceive.
<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>
Ví dụ về SchemaData sử dụng kiểu mặc định cho hộp chú giải
![](https://developers-dot-devsite-v2-prod.appspot.com/static/kml/documentation/images/SchemaTrails2.gif?authuser=5&hl=vi)
Thay thế pháp nhân cho displayName
Cơ chế Schema/SchemaData cũng hỗ trợ thay thế thực thể trong phần tử <text> của phần tử <BalloonStyle>.
<displayName> của <Schema> cho phép bạn cung cấp phiên bản thân thiện với người dùng cho một loại dữ liệu tùy chỉnh. Việc thay đổi chuỗi một lần trong <Schema> có tác dụng thay đổi <displayName> cho tất cả các Tính năng chứa loại đó.
Trong phần tử <text> của phần tử <BalloonStyle>, hãy sử dụng cú pháp sau để đủ điều kiện thực hiện <displayName>:
$[TYPENAME/TYPEFIELD/displayName]
trong đó
- LOẠI CHIẾT KHẤU
- là thuộc tính name của <Schema>
- LOẠI LOẠI
- là thuộc tính name của <SimpleField>
- Tên hiển thị
- là phần tử <displayName> trong <SimpleField>
Mã sau đây thêm một mẫu BalloonStyle vào ví dụ về SchemaData trước. Như trong ví dụ về Sân gôn, mẫu được tạo bằng cách sử dụng các phần tử <Style>, <BalloonStyle> và <text> ở đầu tài liệu. Mỗi Dấu vị trí trong tệp tham chiếu đến mẫu kiểu này (có tên là "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>
Ví dụ về schemaData sử dụng mẫu BalloonStyle
So sánh hộp chú giải được tạo bằng mẫu BalloonStyle với kiểu bong bóng mặc định cho cùng dữ liệu hiển thị trong ảnh chụp màn hình trước đó.
![](https://developers-dot-devsite-v2-prod.appspot.com/static/kml/documentation/images/schemaTrails.gif?authuser=5&hl=vi)
Thêm dữ liệu XML tuỳ ý vào một tính năng
Cách đơn giản nhất để thêm dữ liệu người dùng vào một Tính năng là thêm dữ liệu trực tiếp dưới dạng giá trị của <ExtendedData>. Google Earth lưu giữ dữ liệu này nhưng không xử lý dữ liệu.
Các phần tử dữ liệu tùy chỉnh được thêm theo cách này cần phải có tiền tố không gian tên (xmlns:prefix="namespace"). Bạn có thể thêm tiền tố này vào phần tử <sftp> hoặc phần tử <ExtendedData>. Tiền tố không gian tên bên ngoài phải đủ điều kiện cho từng bản sao dữ liệu người dùng, như trong ví dụ sau:
<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>