سرویس اسلایدهای پیشرفته

سرویس اسلایدهای پیشرفته به شما امکان می‌دهد با استفاده از Apps Script به API اسلایدها دسترسی پیدا کنید. این سرویس به اسکریپت‌ها اجازه می‌دهد تا محتوا را در اسلایدهای گوگل بخوانند و ویرایش کنند.

مرجع

برای اطلاعات دقیق در مورد این سرویس، به مستندات مرجع برای API اسلایدها مراجعه کنید. مانند تمام سرویس‌های پیشرفته در Apps Script، سرویس اسلایدهای پیشرفته از همان اشیاء، متدها و پارامترهای API عمومی استفاده می‌کند. برای اطلاعات بیشتر، به بخش «نحوه تعیین امضاهای متد» مراجعه کنید.

برای گزارش مشکلات و یافتن پشتیبانی‌های دیگر، به راهنمای پشتیبانی اسلایدها مراجعه کنید.

کد نمونه

کد نمونه زیر از نسخه ۱ این API استفاده می‌کند.

ایجاد یک ارائه جدید

مثال زیر نحوه ایجاد یک ارائه جدید با استفاده از سرویس پیشرفته اسلایدها را نشان می‌دهد. این معادل نمونه دستور العمل ایجاد یک ارائه جدید است.

پیشرفته/اسلایدها.gs
/**
 * Create a new presentation.
 * @return {string} presentation Id.
 * @see https://developers.google.com/slides/api/reference/rest/v1/presentations/create
 */
function createPresentation() {
  try {
    const presentation = Slides.Presentations.create({
      title: "MyNewPresentation",
    });
    console.log(`Created presentation with ID: ${presentation.presentationId}`);
    return presentation.presentationId;
  } catch (e) {
    // TODO (developer) - Handle exception
    console.log("Failed with error %s", e.message);
  }
}

ایجاد اسلاید جدید

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

پیشرفته/اسلایدها.gs
/**
 * Create a new slide.
 * @param {string} presentationId The presentation to add the slide to.
 * @return {Object} slide
 * @see https://developers.google.com/slides/api/reference/rest/v1/presentations/batchUpdate
 */
function createSlide(presentationId) {
  // You can specify the ID to use for the slide, as long as it's unique.
  const pageId = Utilities.getUuid();

  const requests = [
    {
      createSlide: {
        objectId: pageId,
        insertionIndex: 1,
        slideLayoutReference: {
          predefinedLayout: "TITLE_AND_TWO_COLUMNS",
        },
      },
    },
  ];
  try {
    const slide = Slides.Presentations.batchUpdate(
      { requests: requests },
      presentationId,
    );
    console.log(
      `Created Slide with ID: ${slide.replies[0].createSlide.objectId}`,
    );
    return slide;
  } catch (e) {
    // TODO (developer) - Handle Exception
    console.log("Failed with error %s", e.message);
  }
}

خواندن شناسه‌های شیء عنصر صفحه

مثال زیر نحوه بازیابی شناسه‌های شیء برای هر عنصر صفحه در یک اسلاید خاص را با استفاده از یک ماسک فیلد نشان می‌دهد. این معادل شناسه‌های شیء عنصر خوانده شده از یک نمونه دستور پخت صفحه است.

پیشرفته/اسلایدها.gs
/**
 * Read page element IDs.
 * @param {string} presentationId The presentation to read from.
 * @param {string} pageId The page to read from.
 * @return {Object} response
 * @see https://developers.google.com/slides/api/reference/rest/v1/presentations.pages/get
 */
function readPageElementIds(presentationId, pageId) {
  // You can use a field mask to limit the data the API retrieves
  // in a get request, or what fields are updated in an batchUpdate.
  try {
    const response = Slides.Presentations.Pages.get(presentationId, pageId, {
      fields: "pageElements.objectId",
    });
    console.log(response);
    return response;
  } catch (e) {
    // TODO (developer) - Handle Exception
    console.log("Failed with error %s", e.message);
  }
}

یک کادر متن جدید اضافه کنید

مثال زیر نحوه اضافه کردن یک کادر متن جدید به اسلاید و افزودن متن به آن را نشان می‌دهد. این معادل نمونه دستور العمل افزودن کادر متن به اسلاید است.

پیشرفته/اسلایدها.gs
/**
 * Add a new text box with text to a page.
 * @param {string} presentationId The presentation ID.
 * @param {string} pageId The page ID.
 * @return {Object} response
 * @see https://developers.google.com/slides/api/reference/rest/v1/presentations/batchUpdate
 */
function addTextBox(presentationId, pageId) {
  // You can specify the ID to use for elements you create,
  // as long as the ID is unique.
  const pageElementId = Utilities.getUuid();

  const 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,
      },
    },
  ];
  try {
    const response = Slides.Presentations.batchUpdate(
      { requests: requests },
      presentationId,
    );
    console.log(
      `Created Textbox with ID: ${response.replies[0].createShape.objectId}`,
    );
    return response;
  } catch (e) {
    // TODO (developer) - Handle Exception
    console.log("Failed with error %s", e.message);
  }
}

قالب‌بندی متن با شکل

مثال زیر نحوه قالب‌بندی متن یک شکل، به‌روزرسانی رنگ، فونت و زیرخط‌دار کردن متن آن را نشان می‌دهد. این معادل نمونه دستور قالب‌بندی متن در یک شکل یا جعبه متن است.

پیشرفته/اسلایدها.gs
/**
 * Format the text in a shape.
 * @param {string} presentationId The presentation ID.
 * @param {string} shapeId The shape ID.
 * @return {Object} replies
 * @see https://developers.google.com/slides/api/reference/rest/v1/presentations/batchUpdate
 */
function formatShapeText(presentationId, shapeId) {
  const requests = [
    {
      updateTextStyle: {
        objectId: shapeId,
        fields: "foregroundColor,bold,italic,fontFamily,fontSize,underline",
        style: {
          foregroundColor: {
            opaqueColor: {
              themeColor: "ACCENT5",
            },
          },
          bold: true,
          italic: true,
          underline: true,
          fontFamily: "Corsiva",
          fontSize: {
            magnitude: 18,
            unit: "PT",
          },
        },
        textRange: {
          type: "ALL",
        },
      },
    },
  ];
  try {
    const response = Slides.Presentations.batchUpdate(
      { requests: requests },
      presentationId,
    );
    return response.replies;
  } catch (e) {
    // TODO (developer) - Handle Exception
    console.log("Failed with error %s", e.message);
  }
}

بهترین شیوه‌ها

به‌روزرسانی‌های دسته‌ای

هنگام استفاده از سرویس پیشرفته اسلایدها، به جای فراخوانی batchUpdate در یک حلقه، چندین درخواست را در یک آرایه ترکیب کنید.

انجام ندهید — تابع batchUpdate در یک حلقه فراخوانی کنید.

var titles = ["slide 1", "slide 2"];
for (var i = 0; i < titles.length; i++) {
  Slides.Presentations.batchUpdate(preso, {
    requests: [{
      createSlide: ...
    }]
  });
}

انجام دهید — تابع batchUpdate با آرایه‌ای از به‌روزرسانی‌ها فراخوانی کنید.

var requests = [];
var titles = ["slide 1", "slide 2"];
for (var i = 0; i < titles.length; i++) {
  requests.push({ createSlide: ... });
}

Slides.Presentations.batchUpdate(preso, {
  requests: requests
});