Sélectionner des éléments d'une présentation

La sélection correspond à ce qui est actuellement sélectionné dans une page de présentation ouverte, comme un segment de texte en surbrillance ou un tableau. Ce guide vous explique comment obtenir et définir la sélection dans une présentation active à l'aide d'Apps Script.

La sélection est un instantané de ce qu'elle était au moment du démarrage du script. Si l'utilisateur clique et que la sélection change pendant l'exécution du script, ces modifications ne seront pas répercutées.

Sélections et type de sélection

Vous pouvez lire la sélection à l'aide de la classe Selection. La classe comporte différentes méthodes pour obtenir les objets sélectionnés en fonction du type d'objet sélectionné.

L'énumération SelectionType représente le type spécifique d'objets sélectionnés. Par exemple, si l'utilisateur a sélectionné du texte dans une forme, le type de sélection sera TEXT. Dans ce cas, vous pouvez récupérer la plage de texte sélectionnée à l'aide de la méthode selection.getTextRange().

Vous pouvez également récupérer l'objet contenant la sélection. Pour poursuivre avec l'exemple ci-dessus, vous pouvez récupérer la forme contenant le texte sélectionné à l'aide de selection.getPageElementRange().getPageElements()[0]. De même, la page qui contient la forme englobante est la page active actuelle. Pour la récupérer, utilisez selection.getCurrentPage().

Lire la sélection

Pour lire la sélection, utilisez la méthode Overview.getSelection() comme indiqué dans l'exemple suivant:

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

Lire la page active

Pour récupérer la page actuelle que l'utilisateur consulte, utilisez les méthodes getSelection() et getCurrentPage() comme suit:

diapositives/selection/selection.gs
const currentPage = SlidesApp.getActivePresentation().getSelection().getCurrentPage();

Notez que le type de page actuelle peut être l'un des suivants:

Un ou plusieurs objets peuvent être sélectionnés sur la page actuelle, et le SelectionType détermine le type de sélection.

Lire la sélection en fonction du type de sélection

L'exemple suivant montre comment utiliser le type de sélection pour lire la sélection actuelle de manière appropriée.

diapositives/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;
}

Lire des sélections de texte

Vous pouvez lire la sélection de texte à l'aide de la méthode Selection.getTextRange(). Il existe deux types de sélection de texte:

  • Sélection de plage: si une forme contient le texte "Hello" et que "He" est sélectionné, la plage renvoyée contient startIndex=0 et endIndex=2.
  • Sélection du curseur: si une forme contient le texte "Hello" et que le curseur se trouve après "H" ("H|ello"), la plage renvoyée est une plage vide avec startIndex=1 et endIndex=1.

Modifier la sélection

Le script peut modifier la sélection de l'utilisateur. Toute modification de sélection apportée par le script à la présentation est répercutée dans les opérations de sélection ultérieures pendant la durée d'exécution du script.

Les modifications de la sélection ne sont répercutées dans le navigateur de l'utilisateur qu'une fois l'exécution du script terminée ou lorsque Presentation.saveAndClose() est appelé.

Sélectionner la page actuelle

Vous pouvez sélectionner une page de la présentation active en tant que page actuelle en appelant la méthode selectAsCurrentPage(). Cette méthode supprime toute sélection d'éléments de page, de page ou de texte précédents. Ainsi, cette méthode sur la page actuelle vous permet de désélectionner toutes les sélections actuelles sur la page. Exemple :

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

Sélectionner un élément de page

Pour sélectionner un élément de page, utilisez la méthode PageElement.select(). Les éléments de page déjà sélectionnés sont alors désélectionnés.

Exemple :

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

Sélectionner plusieurs éléments de page

Pour ajouter des éléments de page supplémentaires à la sélection, utilisez la méthode PageElement.select(false). Tous les éléments de la page doivent figurer sur la page active.

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

Transformer la sélection

Les modifications apportées par votre script peuvent transformer la sélection actuelle, de sorte que les éléments sélectionnés changent à la suite de ces modifications. Exemple :

  1. Supposons que vous ayez sélectionné deux formes A et B.
  2. Votre script supprime ensuite la forme A.
  3. En conséquence, la sélection est transformée par rapport à la modification afin que seule la forme B soit sélectionnée.

L'exemple suivant montre comment transformer la sélection en manipulant les éléments de page sélectionnés.

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

Sélectionner du texte

Le texte contenu dans une forme ou dans une cellule de tableau peut être sélectionné à l'aide de la méthode TextRange.select(). Si le texte est contenu dans une forme, cette dernière est également sélectionnée. Si le texte est contenu dans une cellule de tableau, cette cellule et son tableau englobant sont tous deux sélectionnés.

Cette opération définit également la page parente comme page actuelle.

Sélection d'une plage dans une forme

L'exemple suivant montre comment sélectionner une plage dans un texte contenu dans une forme.

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

Sélection du curseur dans une forme

L'exemple suivant montre comment effectuer une sélection de curseur dans un texte contenu dans une forme.

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

Sélection d'une plage dans une cellule de tableau

L'exemple suivant montre comment sélectionner une plage dans un texte contenu dans une cellule de table.

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

Sélection du curseur dans TableCell

L'exemple suivant montre comment effectuer une sélection de curseur dans un texte contenu dans une cellule de tableau.

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

Transformation de la sélection avec modifications de texte

L'exemple suivant montre comment transformer la sélection en modifiant le texte sélectionné.

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

Désélection...

Il n'existe aucune méthode explicite pour désélectionner du texte ou des éléments de page. Toutefois, ce résultat peut être obtenu à l'aide des méthodes Page.selectAsCurrentPage() ou pageElement.select().

Sélectionner une page active

L'exemple suivant montre comment désélectionner toutes les sélections actuelles sur une page en définissant cette page comme page actuelle.

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

Sélectionner un élément de page

L'exemple suivant montre comment désélectionner toutes les sélections actuelles sur une page en sélectionnant un élément de la page, ce qui supprimera tous les autres éléments de la sélection.

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