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

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

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

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

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

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

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

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

مخطّط بنية "العروض التقديمية من Google"

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

مخطّط بنية السمات

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

اكتساب أذونات العرض التقديمي

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

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

اكتساب خصائص الشكل

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

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

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

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

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

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

"إخفاء" الخصائص باستخدام PropertyState

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

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

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

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

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

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