Office.Bindings interface

Obtient un objet Office.Document qui représente le document associé à cet ensemble de liaisons.

document: Document;

Valeur de propriété

Office.Document

Crée une liaison avec un objet nommé dans le document.

addFromNamedItemAsync(itemName: string, bindingType: BindingType, options?: AddBindingFromNamedItemOptions, callback?: (result: AsyncResult<Binding>) => void): void;

Paramètres

itemName: string

Nom de l’objet pouvant être lié dans le document. Par exemple, le tableau « MyExpenses » dans Excel. »

bindingType: Office.BindingType

Office.BindingType pour les données. La méthode retourne null si l’objet sélectionné ne peut pas être inséré dans le type spécifié.

options: Office.AddBindingFromNamedItemOptions

Fournit des options pour configurer la liaison créée.

callback: (result: Office.AsyncResult<Office.Binding>) => void

Facultatif. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult. La value propriété du résultat est l’objet Binding qui représente l’élément nommé spécifié.

Retours

void

Remarques

Ensembles de conditions requises :

Pour Excel, le paramètre itemName peut faire référence à une plage nommée ou à un tableau.

Par défaut, l’ajout d’un tableau dans Excel entraîne l’affectation du nom « Tableau1 » pour le premier tableau que vous ajoutez, « Tableau2 » pour le deuxième tableau que vous ajoutez, et ainsi de suite. Pour affecter un nom significatif à un tableau dans l’interface utilisateur d’Excel, servez-vous de la propriété Table Name sous l’onglet Outils de tableau | Conception du ruban.

Remarque : Dans Excel, lorsque vous spécifiez un tableau en tant qu’élément nommé, vous devez qualifier entièrement le nom pour inclure le nom de la feuille de calcul dans le nom du tableau au format suivant : « Feuille1 ! Table1 »

Pour Word, le paramètre itemName fait référence à la propriété Title d’un contrôle de contenu texte enrichi. (Vous ne pouvez pas lier à des contrôles de contenu autres que le contrôle de contenu texte enrichi).

Par défaut, aucun titre n’est affecté à un contrôle de contenu. Pour affecter un nom significatif dans l’interface utilisateur de Word, après l’insertion d’un contrôle de contenu Texte enrichi à partir du groupe Contrôles sur l’onglet Développeur du ruban, 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 propriété Titre du contrôle de contenu sur le nom auquel vous souhaitez faire référence à partir de votre code.

Remarque : Dans Word, s’il existe plusieurs contrôles de contenu texte enrichi avec la même valeur de propriété Title (nom) et que vous essayez de lier à l’un de ces contrôles de contenu avec cette méthode (en spécifiant son nom comme paramètre itemName), l’opération échoue.

Exemples

// The following example adds a binding to the myRange named item in Excel as a "matrix" binding,
// and assigns the binding's id as 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; 
}

// The following example adds a binding to the Table1 named item in Excel as a "table" binding,
// and assigns the binding's id as myTable.
function bindNamedItem() {
    Office.context.document.bindings.addFromNamedItemAsync(
        "Table1", "table", {id:'myTable'}, 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; 
}

// The following example creates a text binding in Word to a rich text content control named "FirstName",
// assigns the id "firstName", and then displays that information.
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; 
}

Crée une liaison avec un objet nommé dans le document.

addFromNamedItemAsync(itemName: string, bindingType: BindingType, callback?: (result: AsyncResult<Binding>) => void): void;

Paramètres

itemName: string

Nom de l’objet pouvant être lié dans le document. Par exemple, le tableau « MyExpenses » dans Excel. »

bindingType: Office.BindingType

Office.BindingType pour les données. La méthode retourne null si l’objet sélectionné ne peut pas être inséré dans le type spécifié.

callback: (result: Office.AsyncResult<Office.Binding>) => void

Facultatif. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult. La value propriété du résultat est l’objet Binding qui représente l’élément nommé spécifié.

Retours

void

Remarques

MatrixBindings, TableBindings, TextBindings

Pour Excel, le paramètre itemName peut faire référence à une plage nommée ou à un tableau.

Par défaut, l’ajout d’un tableau dans Excel entraîne l’affectation du nom « Tableau1 » pour le premier tableau que vous ajoutez, « Tableau2 » pour le deuxième tableau que vous ajoutez, et ainsi de suite. Pour affecter un nom significatif à un tableau dans l’interface utilisateur d’Excel, servez-vous de la propriété Table Name sous l’onglet Outils de tableau | Conception du ruban.

Remarque : Dans Excel, lorsque vous spécifiez un tableau en tant qu’élément nommé, vous devez qualifier entièrement le nom pour inclure le nom de la feuille de calcul dans le nom du tableau au format suivant : « Feuille1 ! Table1 »

Pour Word, le paramètre itemName fait référence à la propriété Title d’un contrôle de contenu texte enrichi. (Vous ne pouvez pas lier à des contrôles de contenu autres que le contrôle de contenu texte enrichi).

Par défaut, aucun titre n’est affecté à un contrôle de contenu. Pour affecter un nom significatif dans l’interface utilisateur de Word, après l’insertion d’un contrôle de contenu Texte enrichi à partir du groupe Contrôles sur l’onglet Développeur du ruban, 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 propriété Titre du contrôle de contenu sur le nom auquel vous souhaitez faire référence à partir de votre code.

Remarque : Dans Word, s’il existe plusieurs contrôles de contenu texte enrichi avec la même valeur de propriété Title (nom) et que vous essayez de lier à l’un de ces contrôles de contenu avec cette méthode (en spécifiant son nom comme paramètre itemName), l’opération échoue.

Créez une liaison en invitant l’utilisateur à effectuer une sélection sur le document.

addFromPromptAsync(bindingType: BindingType, options?: AddBindingFromPromptOptions, callback?: (result: AsyncResult<Binding>) => void): void;

Paramètres

bindingType: Office.BindingType

Spécifie le type de l’objet de liaison à créer. Obligatoire. Retourne null si l’objet sélectionné ne peut pas être renvoyé sous la force dans le type spécifié.

options: Office.AddBindingFromPromptOptions

Fournit des options pour configurer l’invite et identifier la liaison créée.

callback: (result: Office.AsyncResult<Office.Binding>) => void

Facultatif. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult. La value propriété du résultat est l’objet Binding qui représente la sélection spécifiée par l’utilisateur.

Retours

void

Remarques

Ensemble de conditions requises : pas dans un ensemble

Ajoute un objet de liaison du type spécifié à la collection Bindings, qui sera identifié avec l’ID fourni. La méthode échoue si la sélection spécifiée est introuvable.

Exemples

function addBindingFromPrompt() {
    Office.context.document.bindings.addFromPromptAsync(
        Office.BindingType.Text, 
        { id: 'MyBinding', promptText: 'Select text to bind to.' },
        function (asyncResult) {
            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; 
}

Créez une liaison en invitant l’utilisateur à effectuer une sélection sur le document.

addFromPromptAsync(bindingType: BindingType, callback?: (result: AsyncResult<Binding>) => void): void;

Paramètres

bindingType: Office.BindingType

Spécifie le type de l’objet de liaison à créer. Obligatoire. Retourne null si l’objet sélectionné ne peut pas être renvoyé sous la force dans le type spécifié.

callback: (result: Office.AsyncResult<Office.Binding>) => void

Facultatif. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult. La value propriété du résultat est l’objet Binding qui représente la sélection spécifiée par l’utilisateur.

Retours

void

Remarques

Ensemble de conditions requises : pas dans un ensemble

Ajoute un objet de liaison du type spécifié à la collection Bindings, qui sera identifié avec l’ID fourni. La méthode échoue si la sélection spécifiée est introuvable.

Créez une liaison basée sur la sélection actuelle de l’utilisateur.

addFromSelectionAsync(bindingType: BindingType, options?: AddBindingFromSelectionOptions, callback?: (result: AsyncResult<Binding>) => void): void;

Paramètres

bindingType: Office.BindingType

Spécifie le type de l’objet de liaison à créer. Obligatoire. Retourne null si l’objet sélectionné ne peut pas être renvoyé sous la force dans le type spécifié.

options: Office.AddBindingFromSelectionOptions

Fournit des options pour identifier la liaison créée.

callback: (result: Office.AsyncResult<Office.Binding>) => void

Facultatif. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult. La value propriété du résultat est l’objet Binding qui représente la sélection spécifiée par l’utilisateur.

Retours

void

Remarques

Ensembles de conditions requises :

Ajoute le type spécifié d’objet de liaison à la collection Bindings, qui sera identifiée avec l’ID fourni.

Remarque Dans Excel, si vous appelez la méthode addFromSelectionAsync en passant le Binding.id d’une liaison existante, le binding.type de cette liaison est utilisé et son type ne peut pas être modifié en spécifiant une valeur différente pour le paramètre bindingType. Si vous devez utiliser un ID existant et modifier le bindingType, appelez d’abord la méthode Bindings.releaseByIdAsync pour libérer la liaison, puis appelez la méthode addFromSelectionAsync pour rétablir la liaison avec un nouveau type.

Exemples

function addBindingFromSelection() {
    Office.context.document.bindings.addFromSelectionAsync(Office.BindingType.Text, { id: 'MyBinding' }, 
        function (asyncResult) {
        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; 
}

Créez une liaison basée sur la sélection actuelle de l’utilisateur.

addFromSelectionAsync(bindingType: BindingType, callback?: (result: AsyncResult<Binding>) => void): void;

Paramètres

bindingType: Office.BindingType

Spécifie le type de l’objet de liaison à créer. Obligatoire. Retourne null si l’objet sélectionné ne peut pas être renvoyé sous la force dans le type spécifié.

callback: (result: Office.AsyncResult<Office.Binding>) => void

Facultatif. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult. La value propriété du résultat est l’objet Binding qui représente la sélection spécifiée par l’utilisateur.

Retours

void

Remarques

Ensembles de conditions requises :

Ajoute le type spécifié d’objet de liaison à la collection Bindings, qui sera identifiée avec l’ID fourni.

Remarque Dans Excel, si vous appelez la méthode addFromSelectionAsync en passant le Binding.id d’une liaison existante, le binding.type de cette liaison est utilisé et son type ne peut pas être modifié en spécifiant une valeur différente pour le paramètre bindingType. Si vous devez utiliser un ID existant et modifier le bindingType, appelez d’abord la méthode Bindings.releaseByIdAsync pour libérer la liaison, puis appelez la méthode addFromSelectionAsync pour rétablir la liaison avec un nouveau type.

Obtient toutes les liaisons qui ont été créées précédemment.

getAllAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<Binding[]>) => void): void;

Paramètres

options: Office.AsyncContextOptions

Fournit une option permettant de conserver des données de contexte de tout type, inchangées, pour une utilisation dans un rappel.

callback: (result: Office.AsyncResult<Office.Binding[]>) => void

Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult. La value propriété du résultat est un tableau qui contient chaque liaison créée pour l’objet Bindings référencé.

Retours

void

Remarques

Ensembles de conditions requises :

Obtient toutes les liaisons qui ont été créées précédemment.

getAllAsync(callback?: (result: AsyncResult<Binding[]>) => void): void;

Paramètres

callback: (result: Office.AsyncResult<Office.Binding[]>) => void

Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult. La value propriété du résultat est un tableau qui contient chaque liaison créée pour l’objet Bindings référencé.

Retours

void

Remarques

Ensembles de conditions requises :

Exemples

function displayAllBindingNames() {
    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; 
}

Récupère une liaison en fonction de son nom

getByIdAsync(id: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<Binding>) => void): void;

Paramètres

id: string

Spécifie le nom unique de l’objet de liaison. Obligatoire.

options: Office.AsyncContextOptions

Fournit une option permettant de conserver des données de contexte de tout type, inchangées, pour une utilisation dans un rappel.

callback: (result: Office.AsyncResult<Office.Binding>) => void

Facultatif. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult. La value propriété du résultat est l’objet Binding spécifié par l’ID dans l’appel.

Retours

void

Remarques

Ensembles de conditions requises :

Échoue si l’ID spécifié n’existe pas.

Récupère une liaison en fonction de son nom

getByIdAsync(id: string, callback?: (result: AsyncResult<Binding>) => void): void;

Paramètres

id: string

Spécifie le nom unique de l’objet de liaison. Obligatoire.

callback: (result: Office.AsyncResult<Office.Binding>) => void

Facultatif. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult. La value propriété du résultat est l’objet Binding spécifié par l’ID dans l’appel.

Retours

void

Remarques

Ensembles de conditions requises :

Échoue si l’ID spécifié n’existe pas.

Exemples

function displayBindingType() {
    Office.context.document.bindings.getByIdAsync('MyBinding', function (asyncResult) {
        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; 
}

Supprime la liaison du document

releaseByIdAsync(id: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Paramètres

id: string

Spécifie le nom unique à utiliser pour identifier l’objet de liaison. Obligatoire.

options: Office.AsyncContextOptions

Fournit une option permettant de conserver des données de contexte de tout type, inchangées, pour une utilisation dans un rappel.

callback: (result: Office.AsyncResult<void>) => void

Facultatif. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult.

Retours

void

Remarques

Ensembles de conditions requises :

Échoue si l’ID spécifié n’existe pas.

Supprime la liaison du document

releaseByIdAsync(id: string, callback?: (result: AsyncResult<void>) => void): void;

Paramètres

id: string

Spécifie le nom unique à utiliser pour identifier l’objet de liaison. Obligatoire.

callback: (result: Office.AsyncResult<void>) => void

Facultatif. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult.

Retours

void

Remarques

Ensembles de conditions requises :

Échoue si l’ID spécifié n’existe pas.

Exemples

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

addFromNamedItemAsync(itemName, bindingType, options, callback)	Crée une liaison avec un objet nommé dans le document.
addFromNamedItemAsync(itemName, bindingType, callback)	Crée une liaison avec un objet nommé dans le document.
addFromPromptAsync(bindingType, options, callback)	Créez une liaison en invitant l’utilisateur à effectuer une sélection sur le document.
addFromPromptAsync(bindingType, callback)	Créez une liaison en invitant l’utilisateur à effectuer une sélection sur le document.
addFromSelectionAsync(bindingType, options, callback)	Créez une liaison basée sur la sélection actuelle de l’utilisateur.
addFromSelectionAsync(bindingType, callback)	Créez une liaison basée sur la sélection actuelle de l’utilisateur.
getAllAsync(options, callback)	Obtient toutes les liaisons qui ont été créées précédemment.
getAllAsync(callback)	Obtient toutes les liaisons qui ont été créées précédemment.
getByIdAsync(id, options, callback)	Récupère une liaison en fonction de son nom
getByIdAsync(id, callback)	Récupère une liaison en fonction de son nom
releaseByIdAsync(id, options, callback)	Supprime la liaison du document
releaseByIdAsync(id, callback)	Supprime la liaison du document

Propriétés

Méthodes

Détails de la propriété

document

Valeur de propriété

Détails de la méthode

addFromNamedItemAsync(itemName, bindingType, options, callback)

Paramètres

Retours

Remarques

Exemples

addFromNamedItemAsync(itemName, bindingType, callback)

Paramètres

Retours

Remarques

addFromPromptAsync(bindingType, options, callback)

Paramètres

Retours

Remarques

Exemples

addFromPromptAsync(bindingType, callback)

Paramètres

Retours

Remarques

addFromSelectionAsync(bindingType, options, callback)

Paramètres

Retours

Remarques

Exemples

addFromSelectionAsync(bindingType, callback)

Paramètres

Retours

Remarques

getAllAsync(options, callback)

Paramètres

Retours

Remarques

getAllAsync(callback)

Paramètres

Retours

Remarques

Exemples

getByIdAsync(id, options, callback)

Paramètres

Retours

Remarques

getByIdAsync(id, callback)

Paramètres

Retours

Remarques

Exemples

releaseByIdAsync(id, options, callback)

Paramètres

Retours

Remarques

releaseByIdAsync(id, callback)

Paramètres

Retours

Remarques

Exemples

Commentaires

Ressources supplémentaires