الكتابة الأساسية

تتيح لك واجهة برمجة التطبيقات Google Slides API إضافة عناصر إلى صفحات العروض التقديمية وتعديلها. توضّح الأمثلة الواردة في هذه الصفحة كيفية تنفيذ عمليات القراءة الشائعة باستخدام طريقة presentations.batchUpdate.

تستخدِم هذه الأمثلة المتغيّرات التالية:

• PRESENTATION_ID—تشير إلى المكان الذي تقدّم فيه معرّف العرض التقديمي. يمكنك العثور على قيمة رقم التعريف هذا من عنوان URL الخاص بالعرض التقديمي.
• PAGE_ID: تشير إلى المكان الذي تقدّم فيه معرّف عنصر الصفحة. يمكنك استرداد قيمة هذا الحقل من عنوان URL أو باستخدام طلب قراءة من واجهة برمجة التطبيقات.
• PAGE_ELEMENT_ID—تشير إلى المكان الذي تقدّم فيه معرّف كائن عنصر الصفحة. يمكنك تحديد هذا المعرّف للعناصر التي تنشئها (مع بعض القيود) أو السماح لواجهة برمجة التطبيقات Slides API بإنشاء معرّف تلقائيًا. يمكن استرداد معرّفات العناصر من خلال طلب قراءة من واجهة برمجة التطبيقات.

يتم تقديم هذه الأمثلة كطلبات HTTP لتكون محايدة لغويًا. للتعرّف على كيفية تنفيذ تعديل مجمّع بلغات مختلفة باستخدام مكتبات برامج Google API، راجِع إضافة أشكال ونصوص.

إضافة مربّع نص إلى شريحة

يوضّح نموذج الرمز البرمجي التالي presentations.batchUpdate كيفية استخدام الإجراء CreateShapeRequest لإضافة مربّع نص جديد (يحتوي على السلسلة "My Added Text Box") إلى شريحة محدّدة بواسطة PAGE_ID. يتم تحديد طلبَين في نص الطلب، أحدهما لإنشاء شكل مربّع النص (بحجم وموقع محدّدَين) والآخر لإدراج نص فيه.

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

في ما يلي بروتوكول الطلب لإضافة مربّع نص إلى شريحة:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate

{
  "requests": [
    {
      "createShape": {
        "objectId": PAGE_ELEMENT_ID,
        "shapeType": "TEXT_BOX",
        "elementProperties": {
          "pageObjectId":  PAGE_ID,
          "size": {
            "width": {
              "magnitude": 150,
              "unit": "PT"
            },
            "height": {
              "magnitude": 50,
              "unit": "PT"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1,
            "translateX": 200,
            "translateY": 100,
            "unit": "PT"
          }
        }
      }
    },
    {
      "insertText": {
        "objectId": PAGE_ELEMENT_ID,
        "text": "My Added Text Box",
        "insertionIndex": 0
      }
    }
  ]
}

إضافة صورة إلى شريحة

يوضّح نموذج الرمز البرمجي التالي presentations.batchUpdate كيفية استخدام طريقة CreateImageRequest لإضافة صورة إلى شريحة محدّدة بواسطة PAGE_ID. تسترد واجهة برمجة التطبيقات الصورة باستخدام IMAGE_URL. يؤدي هذا الطلب أيضًا إلى تغيير حجم الصورة وتحديد موضعها في الشريحة.

في ما يلي بروتوكول الطلب لإضافة صورة إلى شريحة:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate

{
  "requests": [
    {
      "createImage": {
        "url": IMAGE_URL,
        "elementProperties": {
          "pageObjectId":  PAGE_ID,
          "size": {
            "width": {
              "magnitude": 30,
              "unit": "PT"
            },
            "height": {
              "magnitude": 30,
              "unit": "PT"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1,
            "translateX": 200,
            "translateY": 100,
            "unit": "PT"
          }
        }
      }
    }
  ]
}

حذف صفحة أو عنصر صفحة

يوضّح نموذج الرمز التالي presentations.batchUpdate كيفية استخدام الإجراء DeleteObjectRequest لحذف عنصر الصفحة المحدّد بواسطة PAGE_ELEMENT_ID والشريحة المحدّدة بواسطة PAGE_ID باستخدام طلبَين منفصلَين.

في ما يلي بروتوكول الطلب لحذف صفحة أو عنصر صفحة:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate

{
  "requests": [
    {
      "deleteObject": {
        "objectId": PAGE_ELEMENT_ID
      },
      "deleteObject": {
        "objectId":  PAGE_ID
      }
    }
  ]
}

تعديل النص في شكل محدّد

يوضّح نموذج الرمز البرمجي التالي presentations.batchUpdate كيفية استخدام طريقة DeleteTextRequest لاستبدال جزء من النص المعروض في الشكل المحدّد بواسطة PAGE_ELEMENT_ID. لإجراء ذلك، احذف النص أولاً باستخدام startIndex المستند إلى الصفر، ثم أدرِج نصًا جديدًا في ذلك الموضع. في هذا المثال، يتم استبدال سلسلة النص الأصلية "My Shape Text: ????" بـ "My Shape Text: Trapezoid".

لا يؤثر هذا الطلب إلا في النص الموجود في شكل محدّد. لاستبدال النص في كل مكان ضمن عرض تقديمي، استخدِم طريقة ReplaceAllTextRequest.

في ما يلي بروتوكول الطلب لتعديل النص في شكل محدّد:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate

{
  "requests": [
    {
      "deleteText": {
        "objectId": PAGE_ELEMENT_ID,
        "textRange": {
          "type": "FROM_START_INDEX",
          "startIndex": 15
        }
      }
    },
    {
      "insertText": {
        "objectId": PAGE_ELEMENT_ID,
        "text": "Trapezoid",
        "insertionIndex": 15
      }
    }
  ]
}

استبدال علامة شكل بصورة

العلامات هي مربّعات نص أو أشكال تتضمّن اسم سلسلة فريدًا، مثل "account-holder-name".

يوضّح نموذج الرمز التالي presentations.batchUpdate كيفية استخدام طريقة CreateImageRequest لاستبدال مثيل واحد من علامة شكل بصورة، مع الحفاظ على الموضع نفسه وتغيير حجم الصورة لتناسب حجم العلامة مع الحفاظ على نسبة العرض إلى الارتفاع للصورة.

يمكن أيضًا استخدام الطلب لاستبدال صورة بأخرى. يتضمّن الطلب إضافة الصورة الجديدة ثم حذف العلامة.

لا تستبدل الطريقة CreateImageRequest سوى شكل محدّد. لاستبدال أشكال العلامات في كل مكان ضمن عرض تقديمي، استخدِم طريقة ReplaceAllShapesWithImageRequest.

تحتوي علامة الشكل على السمات التالية PageElement (التي يمكن العثور عليها باستخدام طلب presentations.pages.get):

{
  "objectId": PAGE_ELEMENT_ID,
  "size": {
    "width": {
      "magnitude": 3000000,
      "unit": "EMU"
    },
    "height": {
      "magnitude": 3000000,
      "unit": "EMU"
    }
  },
  "transform": {
    "scaleX": 1.13,
    "scaleY": 0.62,
    "translateX": 4800000,
    "translateY":  450000,
    "unit": "EMU"
  },
  "shape": {
    "shapeType": "RECTANGLE"
  }
}

يقع الشكل على الشريحة المحدّدة بواسطة PAGE_ID. لتحديد الصورة التي تحل محل الشكل، تسترد واجهة برمجة التطبيقات الصورة باستخدام IMAGE_URL. للحفاظ على نسبة العرض إلى الارتفاع للصورة مع الحدّ من حجمها ليناسب حجم الملصق، تضبط الطريقة CreateImageRequest حجم الصورة على ناتج حجم الملصق ومقياسه، كما تضبط عوامل مقياس الصورة على 1. لمزيد من المعلومات، يُرجى الاطّلاع على الحفاظ على نسبة العرض إلى الارتفاع.

في ما يلي بروتوكول الطلب لاستبدال علامة شكل بصورة:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate

{
  "requests": [
    {
      "createImage": {
        "url": IMAGE_URL,
        "elementProperties": {
          "pageObjectId":  PAGE_ID,
          "size": {
            "width": {
              "magnitude": 3000000 * 1.13,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000 * 0.62,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1,
            "translateX": 4800000,
            "translateY": 450000,
            "unit": "PT"
          }
        }
      }
    },
    {
      "deleteObject": {
        "objectId": PAGE_ELEMENT_ID
      }
    }
  ]
}