בחירת פריטים במצגת

הבחירה היא מה שנבחר כרגע בדף פתוח של המצגת, למשל קטע של טקסט מודגש או טבלה. במדריך הזה מוסבר איך לקבל ולהגדיר את הבחירה במצגת פעילה באמצעות Apps Script.

הבחירה היא תמונת מצב של מה שקרה כשהסקריפט התחיל. אם המשתמש הקליקים והבחירה משתנים בזמן שהסקריפט פועל, השינויים האלה לא ישתקף.

בחירות וסוג הבחירה

אפשר לקרוא את הבחירה באמצעות הכיתה Selection. בכיתה יש שיטות שונות לקבל את האובייקטים שנבחרו על סמך סוג האובייקטים שנבחרו.

המאפיין המסווג SelectionType מייצג את הסוג הספציפי של העצמים שנבחרו. לדוגמה, אם למשתמש יש נבחר טקסט כלשהו בצורה, סוג הבחירה להיות TEXT. במקרה כזה, אפשר לאחזר את טווח הטקסט שנבחר באמצעות אמצעי תשלום אחד (selection.getTextRange()).

אפשר גם לאחזר את האובייקט שמכיל את הבחירה; שממשיכים בדוגמה שלמעלה, אפשר לאחזר את הצורה שמכילה את הטקסט שנבחר באמצעות selection.getPageElementRange().getPageElements()[0] באופן דומה, הדף מכיל את הצורה המצורפת הוא הדף הפעיל הנוכחי; כדי לאחזר את הדף הזה, יש להשתמש ב-selection.getCurrentPage().

בתהליך של קריאת הפריטים שנבחרו

כדי לקרוא את הטקסט שנבחר, משתמשים Presentation.getSelection() כפי שמוצג בדוגמה הבאה:

segments/selection/selection.gs
const selection = SlidesApp.getActivePresentation().getSelection();

קריאת הדף הנוכחי

כדי לאחזר את הדף הנוכחי ש המשתמש צופה, יש להשתמש getSelection() וגם getCurrentPage() באופן הבא:

segments/selection/selection.gs
const currentPage = SlidesApp.getActivePresentation().getSelection().getCurrentPage();

לתשומת ליבכם, הדף הנוכחי יכול להיות כל אחד מהסוגים הבאים:

בדף הנוכחי ניתן לבחור אובייקט אחד או יותר, ואת סוג הבחירה קובע את סוג הבחירה.

קריאת הפריטים שנבחרו על סמך סוג הבחירה

הדוגמה הבאה ממחישה איך אפשר להשתמש בסוג הבחירה כדי לקרוא את הבחירה הנוכחית בדרך שמתאימה לסוג.

segments/selection/selection.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().

בחירת הדף הנוכחי

אפשר לבחור דף במצגת הפעילה כדף הנוכחי באמצעות קריאה ה-method selectAsCurrentPage(). השיטה הזו מסירה את החלק הקודם של הדף, את הדף או את בחירת הטקסט. אז באמצעות השיטה הזו בדף הנוכחי מאפשרת לך לבטל את הבחירה באפשרויות הנוכחיות הדף הזה. לדוגמה:

slides/selection/selection.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()‎. הפעולה הזו גם מבטלת את הבחירה של רכיבי דף שנבחרו בעבר.

לדוגמה:

segments/selection/selection.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
//

בחירה של מספר רכיבים בדף

כדי לצרף לבחירה רכיבי דף נוספים, משתמשים ב-method‏ PageElement.select(false). כל רכיבי הדף חייבים להיות בדף הנוכחי.

slides/selection/selection.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.

הדוגמה הבאה ממחישה איך אפשר לשנות את הבחירה באמצעות מניפולציה מרכיבי הדף שנבחרו.

segments/selection/selection.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(). אם הטקסט נמצא בתוך צורה, גם הצורה תיבחר. אם הטקסט כלול בתא בטבלה, התא בטבלה והתא המצורף נבחרו שתיהן.

הפעולה הזו גם מגדירה את דף ההורה בתור הדף הנוכחי.

בחירת טווח בצורה

הדוגמה הבאה מראה איך לבצע בחירת טווח בתוך טקסט שכלול בצורה.

segments/selection/selection.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
//

בחירת סמן בתוך צורה

בדוגמה הבאה מוסבר איך לבחור טקסט בתוך צורה באמצעות הסמן.

segments/selection/selection.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
//

בחירת טווח בתא בטבלה

הדוגמה הבאה מראה איך לבצע בחירת טווח בתוך טקסט שכלול בתא בטבלה.

segments/selection/selection.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

הדוגמה הבאה מראה איך לבצע בחירה של סמן בתוך טקסט שכלול בתא בטבלה.

segments/selection/selection.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
//

טרנספורמציה של בחירה עם עריכות טקסט

הדוגמה הבאה מראה איך אפשר לשנות את הבחירה על ידי עריכת הטקסט שנבחר.

segments/selection/selection.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() אמצעי תשלום.

בחירת דף נוכחי

בדוגמה הבאה מוסבר איך לבטל את הבחירה של פריטים בדף מסוים על ידי הגדרת הדף הזה כדף הנוכחי.

segments/selection/selection.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();

בחירת רכיב דף

הדוגמה הבאה מראה איך לבטל את הבחירה באפשרויות הנוכחיות בדף על ידי בחירת רכיב דף אחד, ובכך הסרת כל שאר הפריטים מהבחירה.

slides/selection/selection.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();