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

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

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

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

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

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

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

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

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

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

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

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

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

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

تتضمّن معظم العناصر في محتوى النص الأساسي السمة 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.

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

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

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

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

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

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

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

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