選取簡報中的項目

選取項目是指在開啟的簡報頁面中目前選取的項目，例如一段醒目文字或表格。本指南說明如何使用 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() 方法。這麼做也會取消選取先前選取的任何網頁元素。

例如：

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