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

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

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

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

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

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

يوضِّح نموذج الرمز البرمجي presentations.batchUpdate التالي كيفية استخدام طريقة CreateShapeRequest لإضافة مربّع نص جديد (يحتوي على السلسلة "My Add 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-hold-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
      }
    }
  ]
}