Partager via


Office.Document interface

Une classe abstraite qui représente le document avec lequel interagit le complément.

Remarques

Applications : Excel, PowerPoint, Project, Word

Exemples

// Get the Document object with the Common APIs.
const document : Office.Document = Office.context.document;

Propriétés

bindings

Obtient un objet qui fournit l’accès aux liaisons définies dans le document.

customXmlParts

Obtient un objet qui représente les parties XML personnalisées contenues dans le document.

mode

Obtient le mode dans lequel se trouve le document.

settings

Obtient un objet qui représente les paramètres personnalisés enregistrés du complément de contenu ou de volet des tâches pour le document actif.

url

Obtient l’URL du document actuellement ouvert par l’application Office. Retourne null si l’URL n’est pas disponible.

Méthodes

addHandlerAsync(eventType, handler, options, callback)

Ajoute un gestionnaire d’événements pour un événement d’objet Document.

addHandlerAsync(eventType, handler, callback)

Ajoute un gestionnaire d’événements pour un événement d’objet Document.

getActiveViewAsync(options, callback)

Renvoie l’état de l’affichage actuel de la présentation (modification ou lecture).

getActiveViewAsync(callback)

Renvoie l’état de l’affichage actuel de la présentation (modification ou lecture).

getFileAsync(fileType, options, callback)

Renvoie l’intégralité du fichier de document sous forme de sections pouvant aller jusqu’à 4 194 304 octets (4 Mo). Pour les compléments sur iPad, la tranche de fichier est prise en charge jusqu’à 65536 (64 Ko). Remarque : la spécification de la taille de section de fichier au-dessus de la limite autorisée entraîne une erreur interne.

getFileAsync(fileType, callback)

Renvoie l’intégralité du fichier de document sous forme de sections pouvant aller jusqu’à 4 194 304 octets (4 Mo). Pour les compléments sur iPad, la tranche de fichier est prise en charge jusqu’à 65536 (64 Ko). Remarque : la spécification de la taille de section de fichier au-dessus de la limite autorisée entraîne une erreur interne.

getFilePropertiesAsync(options, callback)

Obtient les propriétés de fichier du document actif.

getFilePropertiesAsync(callback)

Obtient les propriétés de fichier du document actif.

getMaxResourceIndexAsync(options, callback)

Documents de projet uniquement. Obtient l’index maximal de la collection de ressources dans le projet actuel.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

getMaxResourceIndexAsync(callback)

Documents de projet uniquement. Obtient l’index maximal de la collection de ressources dans le projet actuel.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

getMaxTaskIndexAsync(options, callback)

Documents de projet uniquement. Obtient l’index maximal de la collection de tâches dans le projet actuel.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

getMaxTaskIndexAsync(callback)

Documents de projet uniquement. Obtient l’index maximal de la collection de tâches dans le projet actuel.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

getProjectFieldAsync(fieldId, options, callback)

Documents de projet uniquement. Obtenir le champ Projet (par exemple, ProjectWebAccessURL).

getProjectFieldAsync(fieldId, callback)

Documents de projet uniquement. Obtenir le champ Projet (par exemple, ProjectWebAccessURL).

getResourceByIndexAsync(resourceIndex, options, callback)

Documents de projet uniquement. Obtenez le GUID de la ressource qui a l’index spécifié dans la collection de ressources.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

getResourceByIndexAsync(resourceIndex, callback)

Documents de projet uniquement. Obtenez le GUID de la ressource qui a l’index spécifié dans la collection de ressources.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

getResourceFieldAsync(resourceId, fieldId, options, callback)

Documents de projet uniquement. Obtenez le champ de ressource pour l’ID de ressource fourni. (par exemple, ResourceName)

getResourceFieldAsync(resourceId, fieldId, callback)

Documents de projet uniquement. Obtenez le champ de ressource pour l’ID de ressource fourni. (par exemple, ResourceName)

getSelectedDataAsync(coercionType, options, callback)

Lit les données contenues dans la sélection actuelle du document.

getSelectedDataAsync(coercionType, callback)

Lit les données contenues dans la sélection actuelle du document.

getSelectedResourceAsync(options, callback)

Documents de projet uniquement. Obtient l’ID de la ressource sélectionnée actuelle.

getSelectedResourceAsync(callback)

Documents de projet uniquement. Obtient l’ID de la ressource sélectionnée actuelle.

getSelectedTaskAsync(options, callback)

Documents de projet uniquement. Obtient l’ID de la tâche sélectionnée actuelle.

getSelectedTaskAsync(callback)

Documents de projet uniquement. Obtient l’ID de la tâche sélectionnée actuelle.

getSelectedViewAsync(options, callback)

Documents de projet uniquement. Obtenez le type d’affichage (par exemple, Gantt) et le nom de la vue sélectionnés.

getSelectedViewAsync(callback)

Documents de projet uniquement. Obtenez le type d’affichage (par exemple, Gantt) et le nom de la vue sélectionnés.

getTaskAsync(taskId, options, callback)

Documents de projet uniquement. Obtenez le Nom de la tâche, l’ID de tâche WSS et les ResourceNames pour taskId donné.

getTaskAsync(taskId, callback)

Documents de projet uniquement. Obtenez le Nom de la tâche, l’ID de tâche WSS et les ResourceNames pour taskId donné.

getTaskByIndexAsync(taskIndex, options, callback)

Documents de projet uniquement. Obtenez le GUID de la tâche qui a l’index spécifié dans la collection de tâches.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

getTaskByIndexAsync(taskIndex, callback)

Documents de projet uniquement. Obtenez le GUID de la tâche qui a l’index spécifié dans la collection de tâches.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

getTaskFieldAsync(taskId, fieldId, options, callback)

Documents de projet uniquement. Obtenir le champ de tâche pour l’ID de tâche fourni. (par exemple, StartDate).

getTaskFieldAsync(taskId, fieldId, callback)

Documents de projet uniquement. Obtenir le champ de tâche pour l’ID de tâche fourni. (par exemple, StartDate).

getWSSUrlAsync(options, callback)

Documents de projet uniquement. Obtenez l’URL WSS et le nom de la liste des tâches. Le MPP est également synchronisé.

getWSSUrlAsync(callback)

Documents de projet uniquement. Obtenez l’URL WSS et le nom de la liste des tâches. Le MPP est également synchronisé.

goToByIdAsync(id, goToType, options, callback)

Accède à l’emplacement ou l’objet spécifié dans le document.

goToByIdAsync(id, goToType, callback)

Accède à l’emplacement ou l’objet spécifié dans le document.

removeHandlerAsync(eventType, options, callback)

Supprime un gestionnaire d’événements pour le type d’événement spécifié.

removeHandlerAsync(eventType, callback)

Supprime un gestionnaire d’événements pour le type d’événement spécifié.

setResourceFieldAsync(resourceId, fieldId, fieldValue, options, callback)

Documents de projet uniquement. Définissez le champ de ressource pour l’ID de ressource spécifié.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

setResourceFieldAsync(resourceId, fieldId, fieldValue, callback)

Documents de projet uniquement. Définissez le champ de ressource pour l’ID de ressource spécifié.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

setSelectedDataAsync(data, options, callback)

Écrit les données spécifiées dans la sélection actuelle.

setSelectedDataAsync(data, callback)

Écrit les données spécifiées dans la sélection actuelle.

setTaskFieldAsync(taskId, fieldId, fieldValue, options, callback)

Documents de projet uniquement. Définissez le champ de tâche pour l’ID de tâche spécifié.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

setTaskFieldAsync(taskId, fieldId, fieldValue, callback)

Documents de projet uniquement. Définissez le champ de tâche pour l’ID de tâche spécifié.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

Détails de la propriété

bindings

Obtient un objet qui fournit l’accès aux liaisons définies dans le document.

bindings: Bindings;

Valeur de propriété

Remarques

Vous n’instanciez pas l’objet Document directement dans votre script. Pour appeler des membres de l’objet Document afin d’interagir avec le document actif ou la feuille de calcul active, utilisez Office.context.document dans votre script.

Exemples

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

customXmlParts

Obtient un objet qui représente les parties XML personnalisées contenues dans le document.

customXmlParts: CustomXmlParts;

Valeur de propriété

Exemples

function getCustomXmlParts(){
    Office.context.document.customXmlParts.getByNamespaceAsync('http://tempuri.org', function (asyncResult) {
        write('Retrieved ' + asyncResult.value.length + ' custom XML parts');
    });
}

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

mode

Obtient le mode dans lequel se trouve le document.

mode: DocumentMode;

Valeur de propriété

Exemples

function displayDocumentMode() {
    write(Office.context.document.mode);
}

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}
// The following example initializes the add-in and then gets properties of the
// Document object that are available in the context of a Project document.
// A Project document is the opened, active project. To access members of the
// ProjectDocument object, use the Office.context.document object as shown in
// the code examples for ProjectDocument methods and events.
// The example assumes your add-in has a reference to the jQuery library and
// that the following page control is defined in the content div in the page body:
// <span id="message"></span>

(function () {
    "use strict";

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason) {
        $(document).ready(function () {

            // Get information about the document.
            showDocumentProperties();
        });
    };

    // Get the document mode and the URL of the active project.
    function showDocumentProperties() {
        const output = String.format(
            'The document mode is {0}.<br/>The URL of the active project is {1}.',
            Office.context.document.mode,
            Office.context.document.url);
        $('#message').html(output);
    }
})();

settings

Obtient un objet qui représente les paramètres personnalisés enregistrés du complément de contenu ou de volet des tâches pour le document actif.

settings: Settings;

Valeur de propriété

url

Obtient l’URL du document actuellement ouvert par l’application Office. Retourne null si l’URL n’est pas disponible.

url: string;

Valeur de propriété

string

Exemples

function displayDocumentUrl() {
    write(Office.context.document.url);
}

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

Détails de la méthode

addHandlerAsync(eventType, handler, options, callback)

Ajoute un gestionnaire d’événements pour un événement d’objet Document.

addHandlerAsync(eventType: Office.EventType, handler: any, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Paramètres

eventType
Office.EventType

Pour un événement d’objet Document, le paramètre eventType peut être spécifié en tant que Office.EventType.Document.SelectionChanged ou Office.EventType.Document.ActiveViewChanged, ou la valeur de texte correspondante de cette énumération.

handler

any

Fonction de gestionnaire d’événements à ajouter, dont le seul paramètre est de type Office.DocumentSelectionChangedEventArgs. Obligatoire.

options
Office.AsyncContextOptions

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

callback

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

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

Retours

void

Remarques

Ensemble de conditions requises : DocumentEvents

Vous pouvez ajouter plusieurs gestionnaires d’événements pour le eventType spécifié tant que le nom de chaque fonction de gestionnaire d’événements est unique.

addHandlerAsync(eventType, handler, callback)

Ajoute un gestionnaire d’événements pour un événement d’objet Document.

addHandlerAsync(eventType: Office.EventType, handler: any, callback?: (result: AsyncResult<void>) => void): void;

Paramètres

eventType
Office.EventType

Pour un événement d’objet Document, le paramètre eventType peut être spécifié en tant que Office.EventType.Document.SelectionChanged ou Office.EventType.Document.ActiveViewChanged, ou la valeur de texte correspondante de cette énumération.

handler

any

Fonction de gestionnaire d’événements à ajouter, dont le seul paramètre est de type Office.DocumentSelectionChangedEventArgs. Obligatoire.

callback

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

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

Retours

void

Remarques

Ensemble de conditions requises : DocumentEvents

Vous pouvez ajouter plusieurs gestionnaires d’événements pour le eventType spécifié tant que le nom de chaque fonction de gestionnaire d’événements est unique.

Exemples

// The following example adds an event handler for the SelectionChanged event of a document
function addSelectionChangedEventHandler() {
    Office.context.document.addHandlerAsync(Office.EventType.DocumentSelectionChanged, MyHandler);
}

function MyHandler(eventArgs) {
    write('Event raised: ' + eventArgs.type);
    doSomethingWithDocument(eventArgs.document);
}

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}
// The following code example adds a handler for the ResourceSelectionChanged event.
// When the resource selection changes in the document, it gets the GUID of the selected resource.
// The example assumes your add-in has a reference to the jQuery library and that the
// following page control is defined in the content div in the page body:
// <span id="message"></span>

(function () {
    "use strict";

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason) {
        $(document).ready(function () {

            // After the DOM is loaded, add-in-specific code can run.
            Office.context.document.addHandlerAsync(
                Office.EventType.ResourceSelectionChanged,
                getResourceGuid);
        });
    };

    // Get the GUID of the selected resource and display it in the add-in.
    function getResourceGuid() {
        Office.context.document.getSelectedResourceAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    $('#message').html(result.value);
                }
            }
        );
    }

    function onError(error) {
        $('#message').html(error.name + ' ' + error.code + ': ' + error.message);
    }
})();

// For a complete code sample that shows how to use a ResourceSelectionChanged
// event handler in a Project add-in, see "Create your first task pane add-in for Microsoft Project".
// https://learn.microsoft.com/office/dev/add-ins/project/create-your-first-task-pane-add-in-for-project-by-using-a-text-editor
// The following code example adds a handler for the TaskSelectionChanged event.
// When the task selection changes in the document, it gets the GUID of the
// selected task.
// The example assumes your add-in has a reference to the jQuery library and that
// the following page control is defined in the content div in the page body:
// <span id="message"></span>

(function () {
    "use strict";

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason) {
        $(document).ready(function () {

            // After the DOM is loaded, add-in-specific code can run.
            Office.context.document.addHandlerAsync(
                Office.EventType.TaskSelectionChanged,
                getTaskGuid);
            getTaskGuid();
        });
    };

    // Get the GUID of the selected task and display it in the add-in.
    function getTaskGuid() {
        Office.context.document.getSelectedTaskAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    $('#message').html(result.value);
                }
            }
        );
    }

    function onError(error) {
        $('#message').html(error.name + ' ' + error.code + ': ' + error.message);
    }
})();
// The following code example adds a handler for the ViewSelectionChanged
// event. When the active view changes, it gets the name and type of the active view.
// The example assumes your add-in has a reference to the jQuery library and that
// the following page control is defined in the content div in the page body:
// <span id="message"></span>

(function () {
    "use strict";

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason) {
        $(document).ready(function () {

            // After the DOM is loaded, add-in-specific code can run.
            Office.context.document.addHandlerAsync(
                Office.EventType.ViewSelectionChanged,
                getActiveView);
            getActiveView();
        });
    };

    // Get the name and type of the active view and display it in the add-in.
    function getActiveView() {
        Office.context.document.getSelectedViewAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    const output = String.format(
                        'View name: {0}<br/>View type: {1}',
                        result.value.viewName, result.value.viewType);
                    $('#message').html(output);
                }
            }
        );
    }

    function onError(error) {
        $('#message').html(error.name + ' ' + error.code + ': ' + error.message);
    }
})();

// For an example that shows how to use a ViewSelectionChanged event handler in a
// Project add-in, see "Create your first task pane add-in for Microsoft Project".
// https://learn.microsoft.com/office/dev/add-ins/project/create-your-first-task-pane-add-in-for-project-by-using-a-text-editor
// The following code example uses addHandlerAsync to add an event handler for the ViewSelectionChanged event.
// When the active view changes, the handler checks the view type. It enables a button if the view is a resource
// view and disables the button if it isn't a resource view. Choosing the button gets the GUID of the selected
// resource and displays it in the add-in.
// The example assumes that your add-in has a reference to the jQuery library and that the following page controls
// are defined in the content div in the page body:
// <input id="get-info" type="button" value="Get info" disabled="disabled" /><br />
// <span id="message"></span>

(function () {
    "use strict";

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason) {
        $(document).ready(function () {

            // After the DOM is loaded, add-in-specific code can run.
            // Add a ViewSelectionChanged event handler.
            Office.context.document.addHandlerAsync(
                Office.EventType.ViewSelectionChanged,
                getActiveView);
            $('#get-info').on("click", getResourceGuid);

            // This example calls the handler on page load to get the active view
            // of the default page.
            getActiveView();
        });
    };

    // Activate the button based on the active view type of the document.
    // This is the ViewSelectionChanged event handler.
    function getActiveView() {
        Office.context.document.getSelectedViewAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    const viewType = result.value.viewType;
                    if (viewType == 6 ||   // ResourceForm
                        viewType == 7 ||   // ResourceSheet
                        viewType == 8 ||   // ResourceGraph
                        viewType == 15) {  // ResourceUsage
                        $('#get-info').removeAttr('disabled');
                    }
                    else {
                        $('#get-info').attr('disabled', 'disabled');
                    }
                    const output = String.format(
                        'View name: {0}<br/>View type: {1}',
                        result.value.viewName, viewType);
                    $('#message').html(output);
                }
            }
        );
    }

    // Get the GUID of the currently selected resource and display it in the add-in.
    function getResourceGuid() {
        Office.context.document.getSelectedResourceAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    $('#message').html('Resource GUID: ' + result.value);
                }
            }
        );
    }

    function onError(error) {
        $('#message').html(error.name + ' ' + error.code + ': ' + error.message);
    }
})();

// For a complete code sample that shows how to use a ViewSelectionChanged event handler in a Project add-in,
// see "Create your first task pane add-in for Project by using a text editor."
// https://learn.microsoft.com/office/dev/add-ins/project/create-your-first-task-pane-add-in-for-project-by-using-a-text-editor

getActiveViewAsync(options, callback)

Renvoie l’état de l’affichage actuel de la présentation (modification ou lecture).

getActiveViewAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<"edit" | "read">) => void): void;

Paramètres

options
Office.AsyncContextOptions

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

callback

(result: Office.AsyncResult<"edit" | "read">) => void

Optional. 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’état de l’affichage actuel de la présentation. La valeur retournée peut être « edit » ou « read ». « modifier » correspond à l’un des affichages dans lesquels vous pouvez modifier des diapositives : Normal, Trieuse de diapositives ou Mode Plan. « read » correspond au diaporama ou au mode Lecture.

Retours

void

Remarques

Ensemble de conditions requises : ActiveView

Peut déclencher un événement lorsque l’affichage change.

getActiveViewAsync(callback)

Renvoie l’état de l’affichage actuel de la présentation (modification ou lecture).

getActiveViewAsync(callback?: (result: AsyncResult<"edit" | "read">) => void): void;

Paramètres

callback

(result: Office.AsyncResult<"edit" | "read">) => void

Optional. 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’état de l’affichage actuel de la présentation. La valeur retournée peut être « edit » ou « read ». « modifier » correspond à l’un des affichages dans lesquels vous pouvez modifier des diapositives : Normal, Trieuse de diapositives ou Mode Plan. « read » correspond au diaporama ou au mode Lecture.

Retours

void

Remarques

Ensemble de conditions requises : ActiveView

Peut déclencher un événement lorsque l’affichage change.

Exemples

function getFileView() {
    // Get whether the current view is edit or read.
    Office.context.document.getActiveViewAsync(function (asyncResult) {
        if (asyncResult.status == "failed") {
            showMessage("Action failed with error: " + asyncResult.error.message);
        }
        else {
            showMessage(asyncResult.value);
        }
    });
}

getFileAsync(fileType, options, callback)

Renvoie l’intégralité du fichier de document sous forme de sections pouvant aller jusqu’à 4 194 304 octets (4 Mo). Pour les compléments sur iPad, la tranche de fichier est prise en charge jusqu’à 65536 (64 Ko). Remarque : la spécification de la taille de section de fichier au-dessus de la limite autorisée entraîne une erreur interne.

getFileAsync(fileType: FileType, options?: GetFileOptions, callback?: (result: AsyncResult<Office.File>) => void): void;

Paramètres

fileType
Office.FileType

Format dans lequel le fichier sera retourné

options
Office.GetFileOptions

Fournit des options pour définir la taille des tranches dans lesquelles le document sera divisé.

callback

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

Optional. 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 File.

Retours

void

Remarques

Ensembles de conditions requises :

Pour les compléments exécutés dans des applications Office autres qu’Office sur iPad, la méthode prend en charge l’obtention getFileAsync de fichiers par tranches allant jusqu’à 4194304 octets (4 Mo). Pour les compléments exécutés dans les applications Office sur iPad, la méthode prend en charge l’obtention getFileAsync de fichiers par tranches allant jusqu’à 65536 (64 Ko).

Le fileType paramètre peut être spécifié à l’aide de l’énumération Office.FileType ou des valeurs de texte. Mais les valeurs possibles varient selon l’application.

Types de fichiers pris en charge, par plateforme

Office sur le web Office pour Windows Office sur Mac Office sur iPad
Excel Compressed, Pdf Compressed, Pdf, TextCompressed, Pdf, Text Non pris en charge
Powerpoint Compressed, Pdf Compressed, Pdf Compressed, Pdf Compressed, Pdf
Word Compressed, Pdf, TextCompressed, Pdf, TextCompressed, Pdf, TextCompressed, Pdf

Exemples

// The following example gets the document in Office Open XML ("compressed") format in 65536 bytes (64 KB) slices.
// Note: The implementation of app.showNotification in this example is from the Visual Studio template for Office Add-ins.
function getDocumentAsCompressed() {
    Office.context.document.getFileAsync(Office.FileType.Compressed, { sliceSize: 65536 /*64 KB*/ }, 
        function (result) {
            if (result.status == "succeeded") {
                // If the getFileAsync call succeeded, then
                // result.value will return a valid File Object.
                const myFile = result.value;
                const sliceCount = myFile.sliceCount;
                const docDataSlices = [];
                let slicesReceived = 0, gotAllSlices = true;
                app.showNotification("File size:" + myFile.size + " #Slices: " + sliceCount);

                // Get the file slices.
                getSliceAsync(myFile, 0, sliceCount, gotAllSlices, docDataSlices, slicesReceived);
            } else {
                app.showNotification("Error:", result.error.message);
            }
    });
}

function getSliceAsync(file, nextSlice, sliceCount, gotAllSlices, docDataSlices, slicesReceived) {
    file.getSliceAsync(nextSlice, function (sliceResult) {
        if (sliceResult.status == "succeeded") {
            if (!gotAllSlices) { /* Failed to get all slices, no need to continue. */
                return;
            }

            // Got one slice, store it in a temporary array.
            // (Or you can do something else, such as
            // send it to a third-party server.)
            docDataSlices[sliceResult.value.index] = sliceResult.value.data;
            if (++slicesReceived == sliceCount) {
              // All slices have been received.
              file.closeAsync();
              onGotAllSlices(docDataSlices);
            }
            else {
                getSliceAsync(file, ++nextSlice, sliceCount, gotAllSlices, docDataSlices, slicesReceived);
            }
        }
            else {
                gotAllSlices = false;
                file.closeAsync();
                app.showNotification("getSliceAsync Error:", sliceResult.error.message);
            }
    });
}

function onGotAllSlices(docDataSlices) {
    let docData = [];
    for (let i = 0; i < docDataSlices.length; i++) {
        docData = docData.concat(docDataSlices[i]);
    }

    let fileContent = new String();
    for (let j = 0; j < docData.length; j++) {
        fileContent += String.fromCharCode(docData[j]);
    }

    // Now all the file content is stored in 'fileContent' variable,
    // you can do something with it, such as print, fax...
}

// The following example gets the document in PDF format.
Office.context.document.getFileAsync(Office.FileType.Pdf,
    function(result) {
        if (result.status == "succeeded") {
            const myFile = result.value;
            const sliceCount = myFile.sliceCount;
            app.showNotification("File size:" + myFile.size + " #Slices: " + sliceCount);

            // Get the file slices.
            const docDataSlices = [];
            let slicesReceived = 0, gotAllSlices = true;
            getSliceAsync(myFile, 0, sliceCount, gotAllSlices, docDataSlices, slicesReceived);
            
            myFile.closeAsync();
        }
        else {
            app.showNotification("Error:", result.error.message);
        }
    }
);

getFileAsync(fileType, callback)

Renvoie l’intégralité du fichier de document sous forme de sections pouvant aller jusqu’à 4 194 304 octets (4 Mo). Pour les compléments sur iPad, la tranche de fichier est prise en charge jusqu’à 65536 (64 Ko). Remarque : la spécification de la taille de section de fichier au-dessus de la limite autorisée entraîne une erreur interne.

getFileAsync(fileType: FileType, callback?: (result: AsyncResult<Office.File>) => void): void;

Paramètres

fileType
Office.FileType

Format dans lequel le fichier sera retourné

callback

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

Optional. 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 File.

Retours

void

Remarques

Ensembles de conditions requises :

Pour les compléments exécutés dans des applications Office autres qu’Office sur iPad, la méthode prend en charge l’obtention getFileAsync de fichiers par tranches allant jusqu’à 4194304 octets (4 Mo). Pour les compléments exécutés dans les applications Office sur iPad, la méthode prend en charge l’obtention getFileAsync de fichiers par tranches allant jusqu’à 65536 (64 Ko).

Le fileType paramètre peut être spécifié à l’aide de l’énumération Office.FileType ou des valeurs de texte. Mais les valeurs possibles varient selon l’application.

Types de fichiers pris en charge, par plateforme

Office sur le web Office pour Windows Office sur Mac Office sur iPad
Excel Compressed, Pdf Compressed, Pdf, TextCompressed, Pdf, Text Non pris en charge
Powerpoint Compressed, Pdf Compressed, Pdf Compressed, Pdf Compressed, Pdf
Word Compressed, Pdf, TextCompressed, Pdf, TextCompressed, Pdf, TextCompressed, Pdf

getFilePropertiesAsync(options, callback)

Obtient les propriétés de fichier du document actif.

getFilePropertiesAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<Office.FileProperties>) => void): void;

Paramètres

options
Office.AsyncContextOptions

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

callback

(result: Office.AsyncResult<Office.FileProperties>) => 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 les propriétés du fichier (avec l’URL trouvée à l’emplacement asyncResult.value.url).

Retours

void

Remarques

Ensembles de conditions requises : pas dans un ensemble

Vous obtenez l’URL du fichier avec la propriété asyncResult.value.urlurl .

getFilePropertiesAsync(callback)

Obtient les propriétés de fichier du document actif.

getFilePropertiesAsync(callback?: (result: AsyncResult<Office.FileProperties>) => void): void;

Paramètres

callback

(result: Office.AsyncResult<Office.FileProperties>) => 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 les propriétés du fichier (avec l’URL trouvée à l’emplacement asyncResult.value.url).

Retours

void

Remarques

Ensembles de conditions requises : pas dans un ensemble

Vous obtenez l’URL du fichier avec la propriété asyncResult.value.urlurl .

Exemples

// To read the URL of the current file, you need to write a callback function that returns the URL.
// The following example shows how to:
// 1. Pass an anonymous callback function that returns the value of the file's URL
//    to the callback parameter of the getFilePropertiesAsync method.
// 2. Display the value on the add-in's page.
function getFileUrl() {
    // Get the URL of the current file.
    Office.context.document.getFilePropertiesAsync(function (asyncResult) {
        const fileUrl = asyncResult.value.url;
        if (fileUrl == "") {
            showMessage("The file hasn't been saved yet. Save the file and try again");
        }
        else {
            showMessage(fileUrl);
        }
    });
}

getMaxResourceIndexAsync(options, callback)

Documents de projet uniquement. Obtient l’index maximal de la collection de ressources dans le projet actuel.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

getMaxResourceIndexAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<number>) => void): void;

Paramètres

options
Office.AsyncContextOptions

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

callback

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

Optional. 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 le numéro d’index le plus élevé dans la collection de ressources du projet actuel.

Retours

void

getMaxResourceIndexAsync(callback)

Documents de projet uniquement. Obtient l’index maximal de la collection de ressources dans le projet actuel.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

getMaxResourceIndexAsync(callback?: (result: AsyncResult<number>) => void): void;

Paramètres

callback

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

Optional. 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 le numéro d’index le plus élevé dans la collection de ressources du projet actuel.

Retours

void

Exemples

// The following code example calls getResourceTaskIndexAsync to get the maximum index of the collection 
// of resources in the current project. Then it uses the returned value and the getResourceByIndexAsync
// method to get each resource GUID. The example assumes that your add-in has a reference to the 
// jQuery library and that the following page controls are defined in the content div in the page body:
// <input id="get-info" type="button" value="Get info" /><br />
// <span id="message"></span>

(function () {
    "use strict";
    const resourceGuids = [];

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason) {
        $(document).ready(function () {

            // After the DOM is loaded, add-in-specific code can run.
            app.initialize();
            $('#get-info').on("click", getResourceInfo);
        });
    };

    // Get the maximum resource index, and then get the resource GUIDs.
    function getResourceInfo() {
        getMaxResourceIndex().then(
            function (data) {
                getResourceGuids(data);
            }
        );
    }

    // Get the maximum index of the resources for the current project.
    function getMaxResourceIndex() {
        const defer = $.Deferred();
        Office.context.document.getMaxResourceIndexAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    defer.resolve(result.value);
                }
            }
        );
        return defer.promise();
    }

    // Get each resource GUID, and then display the GUIDs in the add-in.
    // There is no 0 index for resources, so start with index 1.
    function getResourceGuids(maxResourceIndex) {
        const defer = $.Deferred();
        for (let i = 1; i <= maxResourceIndex; i++) {
            getResourceGuid(i);
        }
        return defer.promise();
        function getResourceGuid(index) {
            Office.context.document.getResourceByIndexAsync(index,
                function (result) {
                    if (result.status === Office.AsyncResultStatus.Succeeded) {
                        resourceGuids.push(result.value);
                        if (index == maxResourceIndex) {
                            defer.resolve();
                            $('#message').html(resourceGuids.toString());
                        }
                    }
                    else {
                        onError(result.error);
                    }
                }
            );
        }
    }
    function onError(error) {
        app.showNotification(error.name + ' ' + error.code + ': ' + error.message);
    }
})();

getMaxTaskIndexAsync(options, callback)

Documents de projet uniquement. Obtient l’index maximal de la collection de tâches dans le projet actuel.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

getMaxTaskIndexAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<number>) => void): void;

Paramètres

options
Office.AsyncContextOptions

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

callback

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

Optional. 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 le numéro d’index le plus élevé dans la collection de tâches du projet actuel.

Retours

void

getMaxTaskIndexAsync(callback)

Documents de projet uniquement. Obtient l’index maximal de la collection de tâches dans le projet actuel.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

getMaxTaskIndexAsync(callback?: (result: AsyncResult<number>) => void): void;

Paramètres

callback

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

Optional. 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 le numéro d’index le plus élevé dans la collection de tâches du projet actuel.

Retours

void

Exemples

// The following code example calls getMaxTaskIndexAsync to get the maximum index
// of the collection of tasks in the current project. Then it uses the returned value
// with the getTaskByIndexAsync method to get each task GUID.
// The example assumes your add-in has a reference to the jQuery library and that the
// following page controls are defined in the content div in the page body:
// <input id="get-info" type="button" value="Get info" /><br />
// <span id="message"></span>

(function () {
    "use strict";
    const taskGuids = [];

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason) {
        $(document).ready(function () {

            // After the DOM is loaded, add-in-specific code can run.
            app.initialize();
            $('#get-info').on("click", getTaskInfo);
        });
    };

    // Get the maximum task index, and then get the task GUIDs.
    function getTaskInfo() {
        getMaxTaskIndex().then(
            function (data) {
                getTaskGuids(data);
            }
        );
    }

    // Get the maximum index of the tasks for the current project.
    function getMaxTaskIndex() {
        const defer = $.Deferred();
        Office.context.document.getMaxTaskIndexAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    defer.resolve(result.value);
                }
            }
        );
        return defer.promise();
    }

    // Get each task GUID, and then display the GUIDs in the add-in.
    function getTaskGuids(maxTaskIndex) {
        const defer = $.Deferred();
        for (let i = 0; i <= maxTaskIndex; i++) {
            getTaskGuid(i);
        }
        return defer.promise();
        function getTaskGuid(index) {
            Office.context.document.getTaskByIndexAsync(index,
                function (result) {
                    if (result.status === Office.AsyncResultStatus.Succeeded) {
                        taskGuids.push(result.value);
                        if (index == maxTaskIndex) {
                            defer.resolve();
                            $('#message').html(taskGuids.toString());
                        }
                    }
                    else {
                        onError(result.error);
                    }
                }
            );
        }
    }
    function onError(error) {
        app.showNotification(error.name + ' ' + error.code + ': ' + error.message);
    }
})();

getProjectFieldAsync(fieldId, options, callback)

Documents de projet uniquement. Obtenir le champ Projet (par exemple, ProjectWebAccessURL).

getProjectFieldAsync(fieldId: number, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<any>) => void): void;

Paramètres

fieldId

number

Champs au niveau du projet.

options
Office.AsyncContextOptions

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

callback

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

Optional. 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 contient la fieldValue propriété , qui représente la valeur du champ spécifié.

Retours

void

getProjectFieldAsync(fieldId, callback)

Documents de projet uniquement. Obtenir le champ Projet (par exemple, ProjectWebAccessURL).

getProjectFieldAsync(fieldId: number, callback?: (result: AsyncResult<any>) => void): void;

Paramètres

fieldId

number

Champs au niveau du projet.

callback

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

Optional. 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 contient la fieldValue propriété , qui représente la valeur du champ spécifié.

Retours

void

Exemples

// The following code example gets the values of three specified fields for the active project, 
// and then displays the values in the add-in.
// The example calls getProjectFieldAsync recursively, after the previous call returns successfully.
// It also tracks the calls to determine when all calls are sent.
// The example assumes your add-in has a reference to the jQuery library and that the 
// following page control is defined in the content div in the page body:
// <span id="message"></span>

(function () {
    "use strict";

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason) {
        $(document).ready(function () {

            // Get information for the active project.
            getProjectInformation();
        });
    };

    // Get the specified fields for the active project.
    function getProjectInformation() {
        const fields =
            [Office.ProjectProjectFields.Start, 
             Office.ProjectProjectFields.Finish, 
             Office.ProjectProjectFields.GUID];
        const fieldValues = ['Start: ', 'Finish: ', 'GUID: '];
        let index = 0; 
        getField();

        // Get each field, and then display the field values in the add-in.
        function getField() {
            if (index == fields.length) {
                let output = '';
                for (let i = 0; i < fieldValues.length; i++) {
                    output += fieldValues[i] + '<br />';
                }
                $('#message').html(output);
            }
            else {
                Office.context.document.getProjectFieldAsync(
                    fields[index],
                    function (result) {

                        // If the call is successful, get the field value and then get the next field.
                        if (result.status === Office.AsyncResultStatus.Succeeded) {
                            fieldValues[index] += result.value.fieldValue;
                            getField(index++);
                        }
                        else {
                            onError(result.error);
                        }
                    }
                );
            }
        }
    }

    function onError(error) {
        $('#message').html(error.name + ' ' + error.code + ': ' + error.message);
    }
})();

getResourceByIndexAsync(resourceIndex, options, callback)

Documents de projet uniquement. Obtenez le GUID de la ressource qui a l’index spécifié dans la collection de ressources.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

getResourceByIndexAsync(resourceIndex: number, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<string>) => void): void;

Paramètres

resourceIndex

number

Index de la ressource dans la collection de ressources pour le projet.

options
Office.AsyncContextOptions

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

callback

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

Optional. 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 le GUID de la ressource sous forme de chaîne.

Retours

void

getResourceByIndexAsync(resourceIndex, callback)

Documents de projet uniquement. Obtenez le GUID de la ressource qui a l’index spécifié dans la collection de ressources.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

getResourceByIndexAsync(resourceIndex: number, callback?: (result: AsyncResult<string>) => void): void;

Paramètres

resourceIndex

number

Index de la ressource dans la collection de ressources pour le projet.

callback

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

Optional. 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 le GUID de la ressource sous forme de chaîne.

Retours

void

Exemples

// The following code example calls getMaxResourceIndexAsync to get the maximum index in the project's resource
// collection, and then calls getResourceByIndexAsync to get the GUID for each resource.
// The example assumes that your add-in has a reference to the jQuery library and that the following 
// page controls are defined in the content div in the page body:
// <input id="get-info" type="button" value="Get info" /><br />
// <span id="message"></span>

(function () {
    "use strict";
    const resourceGuids = [];

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason) {
        $(document).ready(function () {

            // After the DOM is loaded, add-in-specific code can run.
            app.initialize();
            $('#get-info').on("click", getResourceInfo);
        });
    };

    // Get the maximum resource index, and then get the resource GUIDs.
    function getResourceInfo() {
        getMaxResourceIndex().then(
            function (data) {
                getResourceGuids(data);
            }
        );
    }

    // Get the maximum index of the resources for the current project.
    function getMaxResourceIndex() {
        const defer = $.Deferred();
        Office.context.document.getMaxResourceIndexAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    defer.resolve(result.value);
                }
            }
        );
        return defer.promise();
    }

    // Get each resource GUID, and then display the GUIDs in the add-in.
    // There is no 0 index for resources, so start with index 1.
    function getResourceGuids(maxResourceIndex) {
        const defer = $.Deferred();
        for (let i = 1; i <= maxResourceIndex; i++) {
            getResourceGuid(i);
        }
        return defer.promise();
        function getResourceGuid(index) {
            Office.context.document.getResourceByIndexAsync(index,
                function (result) {
                    if (result.status === Office.AsyncResultStatus.Succeeded) {
                        resourceGuids.push(result.value);
                        if (index == maxResourceIndex) {
                            defer.resolve();
                            $('#message').html(resourceGuids.toString());
                        }
                    }
                    else {
                        onError(result.error);
                    }
                }
            );
        }
    }
    function onError(error) {
        app.showNotification(error.name + ' ' + error.code + ': ' + error.message);
    }
})();

getResourceFieldAsync(resourceId, fieldId, options, callback)

Documents de projet uniquement. Obtenez le champ de ressource pour l’ID de ressource fourni. (par exemple, ResourceName)

getResourceFieldAsync(resourceId: string, fieldId: number, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<string>) => void): void;

Paramètres

resourceId

string

Chaîne ou valeur de l’ID de ressource.

fieldId

number

Champs de ressources.

options
Office.AsyncContextOptions

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

callback

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

Optional. 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 le GUID de la ressource sous forme de chaîne.

Retours

void

getResourceFieldAsync(resourceId, fieldId, callback)

Documents de projet uniquement. Obtenez le champ de ressource pour l’ID de ressource fourni. (par exemple, ResourceName)

getResourceFieldAsync(resourceId: string, fieldId: number, callback?: (result: AsyncResult<string>) => void): void;

Paramètres

resourceId

string

Chaîne ou valeur de l’ID de ressource.

fieldId

number

Champs de ressources.

callback

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

Optional. 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 le GUID de la ressource sous forme de chaîne.

Retours

void

Exemples

// The following code example calls getSelectedResourceAsync to get the GUID of the resource
// that's currently selected in a resource view. Then it gets three resource field values by calling 
// getResourceFieldAsync recursively.
// The example assumes your add-in has a reference to the jQuery library and that the following 
// page controls are defined in the content div in the page body:
// <input id="get-info" type="button" value="Get info" /><br />
// <span id="message"></span>

(function () {
    "use strict";

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason) {
        $(document).ready(function () {

            // After the DOM is loaded, add-in-specific code can run.
            $('#get-info').on("click", getResourceInfo);
        });
    };

    // Get the GUID of the resource and then get the resource fields.
    function getResourceInfo() {
        getResourceGuid().then(
            function (data) {
                getResourceFields(data);
            }
        );
    }

    // Get the GUID of the selected resource.
    function getResourceGuid() {
        const defer = $.Deferred();
        Office.context.document.getSelectedResourceAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    defer.resolve(result.value);
                }
            }
        );
        return defer.promise();
    }

    // Get the specified fields for the selected resource.
    function getResourceFields(resourceGuid) {
        const targetFields =
            [Office.ProjectResourceFields.Name,
             Office.ProjectResourceFields.Units, 
             Office.ProjectResourceFields.BaseCalendar];
        const fieldValues = ['Name: ', 'Units: ', 'Base calendar: '];
        let index = 0; 
        getField();

        // Get each field, and then display the field values in the add-in.
        function getField() {
            if (index == targetFields.length) {
                let output = '';
                for (let i = 0; i < fieldValues.length; i++) {
                    output += fieldValues[i] + '<br />';
                }
                $('#message').html(output);
            }

            // If the call is successful, get the field value and then get the next field.
            else {
                Office.context.document.getResourceFieldAsync(
                    resourceGuid,
                    targetFields[index],
                    function (result) {
                        if (result.status === Office.AsyncResultStatus.Succeeded) {
                            fieldValues[index] += result.value.fieldValue;
                            getField(index++);
                        }
                        else {
                            onError(result.error);
                        }
                    }
                );
            }
        }
    }

    function onError(error) {
        $('#message').html(error.name + ' ' + error.code + ': ' + error.message);
    }
})();

getSelectedDataAsync(coercionType, options, callback)

Lit les données contenues dans la sélection actuelle du document.

getSelectedDataAsync<T>(coercionType: Office.CoercionType, options?: GetSelectedDataOptions, callback?: (result: AsyncResult<T>) => void): void;

Paramètres

coercionType
Office.CoercionType

Type de structure de données à renvoyer. Consultez la section Remarques pour connaître les types de forçage pris en charge par chaque application.

options
Office.GetSelectedDataOptions

Fournit des options de personnalisation des données retournées et de leur mise en forme.

callback

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

Optional. 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 les données de la sélection actuelle. Cela est retourné dans la structure de données ou le format que vous avez spécifié avec le paramètre coercionType. (Voir Remarques pour plus d’informations sur le forçage de type de données.)

Retours

void

Remarques

Ensembles de conditions requises :

Dans la fonction de rappel transmise à la méthode getSelectedDataAsync, vous pouvez utiliser les propriétés de l’objet AsyncResult pour retourner les informations suivantes.

Propriété Utilisation
AsyncResult.value Retourne undefined toujours, car il n’y a pas d’objet ou de données à récupérer.
AsyncResult.status Déterminer si l’opération a réussi ou échoué.
AsyncResult.error Accéder à un objet Error fournissant des informations sur l’erreur en cas d’échec de l’opération.
AsyncResult.asyncContext Définissez un élément de tout type retourné dans l’objet AsyncResult sans être modifié.

Les valeurs possibles pour le paramètre Office.CoercionType varient selon l’application Office.

CoercionType Applications prises en charge
Office.CoercionType.Html
  • Word
Office.CoercionType.Matrix (tableau de tableaux)
  • Excel
  • Word
Office.CoercionType.Ooxml (Office Open XML)
  • Word
Office.CoercionType.SlideRange
  • PowerPoint
Office.CoercionType.Table (Objet TableData)
  • Excel
  • Word
Office.CoercionType.Text (chaîne)
  • Excel
  • PowerPoint
  • Project
  • Word
Office.CoercionType.XmlSvg
  • Excel sur Windows et sur Mac

Exemples

// The following example uses the getSelectedDataAsync method of the Document object to retrieve the
// user's current selection as text, and then display it in the add-in's page.

// Displays the user's current selection.
function showSelection() {
    Office.context.document.getSelectedDataAsync(
        Office.CoercionType.Text,
        {
            valueFormat: Office.ValueFormat.Unformatted,
            filterType: Office.FilterType.All
        },
        (result) => {
            const dataValue = result.value;
            write('Selected data is: ' + dataValue);
        }
    );
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}
// To read the value of the current selection, you need to write a callback function that reads the selection.
// The following example shows how to:
// 1. Pass an anonymous callback function that reads the value of the current selection
//    to the callback parameter of the getSelectedDataAsync method.
// 2. Read the selection as text, unformatted, and not filtered.
// 3. Display the value on the add-in's page.
function getText() {
    Office.context.document.getSelectedDataAsync(
        Office.CoercionType.Text,
        {
            valueFormat: Office.ValueFormat.Unformatted,
            filterType: Office.FilterType.All
        },
        (asyncResult) => {
            const error = asyncResult.error;
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                write(error.name + ": " + error.message);
            } 
            else {
                // Get selected data.
                const dataValue = asyncResult.value; 
                write('Selected data is ' + dataValue);
            }
        }
    );
}

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}
// The following code example gets the values of the selected cells. It uses the optional
// asyncContext parameter to pass some text to the callback function.
// The example assumes your add-in has a reference to the jQuery library and that the
// following page controls are defined in the content div in the page body:
// <input id="get-info" type="button" value="Get info" /><br />
// <span id="message"></span>

// The onReady function must be run each time a new page is loaded.
Office.onReady(() => {
    $(document).ready(() => {
        // After the DOM is loaded, add-in-specific code can run.
        $('#get-info').on("click", getSelectedText);
    });
});

// Gets the text from the selected cells in the document, and displays it in the add-in.
function getSelectedText() {
    Office.context.document.getSelectedDataAsync(
        Office.CoercionType.Text,
        { asyncContext: "Some related info" },
        (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) {
                onError(result.error);
            }
            else {
                const output = String.format(
                    'Selected text: {0}<br/>Passed info: {1}',
                    result.value, result.asyncContext);
                $('#message').html(output);
            }
        }
    );
}

function onError(error) {
    $('#message').html(error.name + ' ' + error.code + ': ' + error.message);
}

getSelectedDataAsync(coercionType, callback)

Lit les données contenues dans la sélection actuelle du document.

getSelectedDataAsync<T>(coercionType: Office.CoercionType, callback?: (result: AsyncResult<T>) => void): void;

Paramètres

coercionType
Office.CoercionType

Type de structure de données à renvoyer. Consultez la section Remarques pour connaître les types de forçage pris en charge par chaque application.

callback

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

Optional. 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 les données de la sélection actuelle. Cela est retourné dans la structure de données ou le format que vous avez spécifié avec le paramètre coercionType. (Voir Remarques pour plus d’informations sur le forçage de type de données.)

Retours

void

Remarques

Ensembles de conditions requises :

Dans la fonction de rappel transmise à la méthode getSelectedDataAsync, vous pouvez utiliser les propriétés de l’objet AsyncResult pour retourner les informations suivantes.

Propriété Utilisation
AsyncResult.value Retourne undefined toujours, car il n’y a pas d’objet ou de données à récupérer.
AsyncResult.status Déterminer si l’opération a réussi ou échoué.
AsyncResult.error Accéder à un objet Error fournissant des informations sur l’erreur en cas d’échec de l’opération.
AsyncResult.asyncContext Définissez un élément de tout type retourné dans l’objet AsyncResult sans être modifié.

Les valeurs possibles pour le paramètre Office.CoercionType varient selon l’application Office.

CoercionType Applications prises en charge
Office.CoercionType.Html
  • Word
Office.CoercionType.Matrix (tableau de tableaux)
  • Excel
  • Word
Office.CoercionType.Ooxml (Office Open XML)
  • Word
Office.CoercionType.SlideRange
  • PowerPoint
Office.CoercionType.Table (Objet TableData)
  • Excel
  • Word
Office.CoercionType.Text (chaîne)
  • Excel
  • PowerPoint
  • Project
  • Word
Office.CoercionType.XmlSvg
  • Excel sur Windows et sur Mac

getSelectedResourceAsync(options, callback)

Documents de projet uniquement. Obtient l’ID de la ressource sélectionnée actuelle.

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

Paramètres

options
Office.AsyncContextOptions

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

callback

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

Optional. 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 le GUID de la ressource sous forme de chaîne.

Retours

void

getSelectedResourceAsync(callback)

Documents de projet uniquement. Obtient l’ID de la ressource sélectionnée actuelle.

getSelectedResourceAsync(callback?: (result: AsyncResult<string>) => void): void;

Paramètres

callback

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

Optional. 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 le GUID de la ressource sous forme de chaîne.

Retours

void

Exemples

// The following code example calls getSelectedResourceAsync to get the GUID of the resource that's 
// currently selected in a resource view. Then it gets three resource field values by calling 
// getResourceFieldAsync recursively.
// The example assumes your add-in has a reference to the jQuery library and that the following page controls are
// defined in the content div in the page body:
// <input id="get-info" type="button" value="Get info" /><br />
// <span id="message"></span>

(function () {
    "use strict";

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason) {
        $(document).ready(function () {

            // After the DOM is loaded, add-in-specific code can run.
            $('#get-info').on("click", getResourceInfo);
        });
    };

    // Get the GUID of the resource and then get the resource fields.
    function getResourceInfo() {
        getResourceGuid().then(
            function (data) {
                getResourceFields(data);
            }
        );
    }

    // Get the GUID of the selected resource.
    function getResourceGuid() {
        const defer = $.Deferred();
        Office.context.document.getSelectedResourceAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    defer.resolve(result.value);
                }
            }
        );
        return defer.promise();
    }

    // Get the specified fields for the selected resource.
    function getResourceFields(resourceGuid) {
        const targetFields =
            [Office.ProjectResourceFields.Name,
             Office.ProjectResourceFields.Units, 
             Office.ProjectResourceFields.BaseCalendar];
        const fieldValues = ['Name: ', 'Units: ', 'Base calendar: '];
        let index = 0; 
        getField();

        // Get each field, and then display the field values in the add-in.
        function getField() {
            if (index == targetFields.length) {
                let output = '';
                for (let i = 0; i < fieldValues.length; i++) {
                    output += fieldValues[i] + '<br />';
                }
                $('#message').html(output);
            }

            // If the call is successful, get the field value and then get the next field.
            else {
                Office.context.document.getResourceFieldAsync(
                    resourceGuid,
                    targetFields[index],
                    function (result) {
                        if (result.status === Office.AsyncResultStatus.Succeeded) {
                            fieldValues[index] += result.value.fieldValue;
                            getField(index++);
                        }
                        else {
                            onError(result.error);
                        }
                    }
                );
            }
        }
    }

    function onError(error) {
        $('#message').html(error.name + ' ' + error.code + ': ' + error.message);
    }
})();

getSelectedTaskAsync(options, callback)

Documents de projet uniquement. Obtient l’ID de la tâche sélectionnée actuelle.

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

Paramètres

options
Office.AsyncContextOptions

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

callback

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

Optional. 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 le GUID de la ressource sous forme de chaîne.

Retours

void

getSelectedTaskAsync(callback)

Documents de projet uniquement. Obtient l’ID de la tâche sélectionnée actuelle.

getSelectedTaskAsync(callback?: (result: AsyncResult<string>) => void): void;

Paramètres

callback

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

Optional. 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 le GUID de la ressource sous forme de chaîne.

Retours

void

Exemples

// The following code example calls getSelectedTaskAsync to get the GUID of the task that's currently
// selected in a task view. Then it gets task properties by calling getTaskAsync.
// The example assumes your add-in has a reference to the jQuery library and that the following page
// controls are defined in the content div in the page body:
// <input id="get-info" type="button" value="Get info" /><br />
// <span id="message"></span>

(function () {
    "use strict";

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason) {
        $(document).ready(function () {

            // After the DOM is loaded, add-in-specific code can run.
            $('#get-info').on("click", getTaskInfo);
        });
    };

    // // Get the GUID of the task, and then get local task properties.
    function getTaskInfo() {
        getTaskGuid().then(
            function (data) {
                getTaskProperties(data);
            }
        );
    }

    // Get the GUID of the selected task.
    function getTaskGuid() {
        const defer = $.Deferred();
        Office.context.document.getSelectedTaskAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    defer.resolve(result.value);
                }
            }
        );
        return defer.promise();
    }

    // Get local properties for the selected task, and then display it in the add-in.
    function getTaskProperties(taskGuid) {
        Office.context.document.getTaskAsync(
            taskGuid,
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    const taskInfo = result.value;
                    const output = String.format(
                        'Name: {0}<br/>GUID: {1}<br/>SharePoint task ID: {2}<br/>Resource names: {3}',
                        taskInfo.taskName, taskGuid, taskInfo.wssTaskId, taskInfo.resourceNames);
                    $('#message').html(output);
                }
            }
        );
    }

    function onError(error) {
        $('#message').html(error.name + ' ' + error.code + ': ' + error.message);
    }
})();

getSelectedViewAsync(options, callback)

Documents de projet uniquement. Obtenez le type d’affichage (par exemple, Gantt) et le nom de la vue sélectionnés.

getSelectedViewAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<any>) => void): void;

Paramètres

options
Office.AsyncContextOptions

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

callback

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

Optional. 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 contient les propriétés suivantes : viewName - Le nom de la vue, en tant que constante ProjectViewTypes. viewType - Type de vue, en tant que valeur entière d’une constante ProjectViewTypes.

Retours

void

getSelectedViewAsync(callback)

Documents de projet uniquement. Obtenez le type d’affichage (par exemple, Gantt) et le nom de la vue sélectionnés.

getSelectedViewAsync(callback?: (result: AsyncResult<any>) => void): void;

Paramètres

callback

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

Optional. 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 contient les propriétés suivantes : viewName - Le nom de la vue, en tant que constante ProjectViewTypes. viewType - Type de vue, en tant que valeur entière d’une constante ProjectViewTypes.

Retours

void

Exemples

// The following code example calls adds a ViewSelectionChanged event handler that
// calls getSelectedViewAsync to get the name and type of the active view in the document.
// The example assumes your add-in has a reference to the jQuery library and that
// the following page control is defined in the content div in the page body:
// <span id="message"></span>

(function () {
    "use strict";

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason) {
        $(document).ready(function () {

            // After the DOM is loaded, add-in-specific code can run.
            Office.context.document.addHandlerAsync(
                Office.EventType.ViewSelectionChanged,
                getActiveView);
            getActiveView();
        });
    };

    // Get the active view's name and type.
    function getActiveView() {
        Office.context.document.getSelectedViewAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    const output = String.format(
                        'View name: {0}<br/>View type: {1}',
                        result.value.viewName, viewType);
                    $('#message').html(output);
                }
            }
        );
    }

    function onError(error) {
        $('#message').html(error.name + ' ' + error.code + ': ' + error.message);
    }
})();

getTaskAsync(taskId, options, callback)

Documents de projet uniquement. Obtenez le Nom de la tâche, l’ID de tâche WSS et les ResourceNames pour taskId donné.

getTaskAsync(taskId: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<any>) => void): void;

Paramètres

taskId

string

Chaîne ou valeur de l’ID de tâche.

options
Office.AsyncContextOptions

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

callback

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

Optional. 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 contient les propriétés suivantes : taskName - Nom de la tâche. wssTaskId - ID de la tâche dans la liste de tâches SharePoint synchronisée. Si le projet n’est pas synchronisé avec une liste de tâches SharePoint, la valeur est 0. resourceNames - Liste séparée par des virgules des noms des ressources affectées à la tâche.

Retours

void

getTaskAsync(taskId, callback)

Documents de projet uniquement. Obtenez le Nom de la tâche, l’ID de tâche WSS et les ResourceNames pour taskId donné.

getTaskAsync(taskId: string, callback?: (result: AsyncResult<any>) => void): void;

Paramètres

taskId

string

Chaîne ou valeur de l’ID de tâche.

callback

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

Optional. 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 contient les propriétés suivantes : taskName - Nom de la tâche. wssTaskId - ID de la tâche dans la liste de tâches SharePoint synchronisée. Si le projet n’est pas synchronisé avec une liste de tâches SharePoint, la valeur est 0. resourceNames - Liste séparée par des virgules des noms des ressources affectées à la tâche.

Retours

void

Exemples

// The following code example calls getSelectedTaskAsync to get the task GUID of the currently
// selected task. Then it calls getTaskAsync to get the properties for the task that are
// available from the JavaScript API for Office.
// The example assumes your add-in has a reference to the jQuery library and that the
// following page controls are defined in the content div in the page body:
// <input id="get-info" type="button" value="Get info" /><br />
// <span id="message"></span>

(function () {
    "use strict";

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason) {
        $(document).ready(function () {

            // After the DOM is loaded, add-in-specific code can run.
            $('#get-info').on("click", getTaskInfo);
        });
    };

    // Get the GUID of the task, and then get local task properties.
    function getTaskInfo() {
        getTaskGuid().then(
            function (data) {
                getTaskProperties(data);
            }
        );
    }

    // Get the GUID of the selected task.
    function getTaskGuid() {
        const defer = $.Deferred();
        Office.context.document.getSelectedTaskAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    defer.resolve(result.value);
                }
            }
        );
        return defer.promise();
    }

    // Get local properties for the selected task, and then display it in the add-in.
    function getTaskProperties(taskGuid) {
        Office.context.document.getTaskAsync(
            taskGuid,
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    const taskInfo = result.value;
                    const output = String.format(
                        'Name: {0}<br/>GUID: {1}<br/>SharePoint task ID: {2}<br/>Resource names: {3}',
                        taskInfo.taskName, taskGuid, taskInfo.wssTaskId, taskInfo.resourceNames);
                    $('#message').html(output);
                }
            }
        );
    }

    function onError(error) {
        $('#message').html(error.name + ' ' + error.code + ': ' + error.message);
    }
})();

getTaskByIndexAsync(taskIndex, options, callback)

Documents de projet uniquement. Obtenez le GUID de la tâche qui a l’index spécifié dans la collection de tâches.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

getTaskByIndexAsync(taskIndex: number, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<string>) => void): void;

Paramètres

taskIndex

number

Index de la tâche dans la collection de tâches pour le projet.

options
Office.AsyncContextOptions

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

callback

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

Optional. 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 le GUID de la tâche sous forme de chaîne.

Retours

void

getTaskByIndexAsync(taskIndex, callback)

Documents de projet uniquement. Obtenez le GUID de la tâche qui a l’index spécifié dans la collection de tâches.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

getTaskByIndexAsync(taskIndex: number, callback?: (result: AsyncResult<string>) => void): void;

Paramètres

taskIndex

number

Index de la tâche dans la collection de tâches pour le projet.

callback

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

Optional. 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 le GUID de la tâche sous forme de chaîne.

Retours

void

Exemples

// The following code example calls getMaxTaskIndexAsync to get the
// maximum index in the project's task collection, and then
// calls getTaskByIndexAsync to get the GUID for each task.
// The example assumes that your add-in has a reference to the
// jQuery library and that the following page controls are defined
// in the content div in the page body:
// <input id="get-info" type="button" value="Get info" /><br />
// <span id="message"></span>

(function () {
    "use strict";
    const taskGuids = [];

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason) {
        $(document).ready(function () {

            // After the DOM is loaded, add-in-specific code can run.
            app.initialize();
            $('#get-info').on("click", getTaskInfo);
        });
    };

    // Get the maximum task index, and then get the task GUIDs.
    function getTaskInfo() {
        getMaxTaskIndex().then(
            function (data) {
                getTaskGuids(data);
            }
        );
    }

    // Get the maximum index of the tasks for the current project.
    function getMaxTaskIndex() {
        const defer = $.Deferred();
        Office.context.document.getMaxTaskIndexAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    defer.resolve(result.value);
                }
            }
        );
        return defer.promise();
    }

    // Get each task GUID, and then display the GUIDs in the add-in.
    function getTaskGuids(maxTaskIndex) {
        const defer = $.Deferred();
        for (let i = 0; i <= maxTaskIndex; i++) {
            getTaskGuid(i);
        }
        return defer.promise();
        function getTaskGuid(index) {
            Office.context.document.getTaskByIndexAsync(index,
                function (result) {
                    if (result.status === Office.AsyncResultStatus.Succeeded) {
                        taskGuids.push(result.value);
                        if (index == maxTaskIndex) {
                            defer.resolve();
                            $('#message').html(taskGuids.toString());
                        }
                    }
                    else {
                        onError(result.error);
                    }
                }
            );
        }
    }
    function onError(error) {
        app.showNotification(error.name + ' ' + error.code + ': ' + error.message);
    }
})();

getTaskFieldAsync(taskId, fieldId, options, callback)

Documents de projet uniquement. Obtenir le champ de tâche pour l’ID de tâche fourni. (par exemple, StartDate).

getTaskFieldAsync(taskId: string, fieldId: number, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<any>) => void): void;

Paramètres

taskId

string

Chaîne ou valeur de l’ID de tâche.

fieldId

number

Champs de tâche.

options
Office.AsyncContextOptions

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

callback

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

Optional. 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 contient la fieldValue propriété , qui représente la valeur du champ spécifié.

Retours

void

getTaskFieldAsync(taskId, fieldId, callback)

Documents de projet uniquement. Obtenir le champ de tâche pour l’ID de tâche fourni. (par exemple, StartDate).

getTaskFieldAsync(taskId: string, fieldId: number, callback?: (result: AsyncResult<any>) => void): void;

Paramètres

taskId

string

Chaîne ou valeur de l’ID de tâche.

fieldId

number

Champs de tâche.

callback

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

Optional. 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 contient la fieldValue propriété , qui représente la valeur du champ spécifié.

Retours

void

Exemples

// The following code example calls getSelectedTaskAsync to get the GUID of the task that's currently
// selected in a task view. Then it gets two task field values by calling getTaskFieldAsync recursively.
// The example assumes your add-in has a reference to the jQuery library and that the following page
// controls are defined in the content div in the page body:
// <input id="get-info" type="button" value="Get info" /><br />
// <span id="message"></span>

(function () {
    "use strict";

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason) {
        $(document).ready(function () {
            
            // After the DOM is loaded, add-in-specific code can run.
            $('#get-info').on("click", getTaskInfo);
        });
    };

    // Get the GUID of the task, and then get the task fields.
    function getTaskInfo() {
        getTaskGuid().then(
            function (data) {
                getTaskFields(data);
            }
        );
    }

    // Get the GUID of the selected task.
    function getTaskGuid() {
        const defer = $.Deferred();
        Office.context.document.getSelectedTaskAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    defer.resolve(result.value);
                }
            }
        );
        return defer.promise();
    }

    // Get the specified fields for the selected task.
    function getTaskFields(taskGuid) {
        let output = '';
        const targetFields = [Office.ProjectTaskFields.Priority, Office.ProjectTaskFields.PercentComplete];
        const fieldValues = ['Priority: ', '% Complete: '];
        let index = 0;
        getField();

        // Get each field, and then display the field values in the add-in.
        function getField() {
            if (index == targetFields.length) {
                for (let i = 0; i < fieldValues.length; i++) {
                    output += fieldValues[i] + '<br />';
                }
                $('#message').html(output);
            }

            // Get the field value. If the call is successful, then get the next field.
            else {
                Office.context.document.getTaskFieldAsync(
                    taskGuid,
                    targetFields[index],
                    function (result) {
                        if (result.status === Office.AsyncResultStatus.Succeeded) {
                            fieldValues[index] += result.value.fieldValue;
                            getField(index++);
                        }
                        else {
                            onError(result.error);
                        }
                    }
                );
            }
        }
    }

    function onError(error) {
        $('#message').html(error.name + ' ' + error.code + ': ' + error.message);
    }
})();

getWSSUrlAsync(options, callback)

Documents de projet uniquement. Obtenez l’URL WSS et le nom de la liste des tâches. Le MPP est également synchronisé.

getWSSUrlAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<any>) => void): void;

Paramètres

options
Office.AsyncContextOptions

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

callback

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

Optional. 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 contient les propriétés suivantes : listName - nom de la liste de tâches SharePoint synchronisée. serverUrl : URL de la liste de tâches SharePoint synchronisée.

Retours

void

getWSSUrlAsync(callback)

Documents de projet uniquement. Obtenez l’URL WSS et le nom de la liste des tâches. Le MPP est également synchronisé.

getWSSUrlAsync(callback?: (result: AsyncResult<any>) => void): void;

Paramètres

callback

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

Optional. 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 contient les propriétés suivantes : listName - nom de la liste de tâches SharePoint synchronisée. serverUrl : URL de la liste de tâches SharePoint synchronisée.

Retours

void

goToByIdAsync(id, goToType, options, callback)

Accède à l’emplacement ou l’objet spécifié dans le document.

goToByIdAsync(id: string | number, goToType: GoToType, options?: GoToByIdOptions, callback?: (result: AsyncResult<any>) => void): void;

Paramètres

id

string | number

Identifiant de l’objet ou de l’emplacement à atteindre.

goToType
Office.GoToType

Type d’emplacement à atteindre.

options
Office.GoToByIdOptions

Fournit des options permettant de sélectionner ou non l’emplacement auquel vous accédez.

callback

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

Optional. 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 la vue actuelle.

Retours

void

Remarques

Ensemble de conditions requises : pas dans un ensemble

PowerPoint ne prend pas en charge la méthode goToByIdAsync dans les affichages maîtres.

Le comportement provoqué par l’option selectionMode varie selon l’application Office :

Dans Excel : Office.SelectionMode.Selected sélectionne tout le contenu de la liaison ou de l’élément nommé. Office.SelectionMode.None pour les liaisons de texte, sélectionne la cellule ; pour les liaisons de matrice, les liaisons de tableau et les éléments nommés, sélectionne la première cellule de données (pas la première cellule dans la ligne d’en-tête pour les tableaux).

Dans PowerPoint : Office.SelectionMode.Selected sélectionne le titre ou la première zone de texte de la diapositive. Office.SelectionMode.None ne sélectionne rien.

Dans Word : Office.SelectionMode.Selected sélectionne tout le contenu de la liaison. Office.SelectionMode.None pour les liaisons de texte, déplace le curseur au début du texte ; pour les liaisons de matrice et de tableau, sélectionne la première cellule de données (pas la première cellule dans la ligne d’en-tête pour les tableaux).

goToByIdAsync(id, goToType, callback)

Accède à l’emplacement ou l’objet spécifié dans le document.

goToByIdAsync(id: string | number, goToType: GoToType, callback?: (result: AsyncResult<any>) => void): void;

Paramètres

id

string | number

Identifiant de l’objet ou de l’emplacement à atteindre.

goToType
Office.GoToType

Type d’emplacement à atteindre.

callback

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

Optional. 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 la vue actuelle.

Retours

void

Remarques

Ensemble de conditions requises : pas dans un ensemble

PowerPoint ne prend pas en charge la méthode goToByIdAsync dans les affichages maîtres.

Le comportement provoqué par l’option selectionMode varie selon l’application Office :

Dans Excel : Office.SelectionMode.Selected sélectionne tout le contenu de la liaison ou de l’élément nommé. Office.SelectionMode.None pour les liaisons de texte, sélectionne la cellule ; pour les liaisons de matrice, les liaisons de tableau et les éléments nommés, sélectionne la première cellule de données (pas la première cellule dans la ligne d’en-tête pour les tableaux).

Dans PowerPoint : Office.SelectionMode.Selected sélectionne le titre ou la première zone de texte de la diapositive. Office.SelectionMode.None ne sélectionne rien.

Dans Word : Office.SelectionMode.Selected sélectionne tout le contenu de la liaison. Office.SelectionMode.None pour les liaisons de texte, déplace le curseur au début du texte ; pour les liaisons de matrice et de tableau, sélectionne la première cellule de données (pas la première cellule dans la ligne d’en-tête pour les tableaux).

Exemples

// Go to a binding by id (Word and Excel)
// The following example shows how to:
// 1. Create a table binding using the addFromSelectionAsync method as a sample binding to work with.
// 2. Specify that binding as the binding to go to.
// 3. Pass an anonymous callback function that returns the status of the operation
//    to the callback parameter of the goToByIdAsync method.
// 4. Display the value on the add-in's page.
function gotoBinding() {
    // Create a new table binding for the selected table.
    Office.context.document.bindings.addFromSelectionAsync("table",{ id: "MyTableBinding" }, function (asyncResult) {
    if (asyncResult.status == "failed") {
              showMessage("Action failed with error: " + asyncResult.error.message);
          }
          else {
              showMessage("Added new binding with type: " + asyncResult.value.type +" and id: " + asyncResult.value.id);
          }
    });

    // Go to binding by id.
    Office.context.document.goToByIdAsync("MyTableBinding", Office.GoToType.Binding, function (asyncResult) {
        if (asyncResult.status == "failed") {
            showMessage("Action failed with error: " + asyncResult.error.message);
        }
        else {
            showMessage("Navigation successful");
        }
    });
}

// Go to a table in a spreadsheet (Excel)
// The following example shows how to:
// 1. Specify a table by name as the table to go to.
// 2. Pass an anonymous callback function that returns the status of the operation
//    to the callback parameter of the goToByIdAsync method.
// 3. Display the value on the add-in's page.
function goToTable() {
    Office.context.document.goToByIdAsync("Table1", Office.GoToType.NamedItem, function (asyncResult) {
        if (asyncResult.status == "failed") {
            showMessage("Action failed with error: " + asyncResult.error.message);
        }
        else {
            showMessage("Navigation successful");
        }
    });
}

// Go to the currently selected slide by id (PowerPoint)
// The following example shows how to:
// 1. Get the id of the currently selected slides using the getSelectedDataAsync method.
// 2. Specify the returned id as the slide to go to.
// 3. Pass an anonymous callback function that returns the status of the operation
//    to the callback parameter of the goToByIdAsync method.
// 4. Display the value of the stringified JSON object returned by asyncResult.value,
//    which contains information about the selected slides, on the add-in's page.
let firstSlideId = 0;
function gotoSelectedSlide() {
    //Get currently selected slide's id
    Office.context.document.getSelectedDataAsync(Office.CoercionType.SlideRange, function (asyncResult) {
        if (asyncResult.status == "failed") {
            app.showNotification("Action failed with error: " + asyncResult.error.message);
        }
        else {
            firstSlideId = asyncResult.value.slides[0].id;
            app.showNotification(JSON.stringify(asyncResult.value));
        }
    });
    //Go to slide by id.
    Office.context.document.goToByIdAsync(firstSlideId, Office.GoToType.Slide, function (asyncResult) {
        if (asyncResult.status == "failed") {
            app.showNotification("Action failed with error: " + asyncResult.error.message);
        }
        else {
            app.showNotification("Navigation successful");
        }
    });
}

// Go to slide by index (PowerPoint)
// The following example shows how to:
// 1. Specify the index of the first, last, previous, or next slide to go to.
// 2. Pass an anonymous callback function that returns the status of the operation
//    to the callback parameter of the goToByIdAsync method.
// 3. Display the value on the add-in's page.
function goToSlideByIndex() {
    const goToFirst = Office.Index.First;
    const goToLast = Office.Index.Last;
    const goToPrevious = Office.Index.Previous;
    const goToNext = Office.Index.Next;

    Office.context.document.goToByIdAsync(goToNext, Office.GoToType.Index, function (asyncResult) {
        if (asyncResult.status == "failed") {
            showMessage("Action failed with error: " + asyncResult.error.message);
        }
        else {
            showMessage("Navigation successful");
        }
    });
}

removeHandlerAsync(eventType, options, callback)

Supprime un gestionnaire d’événements pour le type d’événement spécifié.

removeHandlerAsync(eventType: Office.EventType, options?: RemoveHandlerOptions, callback?: (result: AsyncResult<void>) => void): void;

Paramètres

eventType
Office.EventType

Type d’événement. Pour le document peut être « Document.SelectionChanged » ou « Document.ActiveViewChanged ».

options
Office.RemoveHandlerOptions

Fournit des options pour déterminer le ou les gestionnaires d’événements qui sont supprimés.

callback

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

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

Retours

void

Remarques

Ensemble de conditions requises : DocumentEvents

removeHandlerAsync(eventType, callback)

Supprime un gestionnaire d’événements pour le type d’événement spécifié.

removeHandlerAsync(eventType: Office.EventType, callback?: (result: AsyncResult<void>) => void): void;

Paramètres

eventType
Office.EventType

Type d’événement. Pour le document peut être « Document.SelectionChanged » ou « Document.ActiveViewChanged ».

callback

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

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

Retours

void

Remarques

Ensemble de conditions requises : DocumentEvents

Exemples

// The following example removes the event handler named 'MyHandler'.
function removeSelectionChangedEventHandler() {
    Office.context.document.removeHandlerAsync(Office.EventType.DocumentSelectionChanged, {handler:MyHandler});
}

function MyHandler(eventArgs) {
    doSomethingWithDocument(eventArgs.document);
}
// The following code example uses addHandlerAsync to add an event handler for the
// ResourceSelectionChanged event and removeHandlerAsync to remove the handler.
// When a resource is selected in a resource view, the handler displays the
// resource GUID. When the handler is removed, the GUID is not displayed.
// The example assumes that your add-in has a reference to the jQuery library and
// that the following page control is defined in the content div in the page body:
// <input id="remove-handler" type="button" value="Remove handler" /><br />
// <span id="message"></span>

(function () {
    "use strict";

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason) {
        $(document).ready(function () {

            // After the DOM is loaded, add-in-specific code can run.
            Office.context.document.addHandlerAsync(
                Office.EventType.ResourceSelectionChanged,
                getResourceGuid);
            $('#remove-handler').on("click", removeEventHandler);
        });
    };

    // Remove the event handler.
    function removeEventHandler() {
        Office.context.document.removeHandlerAsync(
            Office.EventType.ResourceSelectionChanged,
            {handler:getResourceGuid,
            asyncContext:'The handler is removed.'},
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    $('#remove-handler').attr('disabled', 'disabled');
                    $('#message').html(result.asyncContext);
                }
            }
        );
    }

    // Get the GUID of the currently selected resource and display it in the add-in.
    function getResourceGuid() {
        Office.context.document.getSelectedResourceAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    $('#message').html('Resource GUID: ' + result.value);
                }
            }
        );
    }

    function onError(error) {
        $('#message').html(error.name + ' ' + error.code + ': ' + error.message);
    }
})();

setResourceFieldAsync(resourceId, fieldId, fieldValue, options, callback)

Documents de projet uniquement. Définissez le champ de ressource pour l’ID de ressource spécifié.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

setResourceFieldAsync(resourceId: string, fieldId: number, fieldValue: string | number | boolean | object, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Paramètres

resourceId

string

Chaîne ou valeur de l’ID de ressource.

fieldId

number

Champs de ressources.

fieldValue

string | number | boolean | object

Valeur du champ cible.

options
Office.AsyncContextOptions

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

callback

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

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

Retours

void

setResourceFieldAsync(resourceId, fieldId, fieldValue, callback)

Documents de projet uniquement. Définissez le champ de ressource pour l’ID de ressource spécifié.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

setResourceFieldAsync(resourceId: string, fieldId: number, fieldValue: string | number | boolean | object, callback?: (result: AsyncResult<void>) => void): void;

Paramètres

resourceId

string

Chaîne ou valeur de l’ID de ressource.

fieldId

number

Champs de ressources.

fieldValue

string | number | boolean | object

Valeur du champ cible.

callback

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

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

Retours

void

Exemples

// The following code example calls getSelectedResourceAsync to get the GUID of the resource that's
// currently selected in a resource view. Then it sets two resource field values by calling
// setResourceFieldAsync recursively.
// The getSelectedTaskAsync method used in the example requires that a task view
// (for example, Task Usage) is the active view and that a task is selected. See the addHandlerAsync
// method for an example that activates a button based on the active view type.
// The example assumes your add-in has a reference to the jQuery library and that the
// following page controls are defined in the content div in the page body:
// <input id="set-info" type="button" value="Set info" /><br />
// <span id="message"></span>

(function () {
    "use strict";

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason) {
        $(document).ready(function () {

            // After the DOM is loaded, add-in-specific code can run.
            app.initialize();
            $('#set-info').on("click", setResourceInfo);
        });
    };

    // Get the GUID of the resource, and then get the resource fields.
    function setResourceInfo() {
        getResourceGuid().then(
            function (data) {
                setResourceFields(data);
            }
        );
    }

    // Get the GUID of the selected resource.
    function getResourceGuid() {
        const defer = $.Deferred();
        Office.context.document.getSelectedResourceAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    defer.resolve(result.value);
                }
            }
        );
        return defer.promise();
    }

    // Set the specified fields for the selected resource.
    function setResourceFields(resourceGuid) {
        const targetFields = [Office.ProjectResourceFields.StandardRate, Office.ProjectResourceFields.Notes];
        const fieldValues = [.28, 'Notes for the resource.'];

        // Set the field value. If the call is successful, set the next field.
        for (let i = 0; i < targetFields.length; i++) {
            Office.context.document.setResourceFieldAsync(
                resourceGuid,
                targetFields[i],
                fieldValues[i],
                function (result) {
                    if (result.status === Office.AsyncResultStatus.Succeeded) {
                        i++;
                    }
                    else {
                        onError(result.error);
                    }
                }
            );
        }
        $('#message').html('Field values set');
    }

    function onError(error) {
        app.showNotification(error.name + ' ' + error.code + ': ' + error.message);
    }
})();

setSelectedDataAsync(data, options, callback)

Écrit les données spécifiées dans la sélection actuelle.

setSelectedDataAsync(data: string | TableData | any[][], options?: SetSelectedDataOptions, callback?: (result: AsyncResult<void>) => void): void;

Paramètres

data

string | Office.TableData | any[][]

Données à définir. Valeur string ou Office.CoercionType , tableau 2D ou objet TableData.

Si la valeur passée pour data est :

  • Une chaîne : Du texte brut ou tout élément dont le type peut être forcé en type string sera inséré. Dans Excel, vous pouvez également spécifier des données en tant que formule valide pour ajouter cette formule à la cellule sélectionnée. Par exemple, la définition du paramètre data sur "=SUM(A1:A5)" totalisera les valeurs de la plage spécifiée. Toutefois, après avoir défini une formule sur la cellule liée, vous ne pouvez pas lire la formule ajoutée (ni les formules préexistantes) à partir de la cellule liée. Si vous appelez la méthode Document.getSelectedDataAsync sur la cellule sélectionnée pour en lire les données, la méthode peut renvoyer uniquement les données affichées dans la cellule (le résultat de la formule).

  • Un tableau de tableaux (« matrice ») : Des données tabulaires sans en-tête seront insérées. Par exemple, pour écrire des données dans trois lignes dans deux colonnes, vous pouvez passer un tableau comme suit : [["R1C1 », « R1C2"], ["R2C1 », « R2C2"], ["R3C1 », « R3C2"]]. Pour écrire une seule colonne de trois lignes, transmettez un tableau comme suit : [["R1C1"], ["R2C1"], ["R3C1"]]

Dans Excel, vous pouvez également spécifier le paramètre data en tant que tableau de tableaux contenant des formules valides pour les ajouter aux cellules sélectionnées. Par exemple, si aucune autre donnée n’est remplacée, la définition de données sur [["=SUM(A1 :A5) »,"=AVERAGE(A1 :A5)"]] ajoute ces deux formules à la sélection. Comme lors de la définition d’une formule sur une cellule unique en tant que « texte », vous ne pouvez pas lire les formules ajoutées (ni les formules préexistantes) après leur définition. Vous pouvez uniquement lire les résultats des formules.

  • Un objet TableData : Un tableau avec des en-têtes est inséré. Dans Excel, si vous spécifiez des formules dans l’objet TableData que vous passez pour le paramètre de données, vous risquez de ne pas obtenir les résultats attendus en raison de la fonctionnalité « colonnes calculées » d’Excel, qui duplique automatiquement les formules dans une colonne. Pour contourner ce problème lorsque vous souhaitez écrire data des formules dans une table sélectionnée, essayez de spécifier les données sous la forme d’un tableau de tableaux (au lieu d’un objet TableData) et spécifiez coercionType comme Microsoft.Office.Matrix ou « matrice ». Toutefois, cette technique bloque la fonctionnalité de « colonnes calculées » uniquement lorsque l’une des conditions suivantes est remplie : (1) vous écrivez dans toutes les cellules de la colonne, ou (2) il existe déjà au moins deux formules différentes dans la colonne.
options
Office.SetSelectedDataOptions

Fournit des options permettant d’insérer des données dans la sélection.

callback

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

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult. La propriété AsyncResult.value retourne undefined toujours, car il n’y a pas d’objet ou de données à récupérer.

Retours

void

Remarques

Ensembles de conditions requises :

Comportements propres à l’application

Les actions spécifiques à l’application suivantes s’appliquent lors de l’écriture de données dans une sélection.

Application Condition Comportement
Word S’il n’y a pas de sélection et que le point d’insertion se trouve à un emplacement valide, le spécifié data est inséré au point d’insertion Si data est une chaîne, le texte spécifié est inséré.
Si data est un tableau de tableaux (« matrice ») ou un objet TableData, une nouvelle table Word est insérée.
Si data a la valeur HTML, le code HTML spécifié est inséré. (**Important** : si l’un des fichiers HTML que vous insérez n’est pas valide, Word ne génère pas d’erreur. Word insère autant de code HTML que possible et omet toutes les données non valides).
Si data est Office Open XML, le code XML spécifié est inséré.
Si data est un flux d’image encodé en Base64, l’image spécifiée est insérée.
S’il y a une sélection Il sera remplacé par le spécifié data suivant les mêmes règles que ci-dessus.
Insérer des images Les images insérées sont placées en ligne. Les paramètres imageLeft et imageTop sont ignorés. Les proportions de l’image sont toujours verrouillées. Si seul un des paramètres imageWidth et imageHeight est donné, l’autre valeur est automatiquement redimensionnée pour conserver les proportions d’origine.
Excel Si une seule cellule est sélectionnée Si data est une chaîne, le texte spécifié est inséré comme valeur de la cellule active.
Si data est un tableau de tableaux (« matrice »), l’ensemble de lignes et de colonnes spécifié est inséré, si aucune autre donnée dans les cellules environnantes n’est remplacée.
Si data est un objet TableData, un nouveau tableau Excel avec l’ensemble spécifié de lignes et d’en-têtes est inséré, si aucune autre donnée dans les cellules environnantes ne sera remplacée.
Si plusieurs cellules sont sélectionnées Si la forme ne correspond pas à la forme de data, une erreur est retournée.
Si la forme de la sélection correspond exactement à la forme de data, les valeurs des cellules sélectionnées sont mises à jour en fonction des valeurs dans data.
Insérer des images Les images insérées sont flottantes. Les paramètres position imageLeft et imageTop sont relatifs aux cellules actuellement sélectionnées. Les valeurs imageLeft et imageTop négatives sont autorisées et éventuellement réajustées par Excel pour positionner l’image dans une feuille de calcul. Les proportions sont verrouillées à moins que les paramètres imageWidth et imageHeight soient tous deux indiqués. Si seul un des paramètres imageWidth et imageHeight est donné, l’autre valeur est automatiquement redimensionnée pour conserver les proportions d’origine.
Tous les autres cas Une erreur est retournée.
Excel sur le web En plus des comportements décrits pour Excel ci-dessus, ces limites s’appliquent lors de l’écriture de données dans Excel sur le Web Le nombre total de cellules que vous pouvez écrire dans une feuille de calcul avec le data paramètre ne peut pas dépasser 20 000 en un seul appel à cette méthode.
Le nombre de groupes de mise en forme passés au cellFormat paramètre ne peut pas dépasser 100. Un groupe de mise en forme se compose d’un ensemble de mises en forme appliquées à une plage de cellules donnée.
PowerPoint Insérer une image Les images insérées sont flottantes. Les paramètres position imageLeft et imageTop sont facultatifs, mais s’ils sont fournis, les deux doivent être présents. Si une seule valeur est indiquée, elle sera ignorée. Les valeurs imageLeft et imageTop négatives sont autorisées et peuvent positionner une image en dehors d’une diapositive. Si aucun paramètre facultatif n’est indiqué et qu’une diapositive présente un espace réservé, l’image remplacera l’espace réservé dans la diapositive. Les proportions de l’image seront verrouillées, sauf si les paramètres imageWidth et imageHeight sont tous deux indiqués. Si seul un des paramètres imageWidth et imageHeight est donné, l’autre valeur est automatiquement redimensionnée pour conserver les proportions d’origine.

Applications

Les valeurs possibles pour le paramètre Office.CoercionType varient selon l’application Office.

CoercionType Applications prises en charge
Office.CoercionType.Html
  • Word
Office.CoercionType.Matrix (tableau de tableaux)
  • Excel
  • Word
Office.CoercionType.Ooxml (Office Open XML)
  • Word
Office.CoercionType.SlideRange
  • PowerPoint sur le web et sur Windows
Office.CoercionType.Table (Objet TableData)
  • Excel
  • Word
Office.CoercionType.Text (chaîne)
  • Excel
  • PowerPoint
  • Project
  • Word
Office.CoercionType.XmlSvg
  • Excel sur Windows et sur Mac
  • PowerPoint sur le web, sur Windows et sur Mac
  • Word sur Windows et sur Mac

Exemples

// The following example sets the selected text or cell to "Hello World!", 
// and if that fails, displays the value of the error.message property.
function writeText() {
    Office.context.document.setSelectedDataAsync("Hello World!",
        function (asyncResult) {
            const error = asyncResult.error;
            if (asyncResult.status === Office.AsyncResultStatus.Failed){
                write(error.name + ": " + error.message);
            }
        });
}

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

// Specifying the optional coercionType parameter lets you specify the kind of data you want to write
// to a selection. The following example writes data as an array of three rows of two columns, 
// specifying the coercionType as `Matrix` for that data structure, and if that fails, 
// displays the value of the error.message property.
function writeMatrix() {
    Office.context.document.setSelectedDataAsync(
        [["Red", "Rojo"], ["Green", "Verde"], ["Blue", "Azul"]],
        {coercionType: Office.CoercionType.Matrix}
        function (asyncResult) {
            const error = asyncResult.error;
            if (asyncResult.status === Office.AsyncResultStatus.Failed){
                write(error.name + ": " + 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 writes data as a one column table with a header and four rows, 
// specifying the coercionType as `Table` for that data structure, and if that fails, 
// displays the value of the error.message property.
function writeTable() {
    // Build table.
    const myTable = new Office.TableData();
    myTable.headers = [["Cities"]];
    myTable.rows = [['Berlin'], ['Roma'], ['Tokyo'], ['Seattle']];

    // Write table.
    Office.context.document.setSelectedDataAsync(myTable, {coercionType: Office.CoercionType.Table},
        function (result) {
            const error = result.error
            if (result.status === Office.AsyncResultStatus.Failed) {
                write(error.name + ": " + error.message);
            }
    });
}

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

// In Word if you want to write HTML to the selection, you can specify the coercionType parameter as `Html`
// as shown in the following example, which uses HTML <b> tags to make "Hello" bold.
function writeHtmlData() {
    Office.context.document.setSelectedDataAsync(
        "<b>Hello</b> World!", {coercionType: Office.CoercionType.Html}, function (asyncResult) {
            if (asyncResult.status === Office.AsyncResultStatus.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; 
}

// In Word, PowerPoint, or Excel, if you want to write an image to the selection, you can specify the coercionType
// parameter as `Image` as shown in the following example. Note that imageLeft and imageTop are ignored by Word.
function insertPictureAtSelection(base64EncodedImageStr) {

    Office.context.document.setSelectedDataAsync(base64EncodedImageStr, {
        coercionType: Office.CoercionType.Image,
        imageLeft: 50,
        imageTop: 50,
        imageWidth: 100,
        imageHeight: 100
    },
    function (asyncResult) {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            console.log("Action failed with error: " + asyncResult.error.message);
        }
    });
}

// In Word, PowerPoint, or Excel, if you want to write an scalable vector graphic (SVG) to the selection, you can specify the 
// coercionType parameter as `XmlSvg` as shown in the following example. Note that imageLeft and imageTop are ignored by Word.
function insertSvgAtSelection(base64EncodedImageStr) {
    Office.context.document.setSelectedDataAsync(getImageAsBase64String(), {
        coercionType: Office.CoercionType.XmlSvg,
        imageLeft: 50,
        imageTop: 50,
        imageWidth: 400
    },
        function (asyncResult) {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(asyncResult.error.message);
            }
        });
}

setSelectedDataAsync(data, callback)

Écrit les données spécifiées dans la sélection actuelle.

setSelectedDataAsync(data: string | TableData | any[][], callback?: (result: AsyncResult<void>) => void): void;

Paramètres

data

string | Office.TableData | any[][]

Données à définir. Valeur string ou Office.CoercionType , tableau 2D ou objet TableData.

Si la valeur passée pour data est :

  • Une chaîne : Du texte brut ou tout élément dont le type peut être forcé en type string sera inséré. Dans Excel, vous pouvez également spécifier des données en tant que formule valide pour ajouter cette formule à la cellule sélectionnée. Par exemple, la définition du paramètre data sur "=SUM(A1:A5)" totalisera les valeurs de la plage spécifiée. Toutefois, après avoir défini une formule sur la cellule liée, vous ne pouvez pas lire la formule ajoutée (ni les formules préexistantes) à partir de la cellule liée. Si vous appelez la méthode Document.getSelectedDataAsync sur la cellule sélectionnée pour en lire les données, la méthode peut renvoyer uniquement les données affichées dans la cellule (le résultat de la formule).

  • Un tableau de tableaux (« matrice ») : Des données tabulaires sans en-tête seront insérées. Par exemple, pour écrire des données dans trois lignes dans deux colonnes, vous pouvez passer un tableau comme suit : [["R1C1 », « R1C2"], ["R2C1 », « R2C2"], ["R3C1 », « R3C2"]]. Pour écrire une seule colonne de trois lignes, transmettez un tableau comme suit : [["R1C1"], ["R2C1"], ["R3C1"]]

Dans Excel, vous pouvez également spécifier le paramètre data en tant que tableau de tableaux contenant des formules valides pour les ajouter aux cellules sélectionnées. Par exemple, si aucune autre donnée n’est remplacée, la définition de données sur [["=SUM(A1 :A5) »,"=AVERAGE(A1 :A5)"]] ajoute ces deux formules à la sélection. Comme lors de la définition d’une formule sur une cellule unique en tant que « texte », vous ne pouvez pas lire les formules ajoutées (ni les formules préexistantes) après leur définition. Vous pouvez uniquement lire les résultats des formules.

  • Un objet TableData : Un tableau avec des en-têtes est inséré. Dans Excel, si vous spécifiez des formules dans l’objet TableData que vous passez pour le paramètre de données, vous risquez de ne pas obtenir les résultats attendus en raison de la fonctionnalité « colonnes calculées » d’Excel, qui duplique automatiquement les formules dans une colonne. Pour contourner ce problème lorsque vous souhaitez écrire data des formules dans une table sélectionnée, essayez de spécifier les données sous la forme d’un tableau de tableaux (au lieu d’un objet TableData) et spécifiez coercionType comme Microsoft.Office.Matrix ou « matrice ». Toutefois, cette technique bloque la fonctionnalité de « colonnes calculées » uniquement lorsque l’une des conditions suivantes est remplie : (1) vous écrivez dans toutes les cellules de la colonne, ou (2) il existe déjà au moins deux formules différentes dans la colonne.
callback

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

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult. La propriété AsyncResult.value retourne undefined toujours, car il n’y a pas d’objet ou de données à récupérer.

Retours

void

Remarques

Ensembles de conditions requises :

Comportements propres à l’application

Les actions spécifiques à l’application suivantes s’appliquent lors de l’écriture de données dans une sélection.

Application Condition Comportement
Word S’il n’y a pas de sélection et que le point d’insertion se trouve à un emplacement valide, le spécifié data est inséré au point d’insertion Si data est une chaîne, le texte spécifié est inséré.
Si data est un tableau de tableaux (« matrice ») ou un objet TableData, une nouvelle table Word est insérée.
Si data a la valeur HTML, le code HTML spécifié est inséré. (**Important** : si l’un des fichiers HTML que vous insérez n’est pas valide, Word ne génère pas d’erreur. Word insère autant de code HTML que possible et omet toutes les données non valides).
Si data est Office Open XML, le code XML spécifié est inséré.
Si data est un flux d’image encodé en Base64, l’image spécifiée est insérée.
S’il y a une sélection Il sera remplacé par le spécifié data suivant les mêmes règles que ci-dessus.
Insérer des images Les images insérées sont placées en ligne. Les paramètres imageLeft et imageTop sont ignorés. Les proportions de l’image sont toujours verrouillées. Si seul un des paramètres imageWidth et imageHeight est donné, l’autre valeur est automatiquement redimensionnée pour conserver les proportions d’origine.
Excel Si une seule cellule est sélectionnée Si data est une chaîne, le texte spécifié est inséré comme valeur de la cellule active.
Si data est un tableau de tableaux (« matrice »), l’ensemble de lignes et de colonnes spécifié est inséré, si aucune autre donnée dans les cellules environnantes n’est remplacée.
Si data est un objet TableData, un nouveau tableau Excel avec l’ensemble spécifié de lignes et d’en-têtes est inséré, si aucune autre donnée dans les cellules environnantes ne sera remplacée.
Si plusieurs cellules sont sélectionnées Si la forme ne correspond pas à la forme de data, une erreur est retournée.
Si la forme de la sélection correspond exactement à la forme de data, les valeurs des cellules sélectionnées sont mises à jour en fonction des valeurs dans data.
Insérer des images Les images insérées sont flottantes. Les paramètres position imageLeft et imageTop sont relatifs aux cellules actuellement sélectionnées. Les valeurs imageLeft et imageTop négatives sont autorisées et éventuellement réajustées par Excel pour positionner l’image dans une feuille de calcul. Les proportions sont verrouillées à moins que les paramètres imageWidth et imageHeight soient tous deux indiqués. Si seul un des paramètres imageWidth et imageHeight est donné, l’autre valeur est automatiquement redimensionnée pour conserver les proportions d’origine.
Tous les autres cas Une erreur est retournée.
Excel sur le web En plus des comportements décrits pour Excel ci-dessus, ces limites s’appliquent lors de l’écriture de données dans Excel sur le Web Le nombre total de cellules que vous pouvez écrire dans une feuille de calcul avec le data paramètre ne peut pas dépasser 20 000 en un seul appel à cette méthode.
Le nombre de groupes de mise en forme passés au cellFormat paramètre ne peut pas dépasser 100. Un groupe de mise en forme se compose d’un ensemble de mises en forme appliquées à une plage de cellules donnée.
PowerPoint Insérer une image Les images insérées sont flottantes. Les paramètres position imageLeft et imageTop sont facultatifs, mais s’ils sont fournis, les deux doivent être présents. Si une seule valeur est indiquée, elle sera ignorée. Les valeurs imageLeft et imageTop négatives sont autorisées et peuvent positionner une image en dehors d’une diapositive. Si aucun paramètre facultatif n’est indiqué et qu’une diapositive présente un espace réservé, l’image remplacera l’espace réservé dans la diapositive. Les proportions de l’image seront verrouillées, sauf si les paramètres imageWidth et imageHeight sont tous deux indiqués. Si seul un des paramètres imageWidth et imageHeight est donné, l’autre valeur est automatiquement redimensionnée pour conserver les proportions d’origine.

Applications

Les valeurs possibles pour le paramètre Office.CoercionType varient selon l’application Office.

CoercionType Applications prises en charge
Office.CoercionType.Html
  • Word
Office.CoercionType.Matrix (tableau de tableaux)
  • Excel
  • Word
Office.CoercionType.Ooxml (Office Open XML)
  • Word
Office.CoercionType.SlideRange
  • PowerPoint sur le web et sur Windows
Office.CoercionType.Table (Objet TableData)
  • Excel
  • Word
Office.CoercionType.Text (chaîne)
  • Excel
  • PowerPoint
  • Project
  • Word
Office.CoercionType.XmlSvg
  • Excel sur Windows et sur Mac
  • PowerPoint sur le web, sur Windows et sur Mac
  • Word sur Windows et sur Mac

setTaskFieldAsync(taskId, fieldId, fieldValue, options, callback)

Documents de projet uniquement. Définissez le champ de tâche pour l’ID de tâche spécifié.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

setTaskFieldAsync(taskId: string, fieldId: number, fieldValue: string | number | boolean | object, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Paramètres

taskId

string

Chaîne ou valeur de l’ID de tâche.

fieldId

number

Champs de tâche.

fieldValue

string | number | boolean | object

Valeur du champ cible.

options
Office.AsyncContextOptions

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

callback

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

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

Retours

void

setTaskFieldAsync(taskId, fieldId, fieldValue, callback)

Documents de projet uniquement. Définissez le champ de tâche pour l’ID de tâche spécifié.

Important : cette API fonctionne uniquement dans Project sur le bureau Windows.

setTaskFieldAsync(taskId: string, fieldId: number, fieldValue: string | number | boolean | object, callback?: (result: AsyncResult<void>) => void): void;

Paramètres

taskId

string

Chaîne ou valeur de l’ID de tâche.

fieldId

number

Champs de tâche.

fieldValue

string | number | boolean | object

Valeur du champ cible.

callback

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

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

Retours

void

Exemples

// The following code example calls getSelectedTaskAsync to get the GUID of the task that's
// currently selected in a task view. Then it sets two task field values by calling
// setTaskFieldAsync recursively.
// The getSelectedTaskAsync method used in the example requires that a task view
// (for example, Task Usage) is the active view and that a task is selected. See the
// addHandlerAsync method for an example that activates a button based on the active view type.
// The example assumes your add-in has a reference to the jQuery library and that the
// following page controls are defined in the content div in the page body:
// <input id="set-info" type="button" value="Set info" /><br />
// <span id="message"></span>

(function () {
    "use strict";

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason) {
        $(document).ready(function () {
            
            // After the DOM is loaded, add-in-specific code can run.
            app.initialize();
            $('#set-info').on("click", setTaskInfo);
        });
    };

    // Get the GUID of the task, and then get the task fields.
    function setTaskInfo() {
        getTaskGuid().then(
            function (data) {
                setTaskFields(data);
            }
        );
    }

    // Get the GUID of the selected task.
    function getTaskGuid() {
        const defer = $.Deferred();
        Office.context.document.getSelectedTaskAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    defer.resolve(result.value);
                }
            }
        );
        return defer.promise();
    }

    // Set the specified fields for the selected task.
    function setTaskFields(taskGuid) {
        const targetFields = [Office.ProjectTaskFields.Active, Office.ProjectTaskFields.Notes];
        const fieldValues = [true, 'Notes for the task.'];

        // Set the field value. If the call is successful, set the next field.
        for (let i = 0; i < targetFields.length; i++) {
            Office.context.document.setTaskFieldAsync(
                taskGuid,
                targetFields[i],
                fieldValues[i],
                function (result) {
                    if (result.status === Office.AsyncResultStatus.Succeeded) {
                        i++;
                    }
                    else {
                        onError(result.error);
                    }
                }
            );
        }
        $('#message').html('Field values set');
    }

    function onError(error) {
        app.showNotification(error.name + ' ' + error.code + ': ' + error.message);
    }
})();