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

Utilisez une liaison lorsque votre complément a besoin d’un accès fiable à une zone spécifique d’un classeur Excel ou d’un document Word. Une liaison associe la région à un ID unique, de sorte que votre complément peut y revenir une fois que l’utilisateur a modifié sa sélection ou rouvert le document.

Avec une liaison, votre complément peut :

• Accéder aux structures de données courantes, telles que des tableaux, des plages ou du texte.
• Lisez et écrivez des données sans que l’utilisateur ait besoin de sélectionner la région au préalable.
• Surveillez les modifications de données et de sélection dans la région délimitée.
• Maintenez la relation entre les sessions car la liaison est enregistrée avec le document.

Choisir le bon type de reliure

Office prend en charge trois types de liaison. Choisissez un type en fonction de la région et des données que votre complément doit lire ou écrire.

Spécifiez le type avec le bindingType paramètre lorsque vous créez une liaison à l’aide de addFromSelectionAsync, addFromPromptAsync ou addFromNamedItemAsync.

Liaison de texte

Une liaison de texte représente une zone de document en tant que texte.

Dans Word, la plupart des sélections contiguës fonctionnent. Dans Excel, seules les cellules sélectionnées 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.

Matrix binding

Une liaison de matrice représente une région fixe de données tabulaires sans en-têtes.

Lire ou écrire des données matricielles en deux dimensions Array (un tableau de tableaux en JavaScript). Par exemple, deux lignes de string valeurs dans deux colonnes ressemblent à [['a', 'b'], ['c', 'd']], et une seule colonne de trois lignes ressemble à [['a'], ['b'], ['c']].

Dans Excel, toute sélection contiguë de cellules sert à relier une matrice. Dans Word, seuls les tableaux prennent en charge la liaison de matrice.

Table binding

Une reliure de tableau représente un tableau avec des en-têtes.

Les données d’une liaison de table sont lues ou écrites en tant qu’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 tableau, les nouvelles lignes ou colonnes que les utilisateurs ajoutent au tableau 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 pour interagir avec les Binding 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 est du texte, donc 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, l’un d’eux est généré automatiquement.

La fonction anonyme passée en tant que paramètre de rappel final s’exécute lorsque la création de la liaison est terminée. La fonction reçoit un paramètre unique, asyncResult, qui donne accès à un objet AsyncResult avec le 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 est du texte, donc 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, l’un d’eux 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 le 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 de la méthode addFromNamedItemAsync et affecte la id liaison en tant que « 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 de 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 affecte les noms « Tableau1 » au premier tableau, « Tableau2 » au deuxième tableau, etc. Pour attribuer un nom significatif à un tableau dans l’interface utilisateur Excel, utilisez la propriété Nom du tableau dans l’onglet Outils de tableau | Onglet Création .

La fonction suivante crée une liaison dans Excel aux trois premières cellules de la colonne A ("A1:A3"), attribue l’ID "MyCities", puis écrit trois noms de ville à 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;
}

Pour 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, un contrôle de contenu n’a aucune Title valeur affectée. Pour attribuer un nom significatif dans l’interface utilisateur de Word, après avoir inséré un contrôle de contenu de texte enrichi à partir du groupe Contrôles de l’onglet Développeur, utilisez la commande Propriétés du groupe Contrôles pour afficher la boîte de dialogue Propriétés du contrôle de contenu. Définissez ensuite la Title propriété du contrôle de contenu sur le nom que vous souhaitez référencer à partir de votre code.

Dans Word, la fonction suivante crée une liaison de texte vers un contrôle de contenu de texte enrichi nommé "FirstName", attribue l’ID"firstName" et affiche ensuite 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 paramètre s’exécute callback une fois l’opération terminée. La fonction est appelée avec un seul paramètre, asyncResult, qui contient un tableau des liaisons du 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 une fois l’opération 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 les données 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 promesse de select fonction retourne un objet Binding , cet objet expose uniquement les quatre méthodes suivantes : getDataAsync, setDataAsync, addHandlerAsync et removeHandlerAsync. Si la promesse ne peut pas retourner un objet Binding, le onError rappel peut être utilisé pour accéder à un objet asyncResult.error afin d’obtenir plus d’informations. Si vous avez besoin d’appeler un membre de l’objet Binding autre que les quatre méthodes exposées par la promesse de l’objet Binding renvoyé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 une fois l’opération terminée. La fonction est appelée avec un seul paramètre, asyncResult, qui contient le 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 ceci :

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

La fonction anonyme transmise à 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 est une liaison de texte, la valeur contient donc 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 transmise à 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 le 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 un 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 comme 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 introduisant le type d’événement en tant que 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 fonction de gestionnaire d’événements dataChanged 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