Lier des régions dans un document ou une feuille de calcul

Les liaisons permettent à votre complément d’accéder de manière cohérente à des régions spécifiques d’un document ou d’une feuille de calcul. Considérez une liaison comme un signet qui mémorise un emplacement spécifique, même si les utilisateurs modifient leur sélection ou naviguent ailleurs dans le document. Plus précisément, voici ce que les liaisons offrent à votre complément.

• Accédez aux structures de données courantes dans les applications Office prises en charge, telles que les tables, les plages ou le texte.
• Lire et écrire des données sans demander aux utilisateurs d’effectuer d’abord une sélection.
• Créez des relations persistantes entre votre complément et les données de document. Les liaisons sont enregistrées avec le document et fonctionnent entre les sessions.

Pour créer une liaison, appelez l’une de ces méthodes d’objet Bindings pour associer une région de document à un identificateur unique : addFromPromptAsync, addFromSelectionAsync ou addFromNamedItemAsync. Une fois que vous avez établi la liaison, utilisez son identificateur pour lire ou écrire dans cette région à tout moment.

Vous pouvez également vous abonner à des événements de modification de données et de sélection pour des régions liées spécifiques. Cela signifie que votre complément n’est averti que des modifications apportées dans la zone liée, et non de l’intégralité du document.

Choisir le type de liaison approprié

Office prend en charge trois types de liaisons différents. Vous spécifiez le type avec le paramètre bindingType lors de la création d’une liaison à l’aide de addFromSelectionAsync, addFromPromptAsync ou addFromNamedItemAsync.

Liaison de texte

Liaison de texte : lie à une région de document qui peut être représentée sous forme de texte.

Dans Word, la plupart des sélections contiguës fonctionnent. Dans Excel, seules les sélections de cellules uniques peuvent utiliser la liaison de texte. Excel prend uniquement en charge le texte brut, tandis que Word prend en charge trois formats : texte brut, HTML et Open XML pour Office.

Liaison de matrice

Liaison de matrice : lie à une région fixe contenant des données tabulaires sans en-têtes.

Les données d’une liaison de matrice sont lues ou écrites sous la forme d’un tableau à deux dimensions (tableau de tableaux en JavaScript). Par exemple, deux lignes de valeurs de chaîne dans deux colonnes ressembleraient à [['a', 'b'], ['c', 'd']], et une seule colonne de trois lignes serait [['a'], ['b'], ['c']].

Dans Excel, toute sélection contiguë de cellules fonctionne pour la liaison de matrice. Dans Word, seuls les tableaux prennent en charge la liaison de matrice.

Liaison de table

Liaison de table : lie à une région de document contenant un tableau avec des en-têtes.

Les données d’une liaison de table sont lues ou écrites sous la forme d’un objet TableData . L’objet TableData expose les données via les headers propriétés et rows .

Tout tableau Excel ou Word peut être la base d’une liaison de tableau. Une fois que vous avez établi une liaison de table, les nouvelles lignes ou colonnes que les utilisateurs ajoutent à la table sont automatiquement incluses dans la liaison.

Après avoir créé une liaison avec l’une des trois méthodes « addFrom », vous pouvez utiliser les données et les propriétés de la liaison à l’aide de l’objet correspondant : MatrixBinding, TableBinding ou TextBinding. Les trois objets héritent des méthodes getDataAsync et setDataAsync de l’objet Binding pour interagir avec les données liées.

Créer une liaison à partir de la sélection actuelle

L’exemple suivant ajoute une liaison de texte appelée myBinding à la sélection actuelle à l’aide de la méthode addFromSelectionAsync .

Office.context.document.bindings.addFromSelectionAsync(Office.BindingType.Text, { id: 'myBinding' }, function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Action failed. Error: ' + asyncResult.error.message);
    } else {
        write('Added new binding with type: ' + asyncResult.value.type + ' and id: ' + asyncResult.value.id);
    }
});

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

Dans cet exemple, le type de liaison étant text, un TextBinding est créé pour la sélection. Différents types de liaison exposent différentes données et opérations. Office.BindingType est une énumération des types de liaison disponibles.

Le deuxième paramètre facultatif spécifie l’ID de la nouvelle liaison. Si vous ne spécifiez pas d’ID, un id est généré automatiquement.

La fonction anonyme passée comme paramètre de rappel final s’exécute lorsque la création de la liaison est terminée. La fonction reçoit un seul paramètre, asyncResult, qui fournit l’accès à un objet AsyncResult avec la status de l’appel. La AsyncResult.value propriété contient une référence à un objet Binding du type spécifié pour la liaison nouvellement créée. Vous pouvez utiliser cet objet Binding pour obtenir et définir les données.

Créer une liaison à partir d’une invite

La fonction suivante ajoute une liaison de texte appelée myBinding à l’aide de la méthode addFromPromptAsync . Cette méthode permet aux utilisateurs de spécifier la plage de la liaison à l’aide de l’invite de sélection de plage intégrée de l’application.

function bindFromPrompt() {
    Office.context.document.bindings.addFromPromptAsync(Office.BindingType.Text, { id: 'myBinding' }, function (asyncResult) {
        if (asyncResult.status == Office.AsyncResultStatus.Failed) {
            write('Action failed. Error: ' + asyncResult.error.message);
        } else {
            write('Added new binding with type: ' + asyncResult.value.type + ' and id: ' + asyncResult.value.id);
        }
    });
}

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

Dans cet exemple, le type de liaison étant text, un TextBinding est créé pour la sélection de l’utilisateur dans l’invite.

Le deuxième paramètre contient l’ID de la nouvelle liaison. Si vous ne spécifiez pas d’ID, un id est généré automatiquement.

La fonction anonyme passée en tant que troisième paramètre de rappel s’exécute lorsque la création de la liaison est terminée. Lorsque la fonction de rappel s’exécute, l’objet AsyncResult contient la status de l’appel et la liaison nouvellement créée.

La capture d’écran suivante montre l’invite de sélection de plage intégrée dans Excel.

Ajout d’une liaison à un élément nommé

La fonction suivante ajoute une liaison à l’élément nommé existant myRange en tant que liaison « matrice » à l’aide id de la méthode addFromNamedItemAsync et affecte à la liaison « myMatrix ».

function bindNamedItem() {
    Office.context.document.bindings.addFromNamedItemAsync("myRange", "matrix", {id:'myMatrix'}, function (result) {
        if (result.status == 'succeeded'){
            write('Added new binding with type: ' + result.value.type + ' and id: ' + result.value.id);
            }
        else
            write('Error: ' + result.error.message);
    });
}

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

Pour Excel, le itemName paramètre addFromNamedItemAsync fait référence à une plage nommée existante, à une plage spécifiée avec le style de référence A1 ("A1:A3") ou à un tableau. Par défaut, Excel attribue les noms « Table1 » pour le premier tableau, « Table2 » pour le deuxième tableau, etc. Pour attribuer un nom explicite à un tableau dans l’interface utilisateur Excel, utilisez la propriété Nom de la table sur les Outils de tableau | Onglet Création .

La fonction suivante crée une liaison dans Excel vers les trois premières cellules de la colonne A ("A1:A3"), affecte l’ID "MyCities", puis écrit trois noms de ville dans cette liaison.

 function bindingFromA1Range() {
    Office.context.document.bindings.addFromNamedItemAsync("A1:A3", "matrix", { id: "MyCities" },
        function (asyncResult) {
            if (asyncResult.status == "failed") {
                write('Error: ' + asyncResult.error.message);
            } else {
                // Write data to the new binding.
                Office.select("bindings#MyCities").setDataAsync([['Berlin'], ['Munich'], ['Duisburg']], { coercionType: "matrix" },
                    function (asyncResult) {
                        if (asyncResult.status == "failed") {
                            write('Error: ' + asyncResult.error.message);
                        }
                    });
            }
        });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

Par Word, le itemName paramètre de addFromNamedItemAsync fait référence à la Title propriété d’un Rich Text contrôle de contenu. (Vous ne pouvez réaliser de liaison avec des contrôles de contenu différents du contrôle de contenu Rich Text.)

Par défaut, aucun contrôle de contenu n’a Title de valeur affectée. Pour attribuer un nom explicite dans l’interface utilisateur Word, après avoir inséré un contrôle de contenu Texte enrichi à partir du groupe Contrôles sous l’onglet Développeur, utilisez la commande Propriétés dans le groupe Contrôles pour afficher la boîte de dialogue Propriétés du contrôle de contenu. Ensuite, définissez la Title propriété du contrôle de contenu sur le nom que vous souhaitez référencer à partir de votre code.

La fonction suivante crée une liaison de texte dans Word à un contrôle de contenu de texte enrichi nommé "FirstName", affecte l’ID"firstName", puis affiche ces informations.

function bindContentControl() {
    Office.context.document.bindings.addFromNamedItemAsync('FirstName', 
        Office.BindingType.Text, {id:'firstName'},
        function (result) {
            if (result.status === Office.AsyncResultStatus.Succeeded) {
                write('Control bound. Binding.id: '
                    + result.value.id + ' Binding.type: ' + result.value.type);
            } else {
                write('Error:', result.error.message);
            }
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

Obtention de toutes les liaisons

L’exemple suivant obtient toutes les liaisons d’un document à l’aide de la méthode getAllAsync .

Office.context.document.bindings.getAllAsync(function (asyncResult) {
    let bindingString = '';
    for (let i in asyncResult.value) {
        bindingString += asyncResult.value[i].id + '\n';
    }
    write('Existing bindings: ' + bindingString);
});

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

La fonction anonyme passée en tant que callback paramètre s’exécute lorsque l’opération est terminée. La fonction est appelée avec un seul paramètre, asyncResult, qui contient un tableau des liaisons dans le document. Le tableau est répété pour générer une chaîne qui contient les ID des liaisons. La chaîne est ensuite affichée dans une boîte de message.

Obtenir une liaison par ID à l’aide de getByIdAsync

L’exemple suivant utilise la méthode getByIdAsync pour obtenir une liaison dans un document en spécifiant son ID. Cet exemple suppose qu’une liaison nommée 'myBinding' a été ajoutée au document à l’aide de l’une des méthodes décrites plus haut dans cet article.

Office.context.document.bindings.getByIdAsync('myBinding', function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Action failed. Error: ' + asyncResult.error.message);
    }
    else {
        write('Retrieved binding with type: ' + asyncResult.value.type + ' and id: ' + asyncResult.value.id);
    }
});

// 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 id paramètre est l’ID de la liaison à récupérer.

La fonction anonyme passée en tant que deuxième paramètre de rappel s’exécute lorsque l’opération est terminée. La fonction est appelée avec un seul paramètre, asyncResult, qui contient le status de l’appel et la liaison avec l’ID « myBinding ».

Obtenir une liaison par ID à l’aide de Office.select

L’exemple suivant utilise la fonction Office.select pour obtenir une promesse d’objet Binding dans un document en spécifiant son ID dans une chaîne de sélecteur. Il appelle ensuite la méthode getDataAsync pour obtenir des données à partir de la liaison spécifiée. Cet exemple suppose qu’une liaison nommée 'myBinding' a été ajoutée au document à l’aide de l’une des méthodes décrites plus haut dans cet article.

Office.select("bindings#myBinding", function onError(){}).getDataAsync(function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Action failed. Error: ' + asyncResult.error.message);
    } else {
        write(asyncResult.value);
    }
});

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

Si la select promesse de fonction renvoie correctement un objet Binding , cet objet expose uniquement les quatre méthodes suivantes : getDataAsync, setDataAsync, addHandlerAsync et removeHandlerAsync. Si la promesse ne peut pas renvoyer un objet Binding, le onError rappel peut être utilisé pour accéder à un objet asyncResult.error pour obtenir plus d’informations. Si vous devez appeler un membre de l’objet Binding autre que les quatre méthodes exposées par la promesse d’objet Binding retournée par la select fonction, utilisez plutôt la méthode getByIdAsync à l’aide de la propriété Document.bindings et de la méthode getByIdAsync pour récupérer l’objet Binding .

Publication d’une liaison par ID

L’exemple suivant utilise la méthode releaseByIdAsync pour libérer une liaison dans un document en spécifiant son ID.

Office.context.document.bindings.releaseByIdAsync('myBinding', function (asyncResult) {
    write('Released myBinding!');
});

// 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 id paramètre est l’ID de la liaison à libérer.

La fonction anonyme passée en tant que deuxième paramètre est un rappel qui s’exécute lorsque l’opération est terminée. La fonction est appelée avec un seul paramètre, asyncResult, qui contient les status de l’appel.

Lecture de données à partir d’une liaison

L’exemple suivant utilise la méthode getDataAsync pour obtenir des données à partir d’une liaison existante.

myBinding.getDataAsync(function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Action failed. Error: ' + asyncResult.error.message);
    } else {
        write(asyncResult.value);
    }
});

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

myBinding est une variable qui contient une liaison de texte existante dans le document. Vous pouvez également utiliser Office.select pour accéder à la liaison par son ID et démarrer votre appel à la méthode getDataAsync , comme suit :

Office.select("bindings#myBindingID").getDataAsync

La fonction anonyme passée à la méthode est un rappel qui s’exécute une fois l’opération terminée. La propriété AsyncResult.value contient les données dans myBinding. Le type de valeur dépend du type de liaison. La liaison dans cet exemple étant une liaison de texte, la valeur contient une chaîne. Pour obtenir des exemples supplémentaires concernant l’utilisation des liaisons de matrice et de tableau, consultez la rubrique sur la méthode getDataAsync.

Écriture de données dans une liaison

L’exemple suivant utilise la méthode setDataAsync pour définir des données dans une liaison existante.

myBinding.setDataAsync('Hello World!', function (asyncResult) { });

myBinding est une variable qui contient une liaison de texte existante dans le document.

Dans cet exemple, le premier paramètre est la valeur à définir sur myBinding. Comme il s’agit d’une liaison de texte, la valeur est de type string. Différents types de liaisons acceptent divers types de données.

La fonction anonyme passée à la méthode est un rappel qui s’exécute une fois l’opération terminée. La fonction est appelée avec un seul paramètre, asyncResult, qui contient les status du résultat.

Détecter les modifications apportées aux données ou la sélection dans une liaison

La fonction suivante attache un gestionnaire d’événements à l’événement DataChanged d’une liaison avec l’ID « MyBinding ».

function addHandler() {
Office.select("bindings#MyBinding").addHandlerAsync(
    Office.EventType.BindingDataChanged, dataChanged);
}
function dataChanged(eventArgs) {
    write('Bound data changed in binding: ' + eventArgs.binding.id);
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

myBinding est une variable qui contient une liaison de texte existante dans le document.

Le premier paramètre eventType de addHandlerAsync spécifie le nom de l’événement auquel s’abonner. Office.EventType est une énumération des valeurs de types d’événement disponibles. Office.EventType.BindingDataChanged prend la valeur de la chaîne « bindingDataChanged ».

La dataChanged fonction passée en tant que deuxième paramètre de gestionnaire est un gestionnaire d’événements qui s’exécute lorsque les données de la liaison sont modifiées. La fonction est appelée avec un seul paramètre, eventArgs, qui contient une référence à la liaison. Cette liaison peut être utilisée pour récupérer les données mises à jour.

De même, vous pouvez détecter lorsqu’un utilisateur modifie la sélection dans une liaison en ajoutant un gestionnaire d’événements à l’événement SelectionChanged d’une liaison. Pour ce faire, spécifiez le eventType paramètre de addHandlerAsync en tant que Office.EventType.BindingSelectionChanged ou "bindingSelectionChanged".

Vous pouvez ajouter plusieurs gestionnaires d’événements pour un événement donné en appelant à nouveau addHandlerAsync et en transmettant une fonction de gestionnaire d’événements supplémentaire pour le handler paramètre . Le nom de chaque fonction de gestionnaire d’événements doit être unique.

Suppression d’un gestionnaire d’événements

Pour supprimer un gestionnaire d’événements pour un événement, appelez removeHandlerAsync en passant le type d’événement comme premier paramètre eventType et le nom de la fonction de gestionnaire d’événements à supprimer en tant que deuxième paramètre de gestionnaire . Par exemple, la fonction suivante supprime la dataChanged fonction de gestionnaire d’événements ajoutée dans l’exemple de la section précédente.

function removeEventHandlerFromBinding() {
    Office.select("bindings#MyBinding").removeHandlerAsync(
        Office.EventType.BindingDataChanged, {handler:dataChanged});
}

Voir aussi

• Compréhension de l’API JavaScript pour Office
• Programmation asynchrone dans des compléments Office
• Lecture et écriture de données dans la sélection active d’un document ou d’une feuille de calcul