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

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

slides/selection/selection.gs

הצגת הקוד ב-GitHub

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

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

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

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

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

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

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;
}

הקראה של טקסט שנבחר

אפשר לקרוא את הטקסט שנבחר באמצעות ה-method‏ Selection.getTextRange(). יש שני סוגים של בחירת טקסט:

• בחירת טווח: אם צורה מכילה את הטקסט 'Hello' ונבחר הטקסט 'He', הטווח שמוחזר הוא 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(). בנוסף, כל רכיבי הדף שנבחרו קודם יבוטלו.

השיטות 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
//

בחירה של כמה רכיבי דף

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

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

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

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

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

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

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

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

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