選取簡報中的項目

「selection」是目前開啟簡報頁面中選取的任何項目，例如醒目顯示的文字或表格。本指南將說明如何使用 Apps Script 擷取及設定使用中的簡報。

所選取的項目為指令碼開始時的快照。如果使用者在指令碼執行期間點選動作，選項有所變更，系統並不會反映這些變更。

選項和選取類型

您可以使用選取類別讀取選擇。該類別提供多種方法，可根據所選物件的類型取得所選物件。

SelectionType 列舉代表所選物件的特定類型。例如，如果使用者已在某個形狀中選取部分文字，選取類型為 TEXT。在這種情況下，您可以使用 selection.getTextRange() 方法擷取所選文字範圍。

您也可以擷取包含所選選項的物件。繼續上述範例，您可以使用 selection.getPageElementRange().getPageElements()[0] 擷取包含所選文字的形狀。同樣地，包含封閉形狀的頁面也是目前使用中的頁面；如要擷取該頁面，請使用 selection.getCurrentPage()。

讀出選取範圍

如要讀取所選資料，請使用 Presentation.getSelection() 方法，如以下範例所示：

投影片/selection/selection.gs
const selection = SlidesApp.getActivePresentation().getSelection();

讀取目前網頁

如要擷取使用者目前查看的 Page，請使用 getSelection() 和 getCurrentPage() 方法，如下所示：

投影片/selection/selection.gs
const currentPage = SlidesApp.getActivePresentation().getSelection().getCurrentPage();

請注意，目前頁面可以是下列任一類型：

目前頁面中可以選取一或多個物件，所選類型則取決於 SelectionType。

根據選取類型讀取選項

以下範例說明如何使用選取類型，以適合類型的方式讀取目前選取的項目。

投影片/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() 方法，可以將使用中呈現的頁面選取為目前的頁面。這個方法會移除先前選取的網頁元素、網頁或文字選項。因此，如果在目前頁面使用這個方法，就能取消選取頁面上的任何目前選取項目。例如：

投影片/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() 方法。 也會取消選取之前選取的頁面元素。

例如：

投影片/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) 方法。所有頁面元素都必須位於目前的頁面中。

投影片/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。

以下範例說明如何透過操控所選頁面元素轉換選項。

投影片/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() 方法選取形狀或表格儲存格中包含的文字。如果文字包含在形狀中，系統會一併選取該形狀。如果表格儲存格含有文字，系統會同時選取該表格儲存格及其所屬表格。

系統也會將上層頁面設為目前的頁面。

形狀的範圍選項

以下範例說明如何在形狀中的文字中選取範圍。

投影片/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
//

在形狀中選取遊標

以下範例說明如何在形狀中的文字中選取遊標。

投影片/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
//

在表格儲存格中選取範圍

以下範例說明如何在表格儲存格中的文字中選取範圍。

投影片/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 中選取遊標

以下範例說明如何在表格儲存格中的文字內選取遊標。

投影片/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
//

使用文字編輯功能進行選取的轉換

以下範例說明如何透過編輯所選文字來轉換選擇。

投影片/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() 方法達成此結果。

選取目前頁面

以下範例說明如何將頁面設為目前頁面，藉此取消選取頁面上現有的任何選取項目。

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

選取網頁元素

以下範例說明如何選取一個網頁元素，藉此取消選取網頁上目前所有的選取項目，並移除選取範圍的所有其他項目。

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