Como selecionar itens em uma apresentação

A seleção é aquilo que está atualmente selecionado em uma página de apresentação aberta, como um período de texto destacado ou uma tabela. Este guia ensina como obter e definir a seleção em uma apresentação ativa usando o Apps Script.

A seleção é um resumo do que era quando o script foi iniciado. Se o usuário clicar e a seleção mudar enquanto o script estiver em execução, essas mudanças não serão refletidas.

Seleção e tipo de seleção

Leia a seleção usando a classe Selection. A classe tem vários métodos para receber os objetos selecionados com base no tipo dos objetos selecionados.

O tipo enumerado SelectionType representa o tipo específico de objetos selecionados. Por exemplo, se o usuário selecionou algum texto em uma forma, o tipo de seleção será TEXT. Nesse caso, é possível extrair o intervalo de texto selecionado usando o método selection.getTextRange().

Você também pode extrair o objeto que contém a seleção. Continuando com o exemplo acima, também é possível recuperar a forma que contém o texto selecionado usando selection.getPageElementRange().getPageElements()[0]. Da mesma forma, a página que contém a forma de delimitação é a página ativa atual. Para recuperá-la, use selection.getCurrentPage().

Como ler a seleção

Para ler a seleção, use o método Presentation.getSelection() como mostrado no exemplo a seguir:

slides/seleção/seleção.gs
const selection = SlidesApp.getActivePresentation().getSelection();

Como ler a página atual

Para recuperar a Page atual que o usuário está visualizando, use os métodos getSelection() e getCurrentPage() da seguinte maneira:

slides/seleção/seleção.gs
const currentPage = SlidesApp.getActivePresentation().getSelection().getCurrentPage();

A página atual pode ser de qualquer um dos seguintes tipos:

A página atual pode ter um ou mais objetos selecionados, e o SelectionType determina o tipo de seleção.

Como ler a seleção com base no tipo

O exemplo abaixo mostra como usar o tipo de seleção para ler a seleção atual de uma maneira adequada ao tipo.

slides/seleção/seleção.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;
}

Leitura de seleções de texto

Leia a seleção de texto usando o método Selection.getTextRange(). Há dois tipos de seleção de texto:

  • Seleção de intervalo: se uma forma contiver o texto "Hello" e "He" for selecionado, o intervalo retornado terá startIndex=0 e endIndex=2.
  • Seleção de cursor: se uma forma contiver o texto "Hello" e o cursor estiver depois de "H" ("H|ello"), o intervalo retornado será um intervalo vazio com startIndex=1 e endIndex=1.

Modificando a seleção

O script pode modificar a seleção do usuário. As mudanças de seleção feitas pelo script na apresentação são refletidas nas operações de seleção subsequentes durante a execução dele.

As mudanças de seleção são refletidas no navegador do usuário somente após a conclusão da execução do script ou quando Presentation.saveAndClose() é chamado.

Como selecionar a página atual

Uma página na apresentação ativa pode ser selecionada como a página atual chamando o método selectAsCurrentPage(). Esse método remove qualquer elemento de página, página ou seleção de texto anterior. Portanto, usar esse método na página atual permite desmarcar todas as seleções atuais na página. Exemplo:

slides/seleção/seleção.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
//

Selecionar um elemento de página

Para selecionar um elemento de página, use o método PageElement.select(). Isso também desmarca todos os elementos de página selecionados anteriormente.

Exemplo:

slides/seleção/seleção.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
//

Selecionar vários elementos de página

Para anexar outros elementos de página à seleção, use o método PageElement.select(false). Todos os elementos da página precisam estar na página atual.

slides/seleção/seleção.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
//

Como transformar a seleção

As edições realizadas pelo script podem transformar a seleção atual, para que o item selecionado mude como resultado da edição. Exemplo:

  1. Digamos que você tenha duas formas A e B selecionadas.
  2. Em seguida, o script remove a forma A.
  3. Como resultado, a seleção é transformada em relação à edição para que apenas a forma B seja selecionada.

O exemplo a seguir mostra como transformar a seleção manipulando elementos de página selecionados.

slides/seleção/seleção.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]
//

Como selecionar texto

O texto contido em uma forma ou em uma célula da tabela pode ser selecionado com o método TextRange.select(). Se o texto estiver contido em uma forma, essa forma também será selecionada. Se o texto estiver em uma célula da tabela, essa célula e a tabela correspondente serão selecionadas.

Isso também define a página principal como a página atual.

Seleção de intervalo em uma forma

O exemplo a seguir mostra como fazer uma seleção de intervalo no texto contido em uma forma.

slides/seleção/seleção.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
//

Seleção do cursor em uma forma

O exemplo a seguir mostra como fazer uma seleção de cursor no texto contido em uma forma.

slides/seleção/seleção.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
//

Seleção de intervalo em uma célula da tabela

O exemplo a seguir mostra como fazer uma seleção de intervalo no texto contido em uma célula da tabela.

slides/seleção/seleção.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
//

Seleção do cursor em TableCell

O exemplo a seguir mostra como fazer uma seleção de cursor no texto contido em uma célula da tabela.

slides/seleção/seleção.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
//

Transformação de seleção com edições textuais

O exemplo a seguir mostra como a seleção pode ser transformada editando o texto selecionado.

slides/seleção/seleção.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
//

Desmarcando

Não há métodos explícitos para desmarcar elementos de texto ou página. No entanto, esse resultado pode ser alcançado usando os métodos Page.selectAsCurrentPage() ou pageElement.select().

Selecionar uma página atual

O exemplo a seguir mostra como desmarcar as seleções atuais em uma página definindo essa página como a atual.

slides/seleção/seleção.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();

Selecionar um elemento de página

O exemplo a seguir mostra como desmarcar qualquer seleção atual em uma página selecionando um elemento da página e removendo todos os outros itens da seleção.

slides/seleção/seleção.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();