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