تتيح لك Google Slides API إنشاء عروض تقديمية في "العروض التقديمية من Google" وتعديلها.
يمكن أن تتكامل التطبيقات مع واجهة برمجة التطبيقات Google Slides API لإنشاء مجموعات شرائح جميلة تلقائيًا من البيانات المقدمة من المستخدم والنظام. على سبيل المثال، يمكنك استخدام تفاصيل العميل من قاعدة بيانات ودمجها مع القوالب المصممة مسبقًا وخيارات التكوين المحددة لإنشاء عروض تقديمية مكتملة في جزء من الوقت الذي يستغرقه إنشائها يدويًا.
نظرة عامة على واجهة برمجة التطبيقات
توفر مجموعة العروض التقديمية طرقًا تتيح لك الحصول على العناصر وتحديثها في العرض التقديمي.
من المحتمل أن يكون معظم عملك باستخدام Slides API عبارة عن إنشاء العروض التقديمية وتحديثها. ويمكنك إجراء ذلك باستخدام الطريقة batchUpdate، حيث تأخذ هذه الطريقة قائمة بكائنات الطلب التي تتيح لك تنفيذ إجراءات مثل:
- إنشاء شرائح
- إضافة عناصر إلى الشرائح مثل الأشكال أو الجداول
- إدراج النص وتغييره وإزالته
- تطبيق التحويلات على العناصر
- تغيير ترتيب الشرائح
راجِع التحديثات المجمّعة لمعرفة مزيد من التفاصيل. راجِع أدلة "البدء" (Get Started) للاطّلاع على مثال بسيط وشامل حول كيفية استخدام واجهة برمجة التطبيقات.
هيكل العرض التقديمي
يتكون العرض التقديمي في واجهة برمجة تطبيقات الشرائح من صفحات تحتوي على عناصر الصفحة.
يمكن اشتقاق معرّف العرض التقديمي من عنوان URL:
https://docs.google.com/presentation/d/presentationId/edit
معرف العرض التقديمي هو سلسلة تحتوي على أحرف وأرقام وبعض الأحرف الخاصة. يمكن استخدام التعبير العادي التالي لاستخراج معرّف العرض التقديمي من عنوان URL لـ "جداول بيانات Google":
/presentation/d/([a-zA-Z0-9-_]+)
إذا كنت على دراية بواجهة برمجة تطبيقات Drive، ستتوافق السمة presentationId مع
رقم تعريف مورد الملف.
يتم تحديد الصفحات وعناصر الصفحة من خلال أرقام تعريف الكائنات.
Pages
تشتمل "العروض التقديمية من Google" على الأنواع التالية من الصفحات:
| ماجستير | تحدد الشرائح الرئيسية الشرائح أنماط النص التلقائية والخلفية وعناصر الصفحة التي تظهر في جميع الشرائح التي تستخدم هذه الشريحة الرئيسية. يجب إضافة عناصر الصفحة التي يجب أن تظهر على كل الشرائح إلى الصفحة الرئيسية. وتتضمن معظم العروض التقديمية مادة رئيسية واحدة، ولكن قد يحتوي بعضها على عدة عروض أو لا يتضمنها. |
| التنسيقات | يتم استخدام التنسيقات كنموذج لكيفية ترتيب عناصر الصفحة تلقائيًا على الشرائح باستخدام تنسيق. يرتبط كل تنسيق بصفحة رئيسية واحدة. |
| شرائح | تتضمن هذه الصفحات المحتوى الذي تقدمه لجمهورك. تستند معظم الشرائح إلى شريحة رئيسية وتخطيط. ويمكنك تحديد التنسيق الذي سيتم استخدامه لكل شريحة عند إنشائها. |
| Notes | تتضمن هذه الصفحات محتوى منشورات العروض التقديمية، بما في ذلك شكل يحتوي على ملاحظات المحاضر في الشريحة. وتحتوي كل شريحة على صفحة ملاحظات مقابلة. لا يمكن تعديل سوى النص في شكل "ملاحظات المحاضر" باستخدام واجهة برمجة تطبيقات "العروض التقديمية من Google". |
| جهات الاتصال الرئيسية للملاحظات | تحدِّد العروض الرئيسية في Notes أنماط النص التلقائية وعناصر الصفحة لجميع صفحات الملاحظات. تكون الشرائح الرئيسية للملاحظات للقراءة فقط في واجهة برمجة تطبيقات "العروض التقديمية من Google". |
عناصر الصفحة
عناصر الصفحة هي المكونات المرئية التي يتم وضعها على الصفحات. تعرض واجهة برمجة التطبيقات أنواعًا متعدّدة من عناصر الصفحة، وهي:
| مجموعة | مجموعة من عناصر الصفحة يتم التعامل معها كوحدة فردية. يمكن تحريكها وتغيير حجمها وتدويرها معًا. |
| شكل | كائن مرئي عادي، مثل المستطيلات والقطع الناقص ومربعات النص. يمكن أن تحتوي الأشكال على نص، وبالتالي فهي العناصر الأكثر شيوعًا في إنشاء الشرائح. |
| صورة | رسم تم استيراده إلى "العروض التقديمية من Google". |
| فيديو | تم استيراد فيديو إلى "العروض التقديمية من Google". |
| سطر | خط مرئي أو منحنى أو موصِّل. |
| الجدول | شبكة من المحتوى |
| WordArt | يشير ذلك المصطلح إلى عنصر نص مرئي يشبه الشكل. |
| SheetsChart | تم استيراد رسم بياني إلى "العروض التقديمية من Google" من "جداول بيانات Google". |
التحديثات المجمّعة
تتيح لك الطريقة batchUpdate تحديث العديد من جوانب العرض التقديمي. يتم تجميع التغييرات معًا في دفعة بحيث إذا فشل أحد الطلبات، فلا تتم كتابة أي من التغييرات الأخرى (التي يحتمل أن تكون تابعة).
تعمل الطريقة batchUpdate من خلال أخذ كائن Request واحد أو أكثر، ويحدد كل كائن نوعًا واحدًا من الطلبات لتنفيذه. هناك العديد من أنواع الطلبات المختلفة. في ما يلي تصنيف لأنواع الطلبات،
مجمّعة في فئات مختلفة.
تعرض الطريقة batchUpdate نص الاستجابة الذي يحتوي على رد لكل طلب. تشغَل كل استجابة الفهرس نفسه الخاص بالطلب ذي الصلة، وبالنسبة إلى الطلبات التي لا تتضمّن استجابة قابلة للتطبيق، ستكون الاستجابة في ذلك الفهرس فارغة. عادةً ما تحتوي طلبات Create المختلفة على ردود، حتى تعرِف رقم تعريف العنصر المُضاف حديثًا.
التعامل مع معرّفات الكائنات
يتكون العرض التقديمي في واجهة برمجة التطبيقات للعروض التقديمية من صفحات وعناصر صفحة. تتضمّن هذه الكائنات سلسلة رقم تعريف الكائن التي تكون فريدة في العرض التقديمي.
تحديد أرقام تعريف العناصر عند الإنشاء
عند إنشاء صفحات أو عناصر صفحة باستخدام الطريقة batchUpdate، يمكنك اختياريًا تحديد رقم تعريف كائن للكائن الجديد. ويتيح لك ذلك إنشاء كائن وتعديله ضمن طلب التحديث المجمّع نفسه، ما يقلّل من عدد الطلبات إلى واجهة برمجة تطبيقات "العروض التقديمية من Google" ويقلل استخدام الحصص.
وننصح بإنشاء رقم تعريف كائن عشوائي في معظم الحالات. على سبيل المثال، إذا كنت تستخدم Java، من المفترَض أن يعمل java.util.UUID.randomUUID().toString() بشكل جيد.
عندما يريد التطبيق تتبع العناصر على مدار فترة زمنية أطول، لا تعتمد على معرّف الكائن، لأنه قد يتغير. راجِع القسم التالي للحصول على مزيد من التفاصيل.
تتبُّع العناصر بدون استخدام رقم تعريف الكائن
عند تقديم طلب من Google Slides API، يتم عادةً الاحتفاظ برقم تعريف العنصر. (يتم استدعاء أي استثناءات في الوثائق المرجعية للطريقة). يؤدي إنشاء نسخة من عرض تقديمي بالكامل باستخدام Drive API أيضًا إلى الاحتفاظ بمعرّفات الكائنات.
ومع ذلك، لا يمكنك الاعتماد على عدم تغيير رقم تعريف كائن بعد تغيير عرض تقديمي في واجهة مستخدم "العروض التقديمية من Google". على سبيل المثال، إذا استخدم أحدهم واجهة مستخدم "العروض التقديمية" لنسخ عنصر صفحة ولصقه ثم حذف العنصر الأصلي، سيحصل عنصر الصفحة الآن على معرّف فريد جديد، وسيتم فقدان المعرّف الذي قدّمته سابقًا عبر واجهة برمجة التطبيقات. ونتيجةً لذلك، ننصحك بعدم تخزين معرّفات العناصر في مساحة تخزين تطبيقك. بدلاً من ذلك، يجب عليك العثور على كائنات في العرض التقديمي من خلال المحتوى النصي أو النص البديل.
تستخدم العروض التقديمية التي تم إنشاؤها حديثًا عادةً مجموعة متسقة من المعرفات للشرائح الرئيسية ومربعات النص الافتراضية. إنّ أرقام التعريف هذه عرضة للتغيير مع مرور الوقت، لذا لا ننصح بالاعتماد على هذه الميزة. بدلاً من ذلك، ابحث عن العناصر التي تريد تعديلها باستخدام كائن العرض التقديمي الذي يعرضه عمليات الاستدعاء إلى create() أو get().