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

لاستخدام 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 في التعريف أعلاه. يتم وصف أنواع عناصر الصفحة هذه في الجدول التالي:

سمات الصفحة وعناصر الصفحة

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

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

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

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

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

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

تتوفّر بعض الخصائص المشتركة بين عدة أنواع من العناصر في 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.