الصفحات وعناصر الصفحة والخصائص

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

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

ستساعدك قراءة هذه النظرة العامة ونظرات عامة أخرى على فهم أدلة طريقة التنفيذ والمستندات المرجعية وعينات التعليمات البرمجية واستخدامها بسهولة أكبر.

العروض التقديمية والصفحات وعناصر الصفحات

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

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

تحتوي كل صفحة على عدد من عناصر الصفحة، والتي تشكّل معًا محتوى الصفحة، كما هو موضّح في المخطّط البياني التالي:

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

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

التخطيطات - تحدد قوالب التخطيط كيفية ترتيب المحتوى في كل نوع من الشرائح. إذا كنت تريد أن تبدو جميع شرائح العناوين بطريقة معينة، على سبيل المثال، يمكنك تعديل قالب تخطيط العنوان.

هناك نوعان آخران من الصفحات، وهما صفحات الملاحظات والصفحات الرئيسية للملاحظات، وهما مناسبان في الغالب للعمل مع ملاحظات المحاضر.

أنواع تمثيل واجهة برمجة التطبيقات وبنيتها

يوضّح هذا القسم كيفية تمثيل النموذج المفاهيمي لـ "العروض التقديمية من Google"، كما هو موضّح أعلاه، في Slides API.

يوضّح المخطّط البياني التالي العلاقة بين العروض التقديمية والصفحات وعناصر الصفحة كأنواع في Slides API:

توضّح الأقسام التالية كيفية تمثيل هذه الأنواع في JSON.

العروض التقديمية

يتضمّن العرض التقديمي عددًا من السمات، ويحتوي على الصفحات التي يتضمّنها:

{
  "presentationId": string,
  "pageSize": { object(Size) },
  "slides": [ { object(Page) } ],
  "title": string,
  "masters": [ { object(Page) } ],
  "layouts": [ { object(Page) } ],
  "notesMaster": object(Page),
  "locale": string,
}

Pages

تتضمّن الصفحة مجموعة من السمات، وتحتوي على عناصر الصفحة التي تظهر فيها:

{
  "objectId": string,
  "pageType": enum(PageType),
  "pageElements": [ { object(PageElement) } ],
  "pageProperties": { object(PageProperties) },

  // Union field properties can be only one of the following:
  "slideProperties": { object(SlideProperties) },
  "layoutProperties": { object(LayoutProperties) },
  "notesProperties": { object(NotesProperties) },
  // End of list of possible types for union field properties.
}

عناصر الصفحة

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

{
  "objectId": string,
  "size": { object(Size) },
  "transform": { object(AffineTransform) },
  "title": string,
  "description": string,

  // Union field element_kind can be only one of the following:
  "elementGroup": { object(Group) },
  "shape": { object(Shape) },
  "image": { object(Image) },
  "video": { object(Video) },
  "line": { object(Line) },
  "table": { object(Table) },
  "wordArt": { object(WordArt) },
  "sheetsChart": { object(SheetsChart) },
  // End of list of possible types for union field element_kind.
}

هناك عدة أنواع من عناصر الصفحة، كما هو محدّد في حقل الاتحاد element_kind في التعريف أعلاه. يتم وصف هذه الأنواع من عناصر الصفحة في الجدول التالي:

نوع العنصر	الوصف
المجموعة	مجموعة من عناصر الصفحة التي يتم التعامل معها كوحدة فردية. ويمكن نقلها وتغيير حجمها وتدويرها معًا.
الشكل	كائن مرئي بسيط، مثل المستطيلات والقطع الناقص ومربعات النص. يمكن أن تحتوي الأشكال على نص، لذا فهي عناصر الصفحة الأكثر شيوعًا لإنشاء الشرائح.
صورة	رسم تم استيراده إلى "العروض التقديمية من Google"
فيديو	فيديو تم استيراده إلى "العروض التقديمية من Google"
Line	خط أو منحنى أو رابط مرئي
جدول	شبكة من المحتوى
WordArt	عنصر نصي مرئي يتصرف بشكل يشبه الشكل.
SheetsChart	رسم بياني تم استيراده إلى "العروض التقديمية من Google" من "جداول بيانات Google"

خصائص الصفحة وعناصر الصفحة

تتيح لك واجهة برمجة التطبيقات Slides API قراءة وتعديل مظهر الصفحات وعناصر الصفحات في العرض التقديمي. تدعم عناصر الصفحة المختلفة سمات مختلفة تتحكم في كيفية عرض عنصر الصفحة.

لكل نوع من أنواع عناصر الصفحة عنصر سمات ورسالة تعديل سمات مقابلة، على سبيل المثال:

• هناك نوع عنصر صفحة شكل
• حقل السمة هو shapeProperties
• طلب تعديل هذه السمات هو UpdateShapePropertiesRequest

تتوفّر المجموعة نفسها من العناصر/الخصائص/طلبات التعديل لكل نوع من عناصر الصفحة: Image/imageProperties/UpdateImageProperties، وهكذا.

يمكنك قراءة سمة الخصائص أينما واجهتها عند قراءة عنصر. لتغيير القيم فيها، استخدِمها مع نوع الطلب المطابق كحمولة لطريقة batchUpdate، ما يتيح لك تغيير هذه القيم في العرض التقديمي.

أنواع المواقع

هناك بعض السمات الشائعة بين عدة أنواع من العناصر في واجهة برمجة التطبيقات Slides API:

الموقع	الوصف
اللون	يمكن أن تكون الألوان في Slides API إما قيمة RGB أو مرجعًا للون مظهر. تتم الإشارة إلى ألوان المظهر بالاسم (على سبيل المثال "DARK1") ويمكن ربطها بقيم RGB باستخدام مخطط ألوان الصفحة. يتم تعديل نظام الألوان هذا عادةً عند تغيير مظهر العرض التقديمي في محرِّر "العروض التقديمية من Google".
التعبئة	تمثّل التعبئة عرض المساحة الفارغة داخل عنصر. التعبئة الأكثر شيوعًا في "العروض التقديمية من Google" هي التعبئة بلون خالص، حيث يتم ملء الجزء الداخلي من العنصر بلون خالص واحد. يمكن أيضًا استخدام التعبئة لخلفيات الصفحات.
المخطَّط	يمثّل المخطط مجموعة الخطوط التي تحيط بعنصر الصفحة. يتم التحكّم في لون الخطوط باستخدام "تعبئة". يمكن للمتصلين أيضًا تعديل عرض المخططات التفصيلية ونمط الشرطات.
ظل	يمثّل الظل تأثيرًا مرئيًا يهدف إلى محاكاة ظل مادي يلقيه العنصر. في الوقت الحالي، تكون الظلال في Slides API للقراءة فقط.

جارٍ تعديل المواقع

لتعديل سمة، استخدِم طلب Update...Properties المناسب في طلب batchUpdate، على سبيل المثال، UpdateShapeProperties للأشكال. تقبل هذه الطلبات رسالة خصائص كاملة ويمكنها استخدام أقنعة الحقول لتحديد الحقول التي يجب تعديلها في رسالة الخصائص.

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

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

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

• خصائص الصفحة: ترث الصفحة أي خصائص لا تحددها، ولكن يتم تحديدها في التنسيق أو الصفحة الرئيسية التي تستند إليها.
• خصائص الشكل: يمكن وضع علامة على الشكل كـ عنصر نائب، ما يتيح لك الإشارة صراحةً إلى شكل عنصر نائب آخر (في تصميم العنصر الرئيسي للصفحة أو الصفحة الرئيسية) لاكتساب الخصائص منه.

يتم شرح هذه الأفكار بشكل أكبر في الفقرات التالية.

وراثة خصائص الصفحة

تحدّد بنية الشرائح والتنسيقات والشرائح الرئيسية التسلسل الهرمي للاكتساب ضمن العرض التقديمي: تكتسب الشرائح من التنسيقات، وتكتسب التنسيقات من الشرائح الرئيسية. يتم تحديد تصميم العنصر الرئيسي للشريحة والشريحة الرئيسية في حقل slideProperties للشريحة.

يمكن أن تكتسب الصفحة سمات، مثل الخلفية ونظام الألوان، من صفحة رئيسية. لاكتساب سمة، لا تضبط الصفحة الفرعية قيمة لتلك السمة في رسالة PageProperties. ومن خلال عدم "إلغاء" القيمة المحدّدة من قِبل الصفحة الرئيسية، تقبل الصفحة القيمة المكتسبة.

يوضّح المخطّط البياني التالي شريحة تكتسب سمات من تنسيق يكتسب سمات من شريحة رئيسية:

السمات المستخدَمة لعرض شريحة هي مزيج من السمات التي تحدّدها والسمات التي ترثها. في هذا المثال، القيم التي تم حلّها والمستخدَمة لعرض الشريحة 1 هي كما يلي:

• ‫PropertyA هي "أحمر".
• ‫PropertyB هي "برتقالي".

ترث الصفحة التي ليس لها صفحة رئيسية القيم التلقائية من "العروض التقديمية من Google" لأي سمات لا تحدّدها.

وراثة خصائص الشكل

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

يمكنك إنشاء عناصر نائبة باستخدام محرِّر "العروض التقديمية من Google"، ولكن ليس باستخدام Slides API.

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

يوضّح المخطّط البياني التالي توريث السمات بين ثلاثة عناصر نائبة مضمّنة في شريحة وتنسيق وشريحة رئيسية:

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

• ‫Placeholder1: يتم عرض propertyA على أنّها "أصفر" وpropertyB على أنّها "أخضر".
• ‫Placeholder2: يتم عرض السمة A على أنّها "أصفر" والسمة B على أنّها "أرجواني".
• ‫Placeholder3: يتم عرض propertyA على أنّها "أصفر" وpropertyB على أنّها "أرجواني".

الأشكال هي النوع الوحيد من عناصر الصفحة التي يمكن أن يكون لها عناصر رئيسية. أما الأنواع الأخرى، مثل الصور والجداول والرسوم البيانية، فلا يمكن أن تكون عناصر نائبة ولا يمكن أن يكون لها عناصر رئيسية.

عندما لا يكون للشكل عنصر رئيسي، تتم تعبئة أي قيم لا يحدّدها تلقائيًا بالقيم التلقائية للتطبيق.

"إخفاء" المواقع باستخدام PropertyState

يتحكّم تعداد PropertyState في ما إذا كانت سمة الشكل تُستخدَم فعليًا للعرض، أو ما إذا كانت القيمة تُستخدَم فقط للتوريث من خلال الأشكال الفرعية. لن يتم استخدام السمة التي تكون حالة السمة فيها NOT_RENDERED عند عرض الشكل على صفحته، ولكن يمكن للعناصر الفرعية التي تكون حالة السمة المقابلة لها RENDERED أن تكتسب هذه السمة.

يؤدي تعديل موقع إلكتروني إلى ضبط حالته ضمنيًا على `RENDERED` ما لم يتم ضبط الحالة على قيمة أخرى في الطلب نفسه.

يوضّح المخطّط البياني التالي توريث السمات بين ثلاثة عناصر نائبة تعالج حقل PropertyState:

يمكن أن يتأثر عرض خصائص الشكل بحقل PropertyState. في هذا المثال، تكون القيم التي تم حلّها لهذه الأشكال على النحو التالي:

• ‫Placeholder1: يتم عرض propertyA على أنّها "أحمر".
• ‫Placeholder2: لا يتم عرض propertyA. إذا كانت هذه هي السمة outline، فلن يكون لـ Placeholder2 أي مخطط تفصيلي.
• ‫Placeholder3: لا يتم عرض propertyA.

هناك قيمة أخرى محتملة لتعداد PropertyState: تعني حالة السمة INHERIT أنّ حالة السمة نفسها موروثة، ويجب استخدام قيمة السمة الأساسية. لا يمكن أن تكون حالة السمة INHERIT للأشكال التي ليس لها أشكال رئيسية.