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

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

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

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

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

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

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

קריאת הבחירה

כדי לקרוא את הבחירה, משתמשים ב-method‏ Presentation.getSelection(), כפי שמתואר בדוגמה הבאה:

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

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

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

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

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

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

קריאת הבחירה על סמך סוג הבחירה

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

slides/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(). יש שני סוגים של בחירת טקסט:

  • בחירת טווח: אם צורה מכילה את הטקסט 'Hello', והאות 'H' מסומנת, הטווח המוחזר יהיה startIndex=0 ו-endIndex=2.
  • בחירת הסמן: אם צורה מכילה את הטקסט 'Hello', והסמן נמצא אחרי האות 'H' ("H|ello"), הטווח המוחזר הוא טווח ריק עם startIndex=1 ו-endIndex=1.

שינוי הבחירה

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

השינויים בבחירה משתקפים בדפדפן של המשתמש רק אחרי השלמת ההפעלה של הסקריפט, או כשמתבצעת קריאה ל-Presentation.saveAndClose().

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

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

לדוגמה:

slides/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. כתוצאה מכך, הבחירה עוברת טרנספורמציה בהתאם לעריכה כך שרק הצורה ב' תיבחר.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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, 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();