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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يتضمن presentation عددًا من الخصائص، ويحتوي على الصفحات الموجودة فيه:

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

الصفحات

تتضمن الصفحة مجموعة من الخصائص، وتحتوي على عناصر الصفحة الموجودة فيها:

{
  "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".
سطر	خط مرئي أو منحنى أو موصل.
جدول	شبكة من المحتوى.
WordArt	عنصر نصي مرئي يتصرف بشكل أكثر مثل الشكل.
SheetsChart	رسم بياني تم استيراده إلى "العروض التقديمية من Google" من "جداول بيانات Google".

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

اكتساب خصائص الصفحة

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

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

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

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

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

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

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

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

يمكنك إنشاء عناصر نائبة باستخدام أداة تعديل "العروض التقديمية من Google"، ولكن ليس باستخدام واجهة برمجة تطبيقات "العروض التقديمية من Google".

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

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

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

• العنصر النائب 1: يتم عرض السمة "أ" على أنّها "أصفر"، بينما يتم عرض السمة "ب" على أنّها "أخضر".
• العنصر النائب 2: يتم عرض الخاصية "أصفر" باللون "الأصفر"، بينما يتم عرض السمة "ب" على أنّها "أرجواني".
• العنصر النائب 3: يتم عرض الخاصية "أصفر"، بينما يتم عرض السمة "ب" على أنّها "أرجواني".

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

عندما لا يكون للشكل أصلاً، تتم تلقائيًا تعبئة أي قيم لم يتم ضبطها باستخدام الإعدادات التلقائية للتطبيق.

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

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

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

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

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

• العنصر النائب 1: يتم عرض الخاصية "أ" على أنّها "أحمر".
• العنصر النائب 2: لم يتم عرض السمة "أ". إذا كانت هذه هي خاصية المخطط التفصيلي، فلن يكون للعنصر النائب 2 مخطط تفصيلي.
• العنصر النائب 3: لم يتم عرض السمة "أ".

هناك قيمة أخرى محتملة لتعداد PropertyState: تعني حالة السمة INHERIT أن حالة الخاصية بذاتها مُكتسَبة، ويجب استخدام قيمة الأصل. لا يمكن أن تكون للأشكال التي لا تحتوي على آباء سمة INHERIT.