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

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

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

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

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

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

تشمل العناصر ذات المستوى الأعلى في مورد documents Tabs وSuggestionsViewMode والسمات الأخرى:

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

هناك تمثيل قديم للمستند عندما لا يتم تحديد المَعلمة includeTabsContent أو تكون قيمتها false، ما يؤدي إلى ملء حقول المحتوى النصي (مثل محتوى النص الأساسي) بمحتوى علامة التبويب الأولى مباشرةً ضمن المستند. لمزيد من المعلومات، يُرجى الاطّلاع على documents.get.

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

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

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

الشكل 1. بنية علامات تبويب المستند

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

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

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

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

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

عنصر هيكلي

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

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

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

تحتوي الأنواع Header وFooter وFootnote على عناصر محتوى تتضمّن أيضًا سلسلة من العناصر البنيوية.

بنية الفقرة

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

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

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

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

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

مقاطع نصية

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

الشكل 5. مستند صغير

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

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

AutoText

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

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

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

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

يتم قياس الفهارس بوحدات ترميز 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 الأساسي. في المقابل، ستستمر أي ميزات تنسيق لم تضبطها في الوراثة من نمط الفقرة.

مواضيع ذات صلة

• الطلبات والردود
• قواعد التعديل البنيوي وسلوكه