Utiliser des listes

L'API Google Docs permet de créer des listes dans de nouveaux documents, de convertir des paragraphes en texte brut existants en listes à puces et de supprimer les puces des paragraphes.

Créer une liste numérotée dans un nouveau document

L'API Docs permet de créer une liste numérotée dans un nouveau document en insérant du texte, puis en appliquant un style de liste au texte dans une seule requête par lot.

Pour créer une liste numérotée dans un nouveau document :

  1. Utilisez la méthode documents.create pour créer un document.

  2. Utilisez la méthode documents.batchUpdate et fournissez un InsertTextRequest pour ajouter du contenu au document. Utilisez des caractères de retour à la ligne (\n) pour séparer les éléments de la liste.

  3. Dans la même mise à jour par lot, incluez un CreateParagraphBulletsRequest, un Range pour spécifier la plage de texte et un BulletGlyphPreset pour définir le modèle de numérotation.

L'exemple de code suivant montre comment créer un document, puis insérer trois éléments sous forme de liste numérotée. BulletGlyphPreset utilise NUMBERED_DECIMAL_ALPHA_ROMAN pour mettre en forme la liste. Cela signifie que les trois premiers niveaux d'imbrication de la liste numérotée sont représentés par un nombre décimal, une lettre minuscule et un chiffre romain minuscule.

Java

Document doc = new Document().setTitle("New List Document");
doc = docsService.documents().create(doc).execute();
String documentId = doc.getDocumentId();

List<Request> requests = new ArrayList<>();
requests.add(new Request().setInsertText(new InsertTextRequest()
        .setText("Item 1\nItem 2\nItem 3\n")
        .setLocation(new Location().setIndex(1).setTabId(TAB_ID))));

requests.add(new Request().setCreateParagraphBullets(
        new CreateParagraphBulletsRequest()
                .setRange(new Range()
                        .setStartIndex(1)
                        .setEndIndex(22)
                        .setTabId(TAB_ID))
                .setBulletPreset("NUMBERED_DECIMAL_ALPHA_ROMAN")));

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests);
docsService.documents().batchUpdate(documentId, body).execute();

System.out.println("Created document with ID: " + documentId);

Python

title = 'New List Document'
body = {'title': title}
doc = service.documents().create(body=body).execute()
document_id = doc.get('documentId')

requests = [
    {
        'insertText': {
            'location': {
                'index': 1,
                'tabId': TAB_ID
            },
            'text': 'Item 1\nItem 2\nItem 3\n'
        }
    },
    {
        'createParagraphBullets': {
            'range': {
                'startIndex': 1,
                'endIndex': 22,
                'tabId': TAB_ID
            },
            'bulletPreset': 'NUMBERED_DECIMAL_ALPHA_ROMAN'
        }
    }
]

result = service.documents().batchUpdate(
    documentId=document_id, body={'requests': requests}).execute()

print(f"Created document with ID: {document_id}")

Remplacez TAB_ID par l'ID de l'onglet contenant le contenu de la liste.

Convertir un paragraphe en liste

Une opération courante de mise en forme des paragraphes consiste à convertir des paragraphes existants en liste à puces.

Pour créer une liste, utilisez la méthode documents.batchUpdate et fournissez un CreateParagraphBulletsRequest. Incluez un Range pour spécifier le texte concerné et un BulletGlyphPreset pour définir le motif de la puce.

Tous les paragraphes qui chevauchent la plage donnée sont listés. Si la plage spécifiée chevauche un tableau, les puces sont appliquées dans les cellules du tableau. Le niveau d'imbrication de chaque paragraphe est déterminé en comptant les tabulations en début de paragraphe.

Vous ne pouvez pas ajuster le niveau d'imbrication d'une puce existante. Pour ce faire, vous devez supprimer la puce, définir les tabulations en début de paragraphe, puis recréer la puce. Pour en savoir plus, consultez Supprimer les puces d'une liste.

Vous pouvez également utiliser CreateParagraphBulletsRequest pour modifier le style des puces d'une liste existante.

L'exemple de code suivant montre une requête par lot qui insère d'abord du texte au début du document, puis crée une liste à partir des paragraphes couvrant les 50 premiers caractères. BulletGlyphPreset utilise BULLET_ARROW_DIAMOND_DISC, ce qui signifie que les trois premiers niveaux d'imbrication de la liste à puces sont représentés par une flèche, un losange et un disque.

Java

List<Request> requests = new ArrayList<>();
requests.add(new Request().setInsertText(new InsertTextRequest()
        .setText("Item One\n")
        .setLocation(new Location().setIndex(1).setTabId(TAB_ID))));

requests.add(new Request().setCreateParagraphBullets(
        new CreateParagraphBulletsRequest()
                .setRange(new Range()
                        .setStartIndex(1)
                        .setEndIndex(50)
                        .setTabId(TAB_ID))
                .setBulletPreset("BULLET_ARROW_DIAMOND_DISC")));

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response = docsService.documents()
        .batchUpdate(DOCUMENT_ID, body).execute();

Python

requests = [
        {
        'insertText': {
            'location': {
                'index': 1,
                'tabId': TAB_ID
            },
            'text': 'Item One\n',
        }}, {
        'createParagraphBullets': {
            'range': {
                'startIndex': 1,
                'endIndex':  50,
                'tabId': TAB_ID
            },
            'bulletPreset': 'BULLET_ARROW_DIAMOND_DISC',
        }
    }
]

result = service.documents().batchUpdate(
    documentId=DOCUMENT_ID, body={'requests': requests}).execute()

Remplacez TAB_ID par l'ID de l'onglet contenant le contenu de la liste, ou omettez-le pour utiliser par défaut le premier onglet du document.

Convertis un paragraphe en liste.
Figure 1. Convertis un paragraphe en liste.

Supprimer des puces d'une liste

Pour supprimer les puces d'une liste de paragraphes, utilisez la méthode documents.batchUpdate et fournissez un DeleteParagraphBulletsRequest. Incluez un Range pour spécifier le texte concerné.

La méthode supprime toutes les puces qui chevauchent la plage donnée, quel que soit le niveau d'imbrication. Pour préserver visuellement le niveau d'imbrication, une indentation est ajoutée au début de chaque paragraphe correspondant.

L'exemple de code suivant montre une requête par lot qui supprime les puces d'une liste de paragraphes.

Java

List<Request> requests = new ArrayList<>();
requests.add(new Request().setDeleteParagraphBullets(
        new DeleteParagraphBulletsRequest()
                .setRange(new Range()
                        .setStartIndex(1)
                        .setEndIndex(50)
                        .setTabId(TAB_ID))));

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response = docsService.documents()
        .batchUpdate(DOCUMENT_ID, body).execute();

Python

requests = [
        {
        'deleteParagraphBullets': {
            'range': {
                'startIndex': 1,
                'endIndex':  50,
                'tabId': TAB_ID
            },
        }
    }
]

result = service.documents().batchUpdate(
    documentId=DOCUMENT_ID, body={'requests': requests}).execute()

Remplacez TAB_ID par l'ID de l'onglet contenant le contenu de la liste, ou omettez-le pour utiliser par défaut le premier onglet du document.