نوشتن پایه

رابط برنامه‌نویسی کاربردی (API) اسلایدهای گوگل به شما امکان می‌دهد عناصر را در صفحات ارائه اضافه و تغییر دهید. مثال‌های این صفحه نحوه انجام عملیات خواندن رایج را با استفاده از متد presentations.batchUpdate نشان می‌دهند.

این مثال‌ها از متغیرهای زیر استفاده می‌کنند:

• PRESENTATION_ID — نشان می‌دهد که شناسه ارائه را کجا ارائه می‌دهید. می‌توانید مقدار این شناسه را از URL ارائه پیدا کنید.
• PAGE_ID — نشان می‌دهد که شناسه شیء صفحه را کجا ارائه می‌دهید. می‌توانید مقدار این شناسه را از URL یا با استفاده از درخواست خواندن API بازیابی کنید.
• PAGE_ELEMENT_ID — نشان می‌دهد که شناسه شیء عنصر صفحه را کجا ارائه می‌دهید. می‌توانید این شناسه را برای عناصری که ایجاد می‌کنید (با برخی محدودیت‌ها ) مشخص کنید یا به API اسلایدها اجازه دهید که به طور خودکار یکی ایجاد کند. شناسه‌های عنصر را می‌توان از طریق درخواست خواندن API بازیابی کرد.

این مثال‌ها به عنوان درخواست‌های HTTP ارائه شده‌اند تا از نظر زبانی بی‌طرف باشند. برای یادگیری نحوه پیاده‌سازی به‌روزرسانی دسته‌ای در زبان‌های مختلف با استفاده از کتابخانه‌های کلاینت API گوگل، به بخش افزودن شکل‌ها و متن مراجعه کنید.

اضافه کردن کادر متن به اسلاید

نمونه کد presentations.batchUpdate زیر نحوه استفاده از متد CreateShapeRequest را برای اضافه کردن یک کادر متن جدید (حاوی رشته "My Added Text Box") به اسلایدی که توسط PAGE_ID مشخص شده است، نشان می‌دهد. دو درخواست در بدنه درخواست مشخص شده است - یکی برای ایجاد شکل کادر متن (با اندازه و مکان مشخص) و دومی برای وارد کردن متن در آن.

درخواست اول شناسه شیء مورد استفاده برای کادر متن را مشخص می‌کند . این به درخواست دوم اجازه می‌دهد تا از آن در همان فراخوانی API استفاده کند و سربار را کاهش دهد.

پروتکل درخواست برای اضافه کردن کادر متن به اسلاید به صورت زیر است:

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 مشخص شده است، نشان می‌دهد. API تصویر را با استفاده از 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
      }
    }
  ]
}

یک برچسب شکل را با یک تصویر جایگزین کنید

برچسب‌ها، کادرهای متنی یا شکل‌هایی با یک نام رشته‌ای منحصر به فرد، مانند "نام-دارنده-حساب" هستند.

نمونه کد presentations.batchUpdate زیر نحوه استفاده از متد CreateImageRequest را برای جایگزینی یک نمونه از یک برچسب شکل با یک تصویر، با حفظ موقعیت یکسان و مقیاس‌بندی آن برای متناسب شدن با اندازه برچسب در عین حفظ نسبت ابعاد تصویر، نشان می‌دهد.

این درخواست همچنین می‌تواند برای جایگزینی یک تصویر با تصویر دیگر استفاده شود. این درخواست شامل اضافه کردن تصویر جدید و سپس حذف برچسب است.

متد CreateImageRequest فقط یک شکل مشخص شده را جایگزین می‌کند. برای جایگزینی شکل‌های برچسب در همه جای یک ارائه، از متد ReplaceAllShapesWithImageRequest استفاده کنید.

تگ shape دارای ویژگی‌های 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 مشخص شده است، قرار می‌گیرد. برای تعیین تصویری که جایگزین شکل می‌شود، API تصویر را با استفاده از 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
      }
    }
  ]
}