تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إضافة بيانات مخصصة

يوفر KML ثلاث طرق لإضافة بيانات مخصصة إلى ميزة KML. يتوقف الأسلوب الذي تختاره على نوع البيانات التي تضيفها وكذلك على كيفية تخطيطك لاستخدام البيانات في العرض التقديمي بتنسيق KML. على وجه التحديد، يوفر عنصر <ExtendedData> الآليات التالية:

>البيانات> - يسمح لك بإضافة أزواج الاسم/القيمة غير المكتوبة إلى بيانات المستخدم المرتبطة بميزة معينة (NetworkLink، أو علامة موضعية، أو GroundOverlay، أو PhotoOverlay، أو ScreenOverlay، أو Document، أو Folder). يتم عرض أزواج الاسم/القيمة هذه في البالون تلقائيًا. يمكن استخدام هذه المعلومات أيضًا لاستبدال الكيان في العنصر <text> في <BalloonStyle>. (راجع القسم الذي يتناول استخدام عنصر BalloonStyle كنموذج.)
عناصر <Schema> و<SchemaData> - تتيح لك إضافة بيانات مكتوبة إلى بيانات المستخدم المقترنة بميزة معينة.
بيانات XML عشوائية - تسمح لك بالاحتفاظ ببيانات المستخدم داخل ملف KML. يمرر برنامج Google Earth هذه البيانات مع الملف ويحفظها ولكن لا يستخدمها.

ملاحظة: يمكن الجمع بين هذه الآليات الثلاث في ملف واحد. إذا كنت تضيف أنواعًا مختلفة من البيانات من مصادر مختلفة، قد يكون من المناسب استخدام الأسلوب المكتوب للبيانات (المخطط/مخطط البيانات) لبعض البيانات المخصصة واستخدام البيانات غير المكتوبة (البيانات) للبيانات المخصصة الأخرى.

ما هو المنهج الذي يجب استخدامه؟

في معظم الحالات، يوفر العنصر <Data> أبسط وأقوى آلية لإضافة بيانات untyped إلى ميزة KML. هذه الطريقة سهلة التنفيذ نسبيًا، وتقدم ميزة تسهيل استخدام نموذج BalloonStyle، والذي يمكن تطبيقه على جميع العلامات الموضعية في ملف KML. (يُرجى الاطِّلاع على استبدال الكيان لعناصر البيانات الموسَّعة للحصول على مثال على هذا الاستخدام.)

يتيح لك عنصرا <Schema> و schema.> إضافة بيانات المستخدم المكتوبة. ويتم تقديم هذه العناصر بشكل أساسي للمستخدمين الذين لديهم بيانات حول نظم المعلومات الجغرافية (GIS). إذا كتبت بيانات يستخدمها تطبيق كمبيوتر خارجي، فمن المحتمل أن تحتاج إلى استخدام عنصري <Schema> و<SchemaData> لإضافة أنواع بيانات منظمة إلى ميزة. (لا يستخدم برنامج Google Earth هذه المعلومات المكتوبة، ولكن التطبيق الآخر قد يطلبها.) ربما لا يحتاج المستخدمون العاديون إلى مزيد من الجوانب التقنية التي تعرضها هذه الآلية. مثل <Data>، يسهل Schema.> استخدام النماذج لـ 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 وروابط تشعّبية.

في ما يلي مثال لعلامة موضعية تحتوي على بيانات مخصصة حول عدة ثقوب في ملعب غولف:

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

يوضح التقاط الشاشة هذا كيفية عرض عناصر <البيانات> افتراضيًا في جدول في بالون العلامة الموضعية:

مثال على البيانات باستخدام النمط التلقائي للبالون

مراجعة: استخدام عنصر BalloonStyle كنموذج

في ملف KML، يمكنك تحديد نمط مرة واحدة وتعيين معرف له. بعد تحديد النمط بهذه الطريقة، يمكنك الرجوع إليه عدة مرات داخل ملف KML (أو داخل ملفات KML أخرى) باستخدام العنصر <styleUrl>. ويُشار إلى النمط المحدد بهذه الطريقة باسم النمط المشترك. يدعم العنصر <text> ضمن <BalloonStyle> استبدال الكيان. يمكن استبدال القيم الفردية لكل مثيل من كيان. في ما يلي الكيانات القياسية التي يمكن استبدالها:

$[name]: تم استبداله باسم العلامة الموضعية
$[description]: تم استبداله بـ وصف العلامة الموضعية
$[address]: تم استبداله بالعنوان للعلامة الموضعية
$[id]: تم استبداله برقم تعريف العلامة الموضعية
$[مقتطف]: تم استبداله بمقتطف العلامة الموضعية
$[geDirections]: تم استبداله باتجاهات القيادة إلى/من العلامة الموضعية

استبدال الكيان لعناصر البيانات الموسّعة

يدعم Google Earth أيضًا استبدال بعض عناصر البيانات الموسعة داخل عنصر <text> من <BalloonStyle>. يمكن الإشارة إلى الكيانات التالية داخل العنصر <text>:

متغير	تم الاستبدال بـ	مثال
$[name_attribute_of_Data_element]	محتويات عنصر <value>	NumberNumber، holeYardage
$[name_attribute_of_Data/displayName]	محتويات عنصر <displayName>	رقم الفتحة، Hole Yardage

في ما يلي مثال يؤدي إلى إنشاء نموذج <BalloonStyle> لمثال عن ملعب الغولف. بالنسبة إلى كل بالون علامة موضعية، يحل برنامج Google Earth محل اسم العلامة الموضعية ثم يكتب المعلومات التي تحتوي على رقم الفتحة والكسر وعدد الياردات لكل ثقب على حدة:

<?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> إضافة بيانات مكتوبة إلى ميزة. تتطلب بعض تطبيقات نظم المعلومات الجغرافية والبرمجة هذه الميزة نظرًا لأنها تتعامل مع البيانات المكتوبة.

نظرة عامة على إضافة البيانات المكتوبة

لإضافة نوع مخصص إلى ميزة KML، يمكنك إجراء مهمتين أساسيتين:

أنشئ العنصر <Schema> الذي يعلن عن النوع الجديد.
أنشئ مثيلات من النوع الجديد باستخدام العنصر <SchemaData>.

تحديد عنصر المخطط

يعلن عنصر المخطط عن نوع منظم. يكون دائمًا <Schema> عنصرًا فرعيًا لـ <Document>. يمكن أن يحتوي المستند على صفر أو أكثر من عناصر المخطط.

سمة المعرّف

عنصر <Schema> يحتوي دائمًا على سمة رقم تعريف، وتتم الإشارة إليه عندما يتم إنشاء نُسخ من هذا النوع (باستخدام <SchemaData>). ويجب أن يكون هذا المعرّف فريدًا داخل ملف KML.

سمة الاسم

تُعد السمة name، التي يتم استخدامها لاستبدال الكيان، اختيارية.

البنية

يحتوي عنصر المخطط على البنية التالية:

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

يحتوي SimpleSimple دائمًا على سمتَي name وtype. وفي حال عدم توفّر السمتَين معًا، سيتم تجاهل الحقل. يتم استخدام سمة الاسم لاستبدال الكيان في العنصر <text> في <BalloonStyle>. يمكن أن يكون نوع Simplefield أحد الخيارات التالية:

string
int
uint
short
ushort
float
double
bool

تحديد كل مثيل من البيانات

استخدم عنصر Schema.> لإنشاء مثيل من النوع الذي يحدده المستخدم. تكون بنية <SchemaData> على النحو التالي:

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

تشير السمة schemaUrl إلى id في المخطط الذي يعلن عن النوع (تمامًا كما يشير styleUrl إلى معرّف النمط الذي تم الإعلان عنه من قبل).وإذا كان schemaUrl عنوان http، يجلب برنامج Google Earth هذا الملف عبر الشبكة. يمكن أن يكون هناك مثال واحد فقط من نوع معين يحدده المستخدم لكل علامة موضعية.

مثال

ويوضح المثال التالي نوعًا من تحديد المستخدم يُسمى ScenicVista. يحتوي هذا النوع على ثلاثة حقول: TrailheadName وTilLength وElevationearn. يحتوي الحقل TrailHeadName على قيم من النوع string. يحتوي حقل TrailLength على قيم من النوع double. يحتوي الحقل Elevationearn (نوع الزيادة) على قيم من النوع int. تحتوي العلامة الموضعية المسماة الممر السهل على مثال لهذا النوع من المستخدمين. يحتوي هذا المثيل على قيمة "Pi in the sky" للحقل TrailHeadName والقيمة 3.14159 للحقل TrailLength وقيمة 10 للحقل Elevationearn.

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

حيث

TYPENAME: هي السمة name لـ [Schema>
TYPEFIELD: هي السمة name لـ SimpleSimple>
اسم العرض: هو عنصر <displayName> ضمن <SimpleField>

تضيف الشفرة التالية نموذج BalloonStyle إلى مثال SchemaData السابق. كما في مثال ملعب الغولف، يتم إنشاء النموذج باستخدام عناصر <النمط>، و<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>

مثال على schemaData باستخدام نموذج BalloonStyle

قارن البالون الذي تم إنشاؤه باستخدام نموذج بالون نمط بنمط البالون الافتراضي للبيانات نفسها المعروضة في لقطة الشاشة السابقة.

إضافة بيانات XML عشوائية إلى ميزة

إن أبسط طريقة لإضافة بيانات المستخدم إلى الميزة هي إضافة البيانات مباشرة كقيمة <ExtendedData>. ويحتفظ برنامج Google Earth بهذه البيانات ولكنه لا يعالجها.

ويجب أن تتضمّن عناصر البيانات المخصّصة المضافة بهذه الطريقة بادئة namespace (xmlns:prefix="namespace). يمكن إضافة هذه البادئة إلى العنصر <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>

الرجوع إلى أعلى الصفحة