بنية مستند مستندات Google

يصف هذا الدليل البنية الداخلية لمستند "مستندات Google": العناصر التي تتألف منها المستند والعلاقة بينها.

عناصر المستوى الأعلى

تتضمن عناصر المستوى الأعلى للمستند النص الأساسي والعديد من السمات الأخرى للمستند ككل:

document: {
    body: ... ,
    documentStyle: ... ,
    lists: ... ,
    documentId: ... ,
    namedStyles: ... ,
    revisionId: ... ,
    title: ...
}

لمعالجة ميزات المستند العامة خارج محتوى النص الأساسي، من الأفضل دائمًا استخدام نموذج مستند واحد أو أكثر، والذي يمكنك استخدامه كأساس لإنشاء مستندات جديدة برمجيًا.

محتوى الرسالة

معظم العناصر التي يمكنك، أو من المرجح أن ترغب في استخدامها آليًا، هي عناصر ضمن محتوى النص:

رسم بياني لمحتوى النص الأساسي

العناصر الهيكلية

محتوى النص الأساسي ما هو إلا تسلسل من كائنات StructuralElement. يخصّص عنصر المحتوى كل عنصر StructuralElement، كما هو موضّح في الرسم التخطيطي التالي:

رسم تخطيطي للعناصر الهيكلية.

تحتوي العناصر الهيكلية وكائنات المحتوى الخاصة بها على كل نص المستند والصور المضمنة وما إلى ذلك.

تحتوي الفقرات على نوع خاص من العناصر يُسمى ParagraphElement، ويعمل على غرار StructuralElement. تخصِّص مجموعة من أنواع عناصر المحتوى ParagraphElement الخاصة بها، كما هو موضَّح في الرسم البياني التالي:

رسم تخطيطي لعناصر الفقرة

للحصول على مثال حول بنية مستند كاملة، يمكنك الاطّلاع على نموذج نَسْخ المستند بتنسيق JSON. في الإخراج، يمكنك رؤية العديد من العناصر الأساسية وعناصر المحتوى، بالإضافة إلى استخدام فهارس البداية والنهاية كما هو موضّح في القسم التالي.

فهرس البداية والنهاية

وتحتوي معظم العناصر في محتوى النص على السمتَين startIndex وendIndex. تشير هذه إلى إزاحة بداية العنصر ونهايته، بالنسبة إلى بداية الجزء المحيط به.

يتم قياس الفهارس بوحدات رموز UTF-16. وهذا يعني أن الأزواج البديلة تستهلك فهرسين. على سبيل المثال، الرمز التعبيري "GRINNING FACE" (جيب)، سيتم استخدامه على النحو التالي "\uD83D\uDE00" وسيتم استهلاك فهرسَين.

بالنسبة للعناصر داخل نص المستند، تمثل الفهارس إزاحة من بداية محتوى النص، وهو عنصر "الجذر".

إنّ أنواع "التخصيص" للعناصر الهيكلية، SectionBreak وTableOfContents وTable وParagraph، لا تتوفّر هذه الفهارس لأنّ StructuralElement تضمينها تحتوي على هذه الحقول. ينطبق هذا أيضًا على أنواع التخصيص المضمنة في ParagraphElement.

بنية الفقرة

تتألف الفقرة مما يلي:

  • elements: تسلسل يحتوي على مثيل واحد أو أكثر من textRun.
  • paragraphStyle: عنصر اختياري يحدّد خصائص النمط للفقرة بوضوح.
  • bullet: عنصر اختياري يوفّر مواصفات التعداد النقطي إذا كانت الفقرة جزءًا من قائمة.

يتم تشغيل النص

تمثّل السمة textRun سلسلة نصية متجاورة بنمط النص نفسه. يمكن أن تحتوي الفقرة على أجزاء متعددة للنصوص ولكن لا يمكن أن تتخطى مساحات النص حدود الفقرة. فكر، على سبيل المثال، في مستند صغير مثل ما يلي:

يوضح الرسم التخطيطي التالي كيف يمكنك تصور تسلسل الفقرات في المستند أعلاه، ولكل منها عمليات النص الخاصة بها وإعدادات الرموز النقطية الاختيارية.

يتم تشغيل رسم تخطيطي للنص.

عناصر الوصول

هناك العديد من العناصر قابلة للتعديل باستخدام الطريقة BatchUpdate. على سبيل المثال، باستخدام نوع الطلب InsertTextRequest، يمكنك تعديل محتوى أي عنصر يحتوي على نص. وبالمثل، يمكنك استخدام UpdateTextStyleRequest لتطبيق التنسيق على نطاق من النصوص المضمَّنة في عنصر واحد أو أكثر.

لقراءة عناصر المستند، استخدِم طريقة get للحصول على نَسْخ JSON للمستند الكامل. (للحصول على طريقة لتنفيذ ذلك، راجع نموذج إخراج محتوى المستند بتنسيق JSON.) يمكنك بعد ذلك تحليل JSON الناتج للعثور على قيم العناصر الفردية.

يمكن أن يكون تحليل المحتوى مفيدًا في حالات استخدام مختلفة. فكر، على سبيل المثال، في أحد مستندات قائمة التطبيقات التي يعثر عليها. قد يريد هذا التطبيق استخراج العنوان ورقم تعريف النسخة السابقة ورقم صفحة البداية للمستند، كما هو موضح في الرسم التخطيطي التالي:

رسم تخطيطي لتطبيق فهرسة المستندات.

نظرًا لعدم وجود طرق لقراءة هذه الإعدادات بشكل صريح، يحتاج تطبيقك إلى الحصول على المستند بأكمله ثم تحليل JSON لاستخراج هذه القيم.