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

لاستخدام Google Docs API بفعالية، يجب فهم بنية مستند "مستندات Google" والعناصر التي يتكون منها المستند، بالإضافة إلى العلاقة بينها. تقدّم هذه الصفحة نظرة عامة تفصيلية على المواضيع التالية:

  • نموذج مفاهيمي لعناصر المستند
  • كيفية تمثيل Docs API لهذه العناصر
  • سمات التصميم للعناصر

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

عنصر الحاوية الأقصى في "مستندات Google" هو مستند. هذه هي الوحدة التي يمكن حفظها في Google Drive ومشاركتها مع مستخدمين آخرين وتعديلها باستخدام النصوص والصور.

تشمل عناصر المستوى الأعلى لمورد documents Tab، SuggestionsViewMode، وسمات أخرى:

document: {
    title: ... ,
    revisionId: ... ,
    documentId: ... ,
    suggestionsViewMode: ... ,
    tabs: ...
}

علامات التبويب

يمكن أن يحتوي مستند واحد على عدّة علامات تبويب، التي تتضمّن محتوًى مختلفًا على مستوى النص. سمة tabs للمستند هي تسلسل من عناصر Tab. يتكوّن Tab من الحقول التالية:

  • ‫TabProperties: يحتوي على سمات علامة التبويب، مثل المعرّف والعنوان والفهرس.
  • childTabs: لعرض علامات التبويب الفرعية لعلامة تبويب (علامات التبويب التي يتم تداخلها مباشرةً تحتها)
  • ‫DocumentTab: يمثّل محتوى نص علامة تبويب.
بنية علامات التبويب في المستند
الشكل 1. بنية علامات التبويب في المستند

تقدّم الأقسام اللاحقة نظرة عامة موجزة على التسلسل الهرمي لعلامات التبويب في المستند، كما تقدّم Tab تمثيل JSON أيضًا معلومات أكثر تفصيلاً. اطّلِع على العمل باستخدام علامات التبويب للحصول على مزيد من المعلومات عن ميزة علامات التبويب.

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

محتوى النص

يحتوي العنصر Body عادةً على المحتوى الكامل لعلامة تبويب المستند. إنّ معظم العناصر التي يمكنك استخدامها آليًا أو قد تحتاج إلى استخدامها بهذه الطريقة هي عناصر ضمن محتوى Body:

بنية محتوى النص
الشكل 2. بنية محتوى النص

عنصر هيكلي

يصف StructuralElement المحتوى الذي يقدّم بنية للمستند. محتوى Body هو تسلسل من StructuralElement عنصر. يخصّص عنصر المحتوى كل عنصر StructuralElement، كما هو موضّح في المخطّط البياني التالي:

العناصر الهيكلية
الشكل 3. العناصر الهيكلية

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

بنية الفقرة

Paragraph هو StructuralElement يمثّل فقرة. يحتوي على مجموعة من المحتوى الذي يتم إنهاؤه بحرف سطر جديد. وتتكوّن من العناصر التالية:

  • ParagraphElement: يصف المحتوى ضمن فقرة.
  • ‫ParagraphStyle: عنصر اختياري يحدّد بوضوح سمات الأسلوب للفقرة.
  • Bullet: إذا كان الفقرة جزءًا من قائمة، عنصر اختياري يقدّم مواصفات الفقرة.

يعمل ParagraphElement على نحو مشابه StructuralElement. تُخصّص مجموعة من أنواع عناصر المحتوى (مثل ColumnBreak و Equation) ParagraphElement الخاصة بها، كما هو موضّح في المخطّط البياني التالي:

بنية عناصر الفقرة
الشكل 4. بنية عناصر الفقرة

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

خطوط النص

TextRun هو ParagraphElement يمثّل سلسلة متّصلة من النصوص بنمط النص نفسه. يمكن أن يحتوي الفقرة على عدّة فقرات نصية، ولكن لا تتجاوز فقرات النص حدود الفقرة. يتم تقسيم المحتوى بعد حرف سطر جديد لإنشاء مجموعات ملفوظات نصية منفصلة. على سبيل المثال، فكِّر في مستند صغير مثل ما يلي:

مستند صغير يحتوي على فقرات وقائمة نقطية
الشكل 5. مستند صغير

يوضّح الرسم البياني التالي كيفية عرض تسلسل الفقرات في المستند السابق، ولكل فقرة إعدادات TextRun وBullet اختيارية.

بنية نص
الشكل 6. بنية نص

AutoText

AutoText هو ParagraphElement يمثّل مكانًا في النص يتم استبداله ديناميكيًا بمحتوى يمكن أن يتغيّر بمرور الوقت. في "مستندات Google"، يتم استخدام هذا الرمز لتحديد أرقام الصفحات.

مؤشّري البدء والانتهاء

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

تحتوي معظم العناصر ضمن محتوى النص الأساسي على السمتَين startIndex و endIndex اللتين تستندان إلى القيمة صفر. تشير هذه القيم إلى إزاحة بداية العنصر ونهايته، بالنسبة إلى بداية الجزء الذي يحويهما. لمزيد من المعلومات عن كيفية ترتيب طلبات البيانات المجمّعة من واجهة برمجة التطبيقات في "مستندات Google"، اطّلِع على تعديلات الطلبات المجمّعة.

يتم قياس الفهارس بوحدات ترميز UTF-16. وهذا يعني أنّ الأزواج البديلة تستهلك فهرسَين. على سبيل المثال، يتم تمثيل رمز الإيموجي "وجه مبتسم"، 😄، على النحو التالي: \uD83D\uDE00 ويستهلك فهرسَين.

بالنسبة إلى العناصر ضمن نص المستند، تمثّل الفهارس Offsets (الموضع النسبي) من بداية محتوى النص، وهو العنصر "الجذر".

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

الوصول إلى العناصر

يمكن تعديل العديد من العناصر باستخدام الطريقة documents.batchUpdate. على سبيل المثال، باستخدام InsertTextRequest، يمكنك تغيير محتوى أي عنصر يحتوي على نص. وبالمثل، يمكنك استخدام UpdateTextStyleRequest لتطبيق التنسيق على نطاق نص يتضمّن عنصرًا واحدًا أو أكثر.

لقراءة عناصر المستند، استخدِم الأسلوب documents.get للحصول على ملف JSON يحتوي على المستند الكامل. يمكنك بعد ذلك تحليل ملف ملف JSON الناتج للعثور على قيم العناصر الفردية. لمزيد من المعلومات، اطّلِع على مقالة إخراج محتوى المستند بتنسيق JSON.

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

بنية قائمة مستندات
الشكل 7. بنية قائمة مستندات

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

اكتساب الأذونات من الموقع

يمكن أن يكتسب StructuralElement سمات من العناصر الرئيسية. تُحدِّد سمات العنصر، بما في ذلك السمات التي يحدّدها والأخرى التي يكتسبها، مظهره المرئي النهائي.

يحدِّد تنسيق أحرف النص كيفية عرض النص في المستند، مثل الخط الغامق والمائل والسطر تحته. يحلّ التنسيق الذي تطبّقه محلّ التنسيق التلقائي المكتسَب من TextStyle الفقرة الأساسية. في المقابل، تستمر أي أحرف لا يتم ضبط تنسيقها في اكتساب أنماط الفقرة.

يحدِّد تنسيق الفقرة كيفية عرض أجزاء النص في المستند، مثل المحاذاة والحدود والمسافة البادئة. إنّ التنسيق الذي تطبّقه يحلّ محلّ التنسيق التلقائي المُكتسَب من ParagraphStyle الأساسي. في المقابل، تستمر أي ميزات تنسيق لا تضبطها في اكتسابها من نمط الفقرة.