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

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

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

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

ويتم تقديم هذه الأمثلة في صورة طلبات 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-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
      }
    }
  ]
}