ومن أجل استخدام واجهة برمجة التطبيقات لمحرّر مستندات 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
تمثل سلسلة نصية متجاورة مع نفس نمط النص. حاسمة
يمكن أن تحتوي الفقرة على عمليات تشغيل نصية متعددة ولكن لا يعمل النص عبر الفقرات
الحدود. يتم تقسيم المحتوى بعد حرف سطر جديد لتشكيل نص منفصل.
يركض. على سبيل المثال، ضع في الاعتبار مستندًا صغيرًا مثل ما يلي:
![مستند صغير يحتوي على فقرات وقائمة نقطية.](https://developers.google.cn/static/docs/api/images/simpledoc.png?authuser=5&hl=ar)
يوضح المخطّط التالي كيف يمكنك تصور تسلسل الفقرات.
في المستند السابق، مع تضمين 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
الأساسي.
وعلى العكس، تستمر أي ميزات تنسيق لم تعينها في الاكتساب من
نمط الفقرة.