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

بنية مستند مستندات 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:

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

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

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

بنية الفقرة

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

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

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

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

مرات ظهور النص

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

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

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

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.

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

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

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

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

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

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