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

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

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

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

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

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

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

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

קריאת הטקסט שנבחר

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

השיטות select() ו-select(true) שקולות.

לדוגמה:

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

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

כדי להוסיף עוד רכיבי דף לבחירה, משתמשים בשיטה 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();