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

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

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

• presentationId — تشير إلى مكان تقديم معرّف العرض التقديمي. يمكنك اكتشاف قيمة رقم التعريف هذا من عنوان URL للعرض التقديمي.
• pageId — تشير إلى المكان الذي تقدم فيه رقم تعريف كائن الصفحة. يمكنك استرداد قيمة هذا من عنوان URL أو باستخدام طلب قراءة لواجهة برمجة التطبيقات.
• pageElementId — تشير إلى المكان الذي تقدم فيه رقم تعريف كائن عنصر الصفحة. يمكنك تحديد هذا المعرّف للعناصر التي تنشئها (مع فرض بعض القيود) أو السماح لـ API بإنشاء عنصر تلقائيًا، ويمكن استرداد معرّفات العناصر من خلال طلب قراءة واجهة برمجة التطبيقات.

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

يضيف طلب presentations.batchUpdate التالي مربع نص جديدًا (يحتوي على السلسلة "My Text Text Box") إلى شريحة محددة بواسطة pageId. يتم تحديد طلبين في نص الطلب؛ أحدهما لإنشاء مربع النص (بحجم وموقع محددين) والآخر لإدراج نص فيه.

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

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

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

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

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

يضيف طلب presentations.batchUpdate التالي صورة جديدة إلى شريحة يحددها pageId. ويتم تحديد الصورة من خلال تقديم عنوان URL (imageUrl) تجلبه واجهة برمجة التطبيقات. يؤدي هذا الطلب إلى تغيير حجم الصورة ووضعها في الشريحة.

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

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

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

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

يؤدي طلب presentations.batchUpdate التالي إلى حذف عنصر الصفحة المحدّد بواسطة pageElementId والشريحة المحدّدة بواسطة pageId باستخدام طلبين منفصلين.

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

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

{
  "requests": [
    {
      "deleteObject": {
        "objectId": pageElementId
      },
      "deleteObject": {
        "objectId": pageId
      }
    }
  ]
}

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

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

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

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

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

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

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

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

يحل هذا الطلب محل شكل محدد واحد فقط. لاستبدال أشكال العلامات في كل مكان ضمن العرض التقديمي، استخدم طلب replaceAllFormatsWithImage.

يتضمن شكل العلامة الخصائص التالية (التي يمكن العثور عليها من خلال presentations.pages.get request):

{
  "objectId": pageElementId,
  "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"
  }
}

هذا الشكل موجود في الشريحة المحددة بواسطة pageId. لتحديد الصورة التي ستحل محل الشكل، قدِّم عنوان URL (imageUrl) لواجهة برمجة التطبيقات لجلب الصورة منه. للحفاظ على نسبة العرض إلى الارتفاع للصورة مع قصرها على حجم العلامة، يعيّن طلب createImage حجم الصورة (المطلوب) لمنتج حجم ومقياس العلامة، وعوامل حجم الصورة إلى 1 (يُرجى مراجعة دليل الحفاظ على نسبة العرض إلى الارتفاع).

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

{
  "requests": [
    {
      "createImage": {
        "url": imageUrl,
        "elementProperties": {
          "pageObjectId": pageId,
          "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": pageElementId
      }
    }
  ]
}