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

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

• نموذج مفاهيمي لعناصر الوثيقة
• كيفية تمثيل واجهة برمجة التطبيقات لتطبيق "مستندات Google" لهذه العناصر
• خصائص نمط العناصر

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

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

تشتمل عناصر المستوى الأعلى لمورد documents على Body وHeader وFooter وسمات أخرى متعددة:

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

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

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

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

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

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

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

بنية الفقرة

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

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

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

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

عمليات تنفيذ النص

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

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

AutoText

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

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

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

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

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

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

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

عناصر الوصول

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

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

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

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

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

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

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

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

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

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