أحد التطبيقات المفيدة لواجهة برمجة التطبيقات Google Slides API هو دمج المعلومات من مصدر بيانات واحد أو أكثر في عرض تقديمي مستند إلى نموذج.
توضّح هذه الصفحة كيفية أخذ البيانات من مصدر خارجي وإدراجها في عرض تقديمي حالي مستند إلى نموذج. يشبه المفهوم مفهوم دمج المراسلات باستخدام معالج نصوص وجدول بيانات.
هناك عدة أسباب تجعل هذا الأسلوب مفيدًا:
من السهل على المصمّمين تحسين تصميم العرض التقديمي باستخدام محرّر "العروض التقديمية من Google". هذا أسهل بكثير من ضبط المَعلمات في تطبيقك لضبط تصميم الشريحة المعروضة.
إنّ فصل المحتوى عن العرض التقديمي هو مبدأ تصميم معروف وله فوائد عديدة.
إعداد مسبق أساسي
في ما يلي مثال على كيفية استخدام Slides API لدمج البيانات في عرض تقديمي:
يمكنك إنشاء العرض التقديمي بالطريقة التي تريدها باستخدام محتوى نائب لمساعدتك في التصميم.
لكل عنصر محتوى ستدرجه، استبدِل المحتوى النائب بعلامة. العلامات هي مربّعات نص أو أشكال تحتوي على سلسلة فريدة. احرص على استخدام سلاسل من غير المرجّح أن تظهر بشكلٍ طبيعي. على سبيل المثال، قد تكون السلسلة
{{account-holder-name}}علامة جيدة.في الرمز، استخدِم Google Drive API لإنشاء نسخة من العرض التقديمي.
في الرمز، استخدِم طريقة Slides API's
batchUpdate، مع مجموعة من طلباتreplaceAllText، لإجراء جميع عمليات استبدال النص في العرض التقديمي. استخدِمreplaceAllShapesWithImageطلبات لإجراء عمليات استبدال الصور في العرض التقديمي.
بعد إنشاء عرض تقديمي يحتوي على علامات، احرص على إنشاء نسخة واستخدِم Slides API لمعالجة النسخة. لا تستخدِم Slides API لمعالجة النسخة الأساسية "للنموذج".
تتضمّن الأقسام التالية مقتطفات من الرموز توضّح بعضًا من هذه العملية. يمكنك أيضًا مشاهدة الفيديو أعلاه للاطّلاع على مثال كامل (Python) يجمع بين العديد من المفاهيم من الأقسام الفردية أدناه.
دمج النص
يمكنك استخدام replaceAllText
طلب لاستبدال جميع مثيلات سلسلة نصية معيّنة في
عرض تقديمي بنص جديد. بالنسبة إلى عمليات الدمج، يكون هذا الإجراء أبسط من العثور على كل مثيل من النص واستبداله بشكلٍ فردي. أحد الأسباب التي تجعل هذا الأسلوب هو الأكثر تطورًا هو أنّ من الصعب توقّع أرقام تعريف عناصر الصفحة، خاصةً عندما يحرِّن المتعاونون العرض التقديمي المستند إلى نموذج ويحافظون عليه.
مثال
يستخدِم هذا المثال Drive API لنسخ عرض تقديمي مستند إلى نموذج، ما يؤدي إلى إنشاء مثيل جديد من العرض التقديمي. بعد ذلك، يستخدِم Google Sheets API لقراءة البيانات من جدول بيانات في "جداول بيانات Google"، وأخيرًا يستخدِم Slides API لتعديل العرض التقديمي الجديد.
يأخذ المثال بيانات من 3 خلايا في صف واحد من نطاق مُعنوَن في جدول البيانات. بعد ذلك، يستبدِل هذه البيانات في العرض التقديمي أينما تظهر
السلاسل {{customer-name}}أو
{{case-description}}أو
{{total-portfolio}}.
برمجة التطبيقات
انتقال
جافا
JavaScript
Node.js
PHP
Python
Ruby
دمج الصور
يمكنك أيضًا دمج الصور في العرض التقديمي باستخدام a
replaceAllShapesWithImage
طلب. يستبدِل هذا الطلب جميع مثيلات الأشكال التي تحتوي على السلسلة النصية المقدَّمة بالصورة المقدَّمة. يضبط الطلب تلقائيًا موضع الصورة وحجمها لتناسب حدود شكل العلامة مع الحفاظ على نسبة العرض إلى الارتفاع للصورة.
مثال
يستخدِم هذا المثال Google Drive API لنسخ عرض تقديمي مستند إلى نموذج، ما يؤدي إلى إنشاء مثيل جديد من العرض التقديمي. بعد ذلك، يستخدِم Slides API للعثور على
أي شكل يحتوي على النص {{company-logo}}
واستبداله بصورة لشعار الشركة. يستبدِل الطلب أيضًا أي
شكل يحتوي على النص {{customer-graphic}}
بصورة مختلفة.
برمجة التطبيقات
انتقال
جافا
JavaScript
Node.js
PHP
Python
Ruby
استبدال مثيلات معيّنة من مربّع نص أو صورة
تكون طلبات replaceAllText
و replaceAllShapesWithImage
مفيدة لاستبدال العلامات في جميع أنحاء العرض التقديمي، ولكن
في بعض الأحيان تحتاج فقط إلى استبدال العناصر وفقًا لمعيار آخر، مثل
أن تكون موجودة على شريحة معيّنة.
في هذه الحالات، عليك استرداد أرقام تعريف أشكال العلامات التي تريد استبدالها. بالنسبة إلى عمليات استبدال النص، عليك حذف النص الحالي في هذه الأشكال ثم إدراج النص الجديد (راجِع المثال تعديل نص في شكل معيّن).
تكون عمليات استبدال الصور أكثر تعقيدًا. لدمج صورة، عليك إجراء ما يلي:
- الحصول على رقم تعريف شكل العلامة
- نسخ معلومات الحجم والتحويل من العلامة
- إضافة الصورة إلى الصفحة باستخدام معلومات الحجم والتحويل
- حذف شكل العلامة
قد يتطلب الحفاظ على نسبة العرض إلى الارتفاع للصورة أثناء تغيير حجمها إلى الحجم المطلوب بعض العناية، كما هو موضّح في القسم التالي. راجِع أيضًا هذا المثال: استبدال علامة شكل بصورة.
الحفاظ على نسبة العرض إلى الارتفاع
عند إنشاء صور باستخدام Slides API، تستند عمليات الملاءمة إلى نسبة العرض إلى الارتفاع فقط إلى حجم الصورة، وليس إلى بيانات الحجم والتحويل. تُعتبر بيانات الحجم التي تقدّمها
في الـ createImage
طلب هي الحجم المطلوب للصورة. تُلاءِم واجهة برمجة التطبيقات نسبة العرض إلى الارتفاع للصورة مع هذا الحجم المطلوب، ثم تطبِّق التحويل المقدَّم.
عند استبدال علامة بصورة، يمكنك الحفاظ على نسبة العرض إلى الارتفاع للصورة من خلال ضبط حجم الصورة وتغيير حجمها على النحو التالي:
- العرض: يتم ضبطه على ناتج ضرب
widthالعلامة فيscaleX - الارتفاع: يتم ضبطه على ناتج ضرب
heightالعلامة فيscaleY - scale_x: يتم ضبطه على
1 - scale_y: يتم ضبطه على
1
يؤدي ذلك إلى أن تُلاءِم Slides API نسبة العرض إلى الارتفاع للصورة وفقًا للحجم المرئي للعلامة
، وليس حجمها غير المعدَّل (راجِع
استبدال علامة شكل بصورة).
يمنع ضبط مَعلمات تغيير الحجم على 1 تغيير حجم الصورة مرّتين.
يضمن هذا الترتيب الحفاظ على نسبة العرض إلى الارتفاع للصورة، ويمنع تجاوز حجم شكل العلامة. تحتوي الصورة على نقطة مركزية نفسها التي يحتوي عليها شكل العلامة.
إدارة النماذج
بالنسبة إلى العروض التقديمية المستندة إلى نماذج التي يحدّدها التطبيق ويملكها، يمكنك إنشاء النموذج باستخدام حساب مخصّص يمثّل التطبيق. تُعدّ حسابات الخدمة خيارًا جيدًا وتتجنّب المشاكل المتعلقة بسياسات Google Workspace التي تقيّد المشاركة.
عند إنشاء مثيلات من العروض التقديمية من النماذج، استخدِم دائمًا بيانات اعتماد المستخدم النهائي. يمنح ذلك المستخدمين تحكّمًا كاملاً في العرض التقديمي الناتج ويمنع مشاكل تغيير الحجم المتعلقة بالحدود المفروضة على كل مستخدم في Google Drive.
لإنشاء نموذج باستخدام حساب خدمة، اتّبِع الخطوات التالية باستخدام بيانات اعتماد التطبيق:
- يمكنك إنشاء عرض تقديمي باستخدام presentations.create في Slides API.
- يمكنك تعديل الأذونات للسماح لمستلِمي العرض التقديمي بقراءته باستخدام permissions.create في Drive API.
- يمكنك تعديل الأذونات للسماح لمؤلّفي النماذج بالكتابة إليه باستخدام permissions.create في Drive API.
- يمكنك تعديل النموذج حسب الحاجة.
لإنشاء مثيل من العرض التقديمي، اتّبِع الخطوات التالية باستخدام بيانات اعتماد المستخدم:
- يمكنك إنشاء نسخة من النموذج باستخدام files.copy في Drive API.
- يمكنك استبدال القيم باستخدام presentation.batchUpdate في Slides API.