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

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

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

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

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

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

يوضّح نموذج الرمز البرمجي التالي presentations.batchUpdate كيفية استخدام الإجراء CreateShapeRequest لإضافة مربّع نص جديد (يحتوي على السلسلة "مربّع النص الذي أضفته") إلى شريحة محدّدة بواسطة 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 المستند إلى الصفر، ثم أدرِج نصًا جديدًا في هذا الموضع. في هذا المثال، تم استبدال سلسلة النصوص الأصلية "نص شكلي: ????" بـ "نص شكلي: شبه منحرف".

لا يؤثر هذا الطلب إلا في النص الذي يتضمّن شكلًا معيّنًا. لاستبدال النص في كل مكان داخل عرض تقديمي، استخدِم الرمز 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
      }
    }
  ]
}

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

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

يوضّح نموذج الرمز البرمجي التالي 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
      }
    }
  ]
}