این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

افزودن داده های سفارشی

KML سه راه برای افزودن داده های سفارشی به یک ویژگی KML ارائه می دهد. اینکه کدام رویکرد را انتخاب می‌کنید به نوع داده‌هایی که اضافه می‌کنید و همچنین نحوه استفاده از داده‌ها در ارائه KML بستگی دارد. به طور خاص، عنصر <ExtendedData> مکانیسم های زیر را ارائه می دهد:

عنصر <داده> - به شما امکان می دهد جفت نام/مقدار تایپ نشده را به داده های کاربر مرتبط با یک ویژگی خاص (شبکه پیوند، علامت مکان، روکش زمین، پوشش عکس، پوشش صفحه، سند یا پوشه) اضافه کنید. این جفت‌های نام/مقدار به‌طور پیش‌فرض در بالون نمایش داده می‌شوند. این اطلاعات همچنین می تواند برای جایگزینی موجودیت در عنصر <text> <BalloonStyle> استفاده شود. (به بخش استفاده از عنصر BalloonStyle به عنوان الگو مراجعه کنید.)
عناصر <Schema> و <SchemaData> - به شما امکان می دهند داده های تایپ شده را به داده های کاربر مرتبط با یک ویژگی خاص اضافه کنید.
داده های XML دلخواه - به شما امکان می دهد داده های کاربر را در یک فایل KML حفظ کنید. Google Earth این داده ها را به همراه فایل ارسال می کند و ذخیره می کند، اما از آن استفاده نمی کند.

نکته: این سه مکانیسم را می توان در یک فایل ترکیب کرد. اگر انواع مختلفی از داده‌ها را از منابع مختلف اضافه می‌کنید، ممکن است استفاده از رویکرد داده‌های تایپ‌شده (Schema/SchemaData) برای برخی از داده‌های سفارشی و استفاده از داده‌های تایپ نشده (داده) برای سایر داده‌های سفارشی مناسب باشد.

از کدام رویکرد باید استفاده کنید؟

در بیشتر موارد عنصر <Data> ساده ترین و قوی ترین مکانیسم را برای افزودن داده های تایپ نشده به یک ویژگی KML ارائه می دهد. پیاده‌سازی این روش نسبتاً آسان است و مزیت استفاده از یک الگوی BalloonStyle را تسهیل می‌کند که می‌تواند برای همه Placemarks در یک فایل KML اعمال شود. (برای مثالی از این استفاده، Entity Replacement for Extended Data Elements را ببینید.)

عناصر <Schema> و <SchemaData> به شما اجازه می دهند تا داده های کاربر تایپ شده را اضافه کنید. این عناصر در درجه اول برای کاربران با داده های GIS (سیستم اطلاعات جغرافیایی) ارائه می شود. اگر داده‌هایی را تایپ کرده‌اید که توسط یک برنامه کامپیوتری خارجی استفاده می‌شود، احتمالاً باید از عناصر <Schema> و <SchemaData> برای افزودن انواع داده‌های ساخت‌یافته به یک ویژگی استفاده کنید. (Google Earth از این اطلاعات تایپ شده استفاده نمی کند، اما برنامه دیگر شما ممکن است به آن نیاز داشته باشد.) کاربران معمولی احتمالاً به جنبه های فنی بیشتری که توسط این مکانیسم ارائه می شود نیاز ندارند. مانند <Data>، <SchemaData> استفاده از الگوها را برای BalloonStyle تسهیل می کند.

اگر به سادگی نیاز به ارسال داده به همراه یک فایل KML دارید و برای پردازش داده ها به Google Earth نیاز ندارید، از ویژگی داده دلخواه XML استفاده کنید، که به شما امکان می دهد به پیشوند فضای نام XML ارجاع دهید و داده ها را در زمینه KML فعلی منتقل کنید. برای اطلاعات بیشتر، به بخش داده‌های XML دلخواه مراجعه کنید.

افزودن جفت نام/مقدار تایپ نشده

عنصر <Data> یک مکانیسم ساده و در عین حال قدرتمند برای افزودن جفت نام/مقدار تایپ نشده به یک ویژگی KML است. نحو این عنصر به شرح زیر است:

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

ویژگی name یک شناسه منحصر به فرد برای این قطعه داده است. عنصر <displayName> زمانی استفاده می شود که می خواهید نام این داده ها را به شکل کاربر پسند نمایش دهید. <displayName> می‌تواند حاوی CDATA باشد که شامل فضاها، URLها و لینک‌ها می‌شود.

در اینجا نمونه ای از 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> به‌طور پیش‌فرض در جدولی در بالون Placemark نمایش داده می‌شوند:

مثال داده با استفاده از یک ظاهر طراحی پیش فرض برای بالون

بررسی: استفاده از عنصر BalloonStyle به عنوان یک الگو

در KML می توانید یک Style را یک بار تعریف کنید و یک ID به آن اختصاص دهید. پس از تعریف Style به این روش، می توانید چندین بار در فایل KML (یا در سایر فایل های KML) با استفاده از عنصر <styleUrl> به آن ارجاع دهید. به سبکی که به این شکل تعریف می شود، سبک اشتراکی گفته می شود. عنصر <text> در <BalloonStyle> از جایگزینی موجودیت پشتیبانی می کند. مقادیر فردی را می توان برای هر نمونه از موجودیت جایگزین کرد. موجودیت های استاندارد قابل تعویض به شرح زیر است:

$[name]: با نام Placemark جایگزین شد
$[توضیحات]: با توضیحات Placemark جایگزین شد
$[آدرس]: با آدرس Placemark جایگزین شد
$[id]: با شناسه Placemark جایگزین شد
$[Snippet]: با قطعه علامت مکان جایگزین شد
$[geDirections]: با مسیرهای رانندگی به/از علامت مکان جایگزین شده است

جایگزینی نهاد برای عناصر داده توسعه یافته

Google Earth همچنین از جایگزینی موجودیت برخی از عناصر داده توسعه یافته در عنصر <text> <BalloonStyle> پشتیبانی می کند. موجودیت های زیر را می توان در عنصر <text> ارجاع داد:

متغیر	جایگزین شده با	مثال
$[name_ attribute_of_Data_element]	محتویات عنصر <value>	holeNumber، holeYardage
$[ name _attribute_of_Data/ displayName ]	محتویات عنصر <displayName>	شماره سوراخ، حفره یارداژ

در اینجا یک مثال است که یک الگوی <BalloonStyle> برای مثال زمین گلف ایجاد می کند. برای هر بالون Placemark، Google Earth نام Placemark را جایگزین می‌کند و سپس اطلاعاتی را که شامل شماره سوراخ، همتراز و یارداژ هر سوراخ جداگانه است می‌نویسد:

<?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، دو کار اساسی را انجام می دهید:

عنصر <Schema> را ایجاد کنید که نوع جدید شما را اعلام می کند.
نمونه هایی از نوع جدید را با استفاده از عنصر <SchemaData> ایجاد کنید.

عنصر Schema را اعلام کنید

عنصر Schema یک نوع ساختار یافته را اعلام می کند. <Schema> همیشه فرزند <Document> است. یک سند می تواند حاوی صفر یا چند عنصر Schema باشد.

ویژگی id

عنصر <Schema> همیشه دارای یک ویژگی id است که در هنگام ایجاد نمونه هایی از این نوع (با استفاده از <SchemaData>) به آن ارجاع داده می شود. این شناسه باید در فایل KML منحصر به فرد باشد.

نام صفت

ویژگی name که برای جایگزینی موجودیت استفاده می شود، اختیاری است.

نحو

عنصر Schema دارای نحو زیر است:

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

یک <SimpleField> همیشه دارای هر دو ویژگی نام و نوع است. اگر هر دو ویژگی را نداشته باشد، فیلد نادیده گرفته می شود. ویژگی name برای جایگزینی موجودیت در عنصر <text> <BalloonStyle> استفاده می شود. نوع Simplefield می تواند یکی از موارد زیر باشد:

string
int
uint
short
ushort
float
double
bool

هر نمونه از داده ها را تعریف کنید

از عنصر <SchemaData> برای ایجاد نمونه ای از نوع تعریف شده توسط کاربر استفاده کنید. نحو برای <SchemaData> به شرح زیر است:

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

ویژگی schemaUrl به شناسه Schema که نوع را اعلام می کند ارجاع می دهد (همانطور که styleUrl به شناسه سبکی که قبلاً اعلام شده است ارجاع می دهد). اگر schemaUrl یک آدرس http باشد، Google Earth این فایل را در سراسر شبکه واکشی می کند. تنها یک نمونه از یک نوع مشخص شده توسط کاربر در هر مکان نشان می‌تواند وجود داشته باشد.

مثال

مثال زیر یک نوع تعریف شده توسط کاربر به نام ScenicVista را اعلام می کند. این نوع شامل سه فیلد است: TrailHeadName، TrailLength و ElevationGain . فیلد TrailHeadName حاوی مقادیری از نوع string است. فیلد TrailLengt h حاوی مقادیری از نوع 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 همچنین از جایگزینی موجودیت در عنصر <text> عنصر <BalloonStyle> پشتیبانی می کند.

<displayName> <Schema> به شما امکان می دهد یک نسخه کاربرپسند برای یک نوع داده سفارشی ارائه دهید. تغییر رشته یک بار در <Schema> باعث تغییر <displayName> برای همه ویژگی هایی می شود که دارای آن نوع هستند.

در عنصر <text> عنصر <BalloonStyle>، از نحو زیر برای واجد شرایط بودن <displayName> استفاده کنید:

$[TYPENAME/TYPEFIELD/displayName]

جایی که

اسم را تایپ کن: ویژگی نام <Schema> است
TYPEFIELD: ویژگی نام <SimpleField> است
نمایش نام: عنصر <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>    
  <!-- 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>

مثال SchemaData با استفاده از الگوی BalloonStyle

بالون ایجاد شده با استفاده از یک الگوی BalloonStyle را با سبک بالون پیش‌فرض برای همان داده‌هایی که در تصویربرداری صفحه قبلی نشان داده شده است، مقایسه کنید.

افزودن داده های XML دلخواه به یک ویژگی

ساده ترین راه برای افزودن داده های کاربر به یک ویژگی این است که داده ها را مستقیماً به عنوان مقدار <ExtendedData> اضافه کنید. Google Earth این داده ها را حفظ می کند اما آنها را پردازش نمی کند.

عناصر داده سفارشی اضافه شده به این روش باید شامل یک پیشوند فضای نام (xmlns:prefix=" فضای نام ") باشد. این پیشوند را می توان به عنصر <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>

بازگشت به بالا