بنية مستند مستندات 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. بنية علامات التبويب في المستند

تقدّم الأقسام اللاحقة نظرة عامة موجزة على التسلسل الهرمي لعلامات التبويب في المستند، كما تقدّم تمثيل علامة التبويب بتنسيق 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"، يتم استخدام هذا الرمز لتحديد أرقام الصفحات.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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