選取簡報中的項目

選取項目是指目前在開啟的簡報頁面中選取的內容，例如醒目顯示的文字範圍或表格。本指南說明如何使用 Apps Script，在進行中的簡報中取得及設定選取範圍。

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

選取項目和選取類型

您可以使用 Selection 類別讀取選取範圍。這個類別提供各種方法，可根據所選物件的類型取得所選物件。

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

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

朗讀所選內容

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

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

朗讀目前網頁

如要擷取使用者目前檢視的 Page，請使用 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() 方法。 這項操作也會取消選取先前選取的任何網頁元素。

例如：

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. 因此，選取範圍會根據編輯內容轉換，只選取形狀 B。

以下範例說明如何透過操弄所選頁面元素來轉換選取範圍。

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