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

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

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

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

AutoText

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

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

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

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

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

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

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

عناصر الوصول

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

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

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

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

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

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

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

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