انتخاب موارد در یک ارائه

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

یک اسکریپت فقط می‌تواند به انتخاب‌های کاربری که اسکریپت را اجرا می‌کند دسترسی داشته باشد.

این انتخاب، تصویری از وضعیت اولیه‌ی اسکریپت است. اگر کاربر کلیک کند و انتخاب در حین اجرای اسکریپت تغییر کند، آن تغییرات اعمال نخواهند شد.

انتخاب‌ها و نوع انتخاب

با استفاده از کلاس Selection، موارد انتخاب شده را بخوانید. این کلاس بر اساس نوع شیء(های) انتخاب شده، متدهای مختلفی برای دریافت اشیاء انتخاب شده دارد.

نوع شمارشی SelectionType نوع خاصی از اشیاء انتخاب شده را نشان می‌دهد. برای مثال، اگر کاربر متنی را در یک شکل انتخاب کرده باشد، نوع انتخاب TEXT خواهد بود. در این حالت، می‌توانید محدوده انتخاب شده متن را با استفاده از متد selection.getTextRange() بازیابی کنید.

همچنین می‌توانید شیء حاوی انتخاب را بازیابی کنید. برای مثال، می‌توانید شکلی را که شامل متن انتخاب شده است با استفاده از selection.getPageElementRange().getPageElements()[0] بازیابی کنید. به طور مشابه، صفحه‌ای که شامل شکل در برگیرنده است، صفحه فعال فعلی است؛ برای بازیابی آن صفحه، از selection.getCurrentPage() استفاده کنید.

خواندن متن انتخاب شده

برای خواندن انتخاب، از متد Presentation.getSelection() همانطور که در مثال زیر نشان داده شده است، استفاده کنید:

اسلایدها/انتخاب/انتخاب.gs

مشاهده در گیت‌هاب

const selection = SlidesApp.getActivePresentation().getSelection();

صفحه فعلی را بخوانید

برای بازیابی صفحه فعلی که کاربر در حال مشاهده آن است، از متدهای getSelection() و getCurrentPage() به شرح زیر استفاده کنید:

اسلایدها/انتخاب/انتخاب.gs

مشاهده در گیت‌هاب

const currentPage = SlidesApp.getActivePresentation()
  .getSelection()
  .getCurrentPage();

توجه داشته باشید که صفحه فعلی می‌تواند هر یک از انواع زیر باشد:

• اسلاید
• استاد
• طرح بندی

صفحه فعلی می‌تواند یک یا چند شیء انتخاب شده داشته باشد و SelectionType نوع انتخاب را تعیین می‌کند.

انتخاب را بر اساس نوع انتخاب بخوانید

مثال زیر نشان می‌دهد که چگونه می‌توانید از نوع انتخاب برای خواندن انتخاب فعلی به روشی متناسب با نوع استفاده کنید.

اسلایدها/انتخاب/انتخاب.gs

مشاهده در گیت‌هاب

const selection = SlidesApp.getActivePresentation().getSelection();
const selectionType = selection.getSelectionType();
let currentPage;
switch (selectionType) {
  case SlidesApp.SelectionType.NONE:
    console.log("Nothing selected");
    break;
  case SlidesApp.SelectionType.CURRENT_PAGE:
    currentPage = selection.getCurrentPage();
    console.log(`Selection is a page with ID: ${currentPage.getObjectId()}`);
    break;
  case SlidesApp.SelectionType.PAGE_ELEMENT: {
    const pageElements = selection.getPageElementRange().getPageElements();
    console.log(`There are ${pageElements.length} page elements selected.`);
    break;
  }
  case SlidesApp.SelectionType.TEXT: {
    const tableCellRange = selection.getTableCellRange();
    if (tableCellRange !== null) {
      const tableCell = tableCellRange.getTableCells()[0];
      console.log(
        `Selected text is in a table at row ${tableCell.getRowIndex()}, column ${tableCell.getColumnIndex()}`,
      );
    }
    const textRange = selection.getTextRange();
    if (textRange.getStartIndex() === textRange.getEndIndex()) {
      console.log(`Text cursor position: ${textRange.getStartIndex()}`);
    } else {
      console.log(
        `Selection is a text range from: ${textRange.getStartIndex()} to: ${textRange.getEndIndex()} is selected`,
      );
    }
    break;
  }
  case SlidesApp.SelectionType.TABLE_CELL: {
    const tableCells = selection.getTableCellRange().getTableCells();
    const table = tableCells[0].getParentTable();
    console.log(`There are ${tableCells.length} table cells selected.`);
    break;
  }
  case SlidesApp.SelectionType.PAGE: {
    const pages = selection.getPageRange().getPages();
    console.log(`There are ${pages.length} pages selected.`);
    break;
  }
  default:
    break;
}

انتخاب‌های متن را بخوانید

متن انتخاب شده را با استفاده از متد Selection.getTextRange() بخوانید. دو نوع انتخاب متن وجود دارد:

• انتخاب محدوده : اگر شکلی حاوی متن "سلام" باشد و "او" انتخاب شده باشد، محدوده‌ی برگردانده شده دارای startIndex=0 و endIndex=2 خواهد بود.
• انتخاب مکان‌نما : اگر شکلی حاوی متن "Hello" باشد و مکان‌نما بعد از "H" ("H|ello") باشد، محدوده‌ی برگردانده شده، محدوده‌ی خالی با startIndex=1 و endIndex=1 خواهد بود.

اصلاح انتخاب

اسکریپت می‌تواند انتخاب کاربر را تغییر دهد. هرگونه تغییر انتخابی که اسکریپت در ارائه ایجاد می‌کند، در عملیات انتخاب بعدی در طول اجرای اسکریپت منعکس می‌شود.

تغییرات انتخاب فقط پس از اتمام اجرای اسکریپت یا هنگام فراخوانی Presentation.saveAndClose() در مرورگر کاربر منعکس می‌شوند.

انتخاب صفحه فعلی

یک صفحه در ارائه فعال می‌تواند با فراخوانی متد selectAsCurrentPage() به عنوان صفحه فعلی انتخاب شود. این متد هرگونه عنصر صفحه، صفحه یا متن انتخاب شده قبلی را حذف می‌کند. بنابراین استفاده از این متد در صفحه فعلی به شما امکان می‌دهد هرگونه انتخاب فعلی در صفحه را از حالت انتخاب خارج کنید. به عنوان مثال:

اسلایدها/انتخاب/انتخاب.gs

مشاهده در گیت‌هاب

// Select the first slide as the current page selection and remove any previous selection.
const selection = SlidesApp.getActivePresentation().getSelection();
const slide = SlidesApp.getActivePresentation().getSlides()[0];
slide.selectAsCurrentPage();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.CURRENT_PAGE
// selection.getCurrentPage() = slide
//

انتخاب یک عنصر صفحه

برای انتخاب یک عنصر صفحه در یک صفحه، از متد PageElement.select() استفاده کنید. این متد همچنین عناصر صفحه‌ای که قبلاً انتخاب شده‌اند را از حالت انتخاب خارج می‌کند.

متدهای select() و select(true) معادل یکدیگر هستند.

برای مثال:

اسلایدها/انتخاب/انتخاب.gs

مشاهده در گیت‌هاب

const slide = SlidesApp.getActivePresentation().getSlides()[0];
const pageElement = slide.getPageElements()[0];
// Only select this page element and remove any previous selection.
pageElement.select();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.PAGE_ELEMENT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements()[0] = pageElement
//

انتخاب چندین عنصر صفحه

برای اضافه کردن عناصر صفحه اضافی به انتخاب، از متد PageElement.select(false) استفاده کنید. تمام عناصر صفحه باید در صفحه فعلی باشند.

اسلایدها/انتخاب/انتخاب.gs

مشاهده در گیت‌هاب

const slide = SlidesApp.getActivePresentation().getSlides()[0];
// First select the slide page, as the current page selection.
slide.selectAsCurrentPage();
// Then select all the page elements in the selected slide page.
const pageElements = slide.getPageElements();
for (let i = 0; i < pageElements.length; i++) {
  pageElements[i].select(false);
}
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.PAGE_ELEMENT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements() = pageElements
//

انتخاب را تغییر شکل دهید

ویرایش‌هایی که اسکریپت شما انجام می‌دهد می‌تواند انتخاب فعلی را تغییر دهد ، به طوری که آنچه انتخاب شده است در نتیجه ویرایش تغییر کند. برای مثال:

1. فرض کنید دو شکل A و B را انتخاب کرده‌اید.
2. در مرحله بعد، اسکریپت شما شکل A را حذف می‌کند.
3. در نتیجه، ناحیه انتخاب شده در برابر ویرایش تغییر شکل می‌دهد تا فقط شکل B انتخاب شود.

مثال زیر نشان می‌دهد که چگونه می‌توان با دستکاری عناصر صفحه انتخاب شده، ناحیه انتخاب شده را تغییر شکل داد.

اسلایدها/انتخاب/انتخاب.gs

مشاهده در گیت‌هاب

const slide = SlidesApp.getActivePresentation().getSlides()[0];
const shape1 = slide.getPageElements()[0].asShape();
const shape2 = slide.getPageElements()[1].asShape();
// Select both the shapes.
shape1.select();
shape2.select(false);
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.PAGE_ELEMENT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements() = [shape1, shape2]
//
// Remove one shape.
shape2.remove();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.PAGE_ELEMENT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements() = [shape1]
//

انتخاب متن

متن موجود در یک شکل یا در یک سلول جدول را می‌توان با استفاده از متد TextRange.select() انتخاب کرد. اگر متن در یک شکل قرار داشته باشد، آن شکل نیز انتخاب می‌شود. اگر متن در یک سلول جدول قرار داشته باشد، آن سلول جدول و جدول در برگیرنده آن هر دو انتخاب می‌شوند.

این همچنین صفحه والد را به عنوان صفحه فعلی تنظیم می‌کند.

انتخاب محدوده در یک شکل

مثال زیر نحوه انتخاب محدوده‌ای را در متن موجود در یک شکل نشان می‌دهد.

اسلایدها/انتخاب/انتخاب.gs

مشاهده در گیت‌هاب

const slide = SlidesApp.getActivePresentation().getSlides()[0];
const shape = slide.getPageElements()[0].asShape();
shape.getText().setText("Hello");
// Range selection: Select the text range 'He'.
shape.getText().getRange(0, 2).select();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.TEXT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements()[0] = shape
// selection.getTextRange().getStartIndex() = 0
// selection.getTextRange().getEndIndex() = 2
//

انتخاب مکان نما در یک شکل

مثال زیر نحوه انتخاب مکان‌نما را در متن موجود در یک شکل نشان می‌دهد.

اسلایدها/انتخاب/انتخاب.gs

مشاهده در گیت‌هاب

const slide = SlidesApp.getActivePresentation().getSlides()[0];
const shape = slide.getPageElements()[0].asShape();
shape.getText().setText("Hello");
// Cursor selection: Place the cursor after 'H' like 'H|ello'.
shape.getText().getRange(1, 1).select();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.TEXT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements()[0] = shape
// selection.getTextRange().getStartIndex() = 1
// selection.getTextRange().getEndIndex() = 1
//

انتخاب محدوده در یک سلول جدول

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

اسلایدها/انتخاب/انتخاب.gs

مشاهده در گیت‌هاب

const slide = SlidesApp.getActivePresentation().getSlides()[0];
const table = slide.getPageElements()[0].asTable();
const tableCell = table.getCell(0, 1);
tableCell.getText().setText("Hello");
// Range selection: Select the text range 'He'.
tableCell.getText().getRange(0, 2).select();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.TEXT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements()[0] = table
// selection.getTableCellRange().getTableCells()[0] = tableCell
// selection.getTextRange().getStartIndex() = 0
// selection.getTextRange().getEndIndex() = 2
//

انتخاب مکان نما در TableCell

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

اسلایدها/انتخاب/انتخاب.gs

مشاهده در گیت‌هاب

const slide = SlidesApp.getActivePresentation().getSlides()[0];
const table = slide.getPageElements()[0].asTable();
const tableCell = table.getCell(0, 1);
tableCell.getText().setText("Hello");
// Cursor selection: Place the cursor after 'H' like 'H|ello'.
tableCell.getText().getRange(1, 1).select();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.TEXT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements()[0] = table
// selection.getTableCellRange().getTableCells()[0] = tableCell
// selection.getTextRange().getStartIndex() = 1
// selection.getTextRange().getEndIndex() = 1
//

تبدیل انتخاب با ویرایش‌های متنی

مثال زیر نشان می‌دهد که چگونه می‌توان با ویرایش متن انتخاب‌شده، ناحیه انتخاب‌شده را تغییر شکل داد.

اسلایدها/انتخاب/انتخاب.gs

مشاهده در گیت‌هاب

const slide = SlidesApp.getActivePresentation().getSlides()[0];
const shape = slide.getPageElements()[0].asShape();
const textRange = shape.getText();
textRange.setText("World");
// Select all the text 'World'.
textRange.select();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.TEXT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements()[0] = shape
// selection.getTextRange().getStartIndex() = 0
// selection.getTextRange().getEndIndex() = 6
//
// Add some text to the shape, and the selection will be transformed.
textRange.insertText(0, "Hello ");

// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.TEXT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements()[0] = shape
// selection.getTextRange().getStartIndex() = 0
// selection.getTextRange().getEndIndex() = 12
//

لغو انتخاب

هیچ روش صریحی برای لغو انتخاب متن یا عناصر صفحه وجود ندارد. با این حال، این نتیجه را می‌توان با استفاده از روش‌های Page.selectAsCurrentPage() یا pageElement.select() به دست آورد.

انتخاب صفحه فعلی

مثال زیر نحوه‌ی لغو انتخاب‌های فعلی در یک صفحه را با تنظیم آن صفحه به عنوان صفحه‌ی فعلی نشان می‌دهد.

اسلایدها/انتخاب/انتخاب.gs

مشاهده در گیت‌هاب

// Unselect one or more page elements already selected.
//
// In case one or more page elements in the first slide are selected, setting the
// same (or any other) slide page as the current page would do the unselect.
//
const slide = SlidesApp.getActivePresentation().getSlides()[0];
slide.selectAsCurrentPage();

انتخاب یک عنصر صفحه

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

اسلایدها/انتخاب/انتخاب.gs

مشاهده در گیت‌هاب

// Unselect one or more page elements already selected.
//
// In case one or more page elements in the first slide are selected,
// selecting any pageElement in the first slide (or any other pageElement) would
// do the unselect and select that pageElement.
//
const slide = SlidesApp.getActivePresentation().getSlides()[0];
slide.getPageElements()[0].select();