Lire et écrire des données dans la sélection active d’un document ou d’une feuille de calcul

L’objet Document expose des méthodes qui vous permettent de lire et d’écrire dans la sélection active de l’utilisateur dans un document ou une feuille de calcul. Pour ce faire, l’objet Document fournit les getSelectedDataAsync méthodes et setSelectedDataAsync . Cette rubrique explique comment lire, écrire et créer des gestionnaires d’événements pour détecter les changements intervenant dans la sélection de l’utilisateur.

La getSelectedDataAsync méthode fonctionne uniquement par rapport à la sélection actuelle de l’utilisateur. Si vous devez conserver la sélection dans le document, afin que la même sélection soit disponible en lecture et en écriture dans les sessions exécutant votre complément, vous devez ajouter une liaison à l’aide de la méthode Bindings.addFromSelectionAsync (ou créer une liaison à l’aide de l’une des autres méthodes « addFrom » de l’objet Bindings). Pour plus d’informations sur la création d’une liaison vers une zone d’un document et sur la lecture et l’écriture dans une liaison, voir Liaisons de régions dans un document ou une feuille de calcul.

Lecture de données sélectionnées

L’exemple suivant montre comment obtenir les données d’une sélection dans un document en utilisant la méthode getSelectedDataAsync.

Office.context.document.getSelectedDataAsync(Office.CoercionType.Text, function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Action failed. Error: ' + asyncResult.error.message);
    }
    else {
        write('Selected data: ' + asyncResult.value);
    }
});

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

Dans cet exemple, le premier paramètre, coercionType, est spécifié comme Office.CoercionType.Text (vous pouvez également spécifier ce paramètre à l’aide de la chaîne "text"littérale ). Cela signifie que la propriété value de l’objet AsyncResult qui est disponible à partir du paramètre asyncResult dans la fonction de rappel renverra une string qui contient le texte sélectionné dans le document. La spécification de différents types de forçage de type produit des valeurs différentes. Office.CoercionType est une énumération des valeurs de types de forçage de type disponibles. Office.CoercionType.Text prend la valeur de la chaîne « text ».

Conseil

Quand devez-vous utiliser la matrice ou le paramètre coercionType de tableau pour accéder aux données ? Si vous avez besoin que vos données tabulaires sélectionnées augmentent dynamiquement lorsque des lignes et des colonnes sont ajoutées, et que vous devez travailler avec des en-têtes de table, vous devez utiliser le type de données table (en spécifiant le paramètre coercionType de la getSelectedDataAsync méthode comme "table" ou Office.CoercionType.Table). L’ajout de lignes et de colonnes au sein de la structure de données est pris en charge dans les données de tableau et de matrice, mais l’ajout de lignes et de colonnes à la fin est pris en charge uniquement pour les données de tableau. Si vous n’envisagez pas d’ajouter des lignes et des colonnes et que vos données ne nécessitent pas de fonctionnalité d’en-tête, vous devez utiliser le type de données matrice (en spécifiant le paramètre coercionType de getSelectedDataAsync la méthode ou "matrix"Office.CoercionType.Matrix), qui fournit un modèle plus simple d’interaction avec les données.

La fonction anonyme qui est passée à la méthode en tant que deuxième paramètre, le rappel, est exécutée lorsque l’opération getSelectedDataAsync est terminée. La fonction est appelée avec un seul paramètre, asyncResult, qui contient le résultat et l’état de l’appel. Si l’appel échoue, la propriété error de l’objet AsyncResult fournit l’accès à l’objet Error . Vous pouvez vérifier la valeur des propriétés Error.name et Error.message pour déterminer les raisons de l’échec de l’opération. Sinon, le texte sélectionné dans le document s’affiche.

La propriété AsyncResult.status est utilisée dans l’instruction if pour tester la réussite de l’appel. Office.AsyncResultStatus est une énumération des valeurs de propriété disponibles AsyncResult.status . Office.AsyncResultStatus.Failed prend la valeur de la chaîne « failed » (et, là encore, peut également être spécifié comme chaîne littérale).

Écriture de données dans la sélection

L’exemple suivant montre comment définir la sélection pour afficher « Hello World! ».

Office.context.document.setSelectedDataAsync("Hello World!", function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write(asyncResult.error.message);
    }
});

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

Le passage de différents types d’objets pour le paramètre de données aura des résultats différents. Le résultat dépend de ce qui est actuellement sélectionné dans le document, de l’application cliente Office qui héberge votre complément et de la possibilité de contraindre les données transmises à la sélection actuelle.

La fonction anonyme transmise dans la méthode setSelectedDataAsync comme paramètre callback est exécutée quand l’appel anonyme est terminé. Lorsque vous écrivez des données dans la sélection à l’aide de la setSelectedDataAsync méthode , le paramètre asyncResult du rappel donne accès uniquement aux status de l’appel et à l’objet Error en cas d’échec de l’appel.

Détection de modifications dans la sélection

L’exemple suivant montre comment détecter des modifications dans la sélection à l’aide de la méthode Document.addHandlerAsync permettant d’ajouter un gestionnaire d’événements pour l’événement SelectionChanged sur le document.

Office.context.document.addHandlerAsync("documentSelectionChanged", myHandler, function(result){}
);

// Event handler function.
function myHandler(eventArgs){
    write('Document Selection Changed');
}

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

Le premier paramètre, eventType, spécifie le nom de l’événement auquel s’abonner. Le passage de la chaîne "documentSelectionChanged" pour ce paramètre revient à transmettre le Office.EventType.DocumentSelectionChanged type d’événement de l’énumération Office.EventType .

La myHandler() fonction qui est passée à la méthode en tant que deuxième paramètre, gestionnaire, est un gestionnaire d’événements qui est exécuté lorsque la sélection est modifiée sur le document. La fonction est appelée avec un seul paramètre, eventArgs, qui contient une référence à un objet DocumentSelectionChangedEventArgs quand l’opération asynchrone se termine. Vous pouvez utiliser la propriété DocumentSelectionChangedEventArgs.document pour accéder au document qui a déclenché l’événement.

Remarque

Vous pouvez ajouter plusieurs gestionnaires d’événements pour un événement donné en appelant à nouveau la addHandlerAsync méthode et en transmettant une fonction de gestionnaire d’événements supplémentaire pour le paramètre handler . Cela fonctionnera correctement à condition que le nom de chaque fonction de gestionnaire d’événements soit unique.

Arrêt de la détection de modifications dans la sélection

L’exemple suivant montre comment arrêter l’écoute de l’événement Document.SelectionChanged en appelant la méthode document.removeHandlerAsync.

Office.context.document.removeHandlerAsync("documentSelectionChanged", {handler:myHandler}, function(result){});

Le myHandler nom de la fonction qui est passé en tant que deuxième paramètre, gestionnaire, spécifie le gestionnaire d’événements qui sera supprimé de l’événement SelectionChanged .

Importante

Si le paramètre facultatif handler est omis lorsque la removeHandlerAsync méthode est appelée, tous les gestionnaires d’événements de l’eventType spécifié sont supprimés.