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

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

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

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

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

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

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

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

קריאת הבחירה

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

slides/selection/selection.gs

הצגת הקוד ב-GitHub

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

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

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

segments/selection/selection.gs

הצגת הקוד ב-GitHub

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

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

• שקף
• מאסטר
• פריסה

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

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

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

slides/selection/selection.gs

הצגת הקוד ב-GitHub

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

הצגת הקוד ב-GitHub

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

ה-method select() ו-select(true) מקבילות.

לדוגמה:

slides/selection/selection.gs

הצגת הקוד ב-GitHub

  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

הצגת הקוד ב-GitHub

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

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

segments/selection/selection.gs

הצגת הקוד ב-GitHub

  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

הצגת הקוד ב-GitHub

  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

הצגת הקוד ב-GitHub

  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

הצגת הקוד ב-GitHub

  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

הצגת הקוד ב-GitHub

  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

הצגת הקוד ב-GitHub

  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

הצגת הקוד ב-GitHub

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

בחירת רכיב דף

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

segments/selection/selection.gs

הצגת הקוד ב-GitHub

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