Office.Context interface

Fournit des informations et l’accès à l’utilisateur connecté.

auth: Auth;

Valeur de propriété

True, si la plateforme actuelle permet au complément d’afficher une interface utilisateur pour la vente ou la mise à niveau ; Sinon, retourne False.

commerceAllowed: boolean;

Valeur de propriété

Remarques

Applications : Excel, Word

commerceAllowed est uniquement pris en charge dans Office sur iPad.

L’App Store iOS ne prend pas en charge les applications avec des compléments qui indiquent des liens vers d’autres systèmes de paiement. Toutefois, les compléments Office exécutés dans Office sur le bureau Windows ou dans le navigateur autorisent ces liens. Si vous souhaitez que l’interface utilisateur de votre complément fournisse un lien vers un système de paiement externe sur des plateformes autres qu’iOS, vous pouvez utiliser la propriété commerceAllowed pour contrôler quand ce lien est affiché.

Exemples

// Check if the add-in is running on an iPad.
const allowCommerce = Office.context.commerceAllowed;
const isTouchEnabled = Office.context.touchEnabled;
if (!allowCommerce && isTouchEnabled) {
    // Add-in is running on an iPad.
    // Do something.
}

Obtient les paramètres régionaux (langue) spécifiés par l’utilisateur pour la modification du document ou de l’élément.

contentLanguage: string;

Valeur de propriété

Remarques

La contentLanguage valeur reflète le paramètre Langue d’édition spécifié avecLa langue desoptions> de fichier> dans l’application Office.

Détails concernant le support

Pour plus d’informations sur la configuration requise des serveurs et des applications Office, voir Configuration requise pour l’exécution des compléments Office.

Applications prises en charge, par plateforme

Exemples

function sayHelloWithContentLanguage() {
    const myContentLanguage = Office.context.contentLanguage;
    switch (myContentLanguage) {
        case 'en-US':
            write('Hello!');
            break;
        case 'en-NZ':
            write('G\'day mate!');
            break;
    }
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

Obtient des informations sur l’environnement dans lequel le complément s’exécute.

diagnostics: ContextInformation;

Valeur de propriété

Remarques

Important : dans Outlook, cette propriété est disponible à partir de l’ensemble de conditions requises de boîte aux lettres 1.5. Pour tous les ensembles de conditions requises de boîte aux lettres, vous pouvez utiliser la propriété Office.context.mailbox.diagnostics pour obtenir des informations similaires.

Exemples

const contextInfo = Office.context.diagnostics;
console.log("Office application: " + contextInfo.host);
console.log("Office version: " + contextInfo.version);
console.log("Platform: " + contextInfo.platform);

Obtient les paramètres régionaux (langue) spécifiés par l’utilisateur pour l’interface utilisateur de l’application Office.

displayLanguage: string;

Valeur de propriété

Remarques

La valeur retournée est une chaîne au format de balise de langage RFC 1766, par exemple en-US.

La displayLanguage valeur reflète le paramètre Langue d’affichage actuel spécifié avec Lalangue desoptions> de fichier> dans l’application Office.

Lors de l’utilisation dans Outlook, les modes applicables sont Compose ou Lecture.

Détails concernant le support

Pour plus d’informations sur la configuration requise des serveurs et des applications Office, voir Configuration requise pour l’exécution des compléments Office.

Applications prises en charge, par plateforme

Exemples

function sayHelloWithDisplayLanguage() {
    const myDisplayLanguage = Office.context.displayLanguage;
    switch (myDisplayLanguage) {
        case 'en-US':
            write('Hello!');
            break;
        case 'en-NZ':
            write('G\'day mate!');
            break;
    }
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

Obtient un objet qui représente le document avec lequel le complément de contenu ou de volet de tâches interagit.

document: Office.Document;

Valeur de propriété

Exemples

// Extension initialization code.
let _document;

// The initialize function is required for all add-ins.
Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
    // After the DOM is loaded, code specific to the add-in can run.
    // Initialize instance variables to access API objects.
    _document = Office.context.document;
    });
}

Contient l’application Office dans laquelle le complément est en cours d’exécution.

host: HostType;

Valeur de propriété

Remarques

Important : dans Outlook, cette propriété est disponible à partir de l’ensemble de conditions requises de boîte aux lettres 1.5. Vous pouvez également utiliser la Office.context.diagnostics propriété pour obtenir l’application à partir de l’ensemble de conditions requises 1.5. Pour tous les ensembles de conditions requises de boîte aux lettres, vous pouvez utiliser la propriété Office.context.mailbox.diagnostics pour obtenir des informations similaires.

Exemples

const host = Office.context.host;
if (host === Office.HostType.Excel || host === Office.HostType.PowerPoint || host === Office.HostType.Word) {
    // Do something.
} else if (host === Office.HostType.Outlook) {
    // Do something.
}

Obtient les informations de licence pour l’installation d’Office de l’utilisateur.

license: object;

Valeur de propriété

Exemples

const license = Office.context.license;
console.log(`Office license: ${license}`);

Fournit l’accès au modèle objet de complément Microsoft Outlook.

mailbox: Office.Mailbox;

Valeur de propriété

Remarques

Niveau d’autorisation minimal : restreint

Mode Outlook applicable : Rédiger ou Lire

Propriétés de clé :

• diagnostics : fournit des informations de diagnostic à un complément Outlook.

• item : fournit des méthodes et des propriétés pour accéder à un message ou à un rendez-vous dans un complément Outlook.

• userProfile : fournit des informations sur l’utilisateur dans un complément Outlook.

Exemples

// The following line of code access the item object of the JavaScript API for Office.
const item = Office.context.mailbox.item;

Permet d’accéder aux propriétés pour les couleurs du thème Office.

officeTheme: OfficeTheme;

Valeur de propriété

Exemples

function applyOfficeTheme() {
    // Identify the current Office theme in use.
    const currentOfficeTheme = Office.context.officeTheme.themeId;

    if (currentOfficeTheme === Office.ThemeId.Colorful || currentOfficeTheme === Office.ThemeId.White) {
        console.log("No changes required.");
    }

    // Get the colors of the current Office theme.
    const bodyBackgroundColor = Office.context.officeTheme.bodyBackgroundColor;
    const bodyForegroundColor = Office.context.officeTheme.bodyForegroundColor;
    const controlBackgroundColor = Office.context.officeTheme.controlBackgroundColor;
    const controlForegroundColor = Office.context.officeTheme.controlForegroundColor;

    // Apply theme colors to a CSS class.
    $("body").css("background-color", bodyBackgroundColor);

    if (Office.context.officeTheme.isDarkTheme()) {
        $("h1").css("color", controlForegroundColor);
    }
}

Obtient une clé de partition pour le stockage local. Les compléments doivent utiliser cette clé de partition dans le cadre de la clé de stockage pour stocker les données en toute sécurité. La clé de partition se trouve undefined dans des environnements sans partitionnement, tels que les contrôles de navigateur pour les applications Windows.

partitionKey: string;

Valeur de propriété

Remarques

Pour plus d’informations, consultez l’article Conserver l’état et les paramètres du complément .

Exemples

// Store the value "Hello" in local storage with the key "myKey1".
setInLocalStorage("myKey1", "Hello");

// ... 

// Retrieve the value stored in local storage under the key "myKey1".
const message = getFromLocalStorage("myKey1");
console.log(message);

// ...

function setInLocalStorage(key: string, value: string) {
    const myPartitionKey = Office.context.partitionKey;

    // Check if local storage is partitioned. 
    // If so, use the partition to ensure the data is only accessible by your add-in.
    if (myPartitionKey) {
        localStorage.setItem(myPartitionKey + key, value);
    } else {
        localStorage.setItem(key, value);
    }
}

function getFromLocalStorage(key: string) {
    const myPartitionKey = Office.context.partitionKey;

    // Check if local storage is partitioned.
    if (myPartitionKey) {
        return localStorage.getItem(myPartitionKey + key);
    } else {
        return localStorage.getItem(key);
    }
}

Fournit la plateforme sur laquelle le complément s’exécute.

platform: PlatformType;

Valeur de propriété

Remarques

Important:

• Dans Outlook, cette propriété est disponible à partir de l’ensemble de conditions requises de boîte aux lettres 1.5. Vous pouvez également utiliser la Office.context.diagnostics propriété pour obtenir la plateforme à partir de l’ensemble de conditions requises 1.5. Pour tous les ensembles de conditions requises de boîte aux lettres, vous pouvez utiliser la propriété Office.context.mailbox.diagnostics pour obtenir des informations similaires.

• Dans Outlook, OfficeOnline est retourné si un complément est en cours d’exécution dans Outlook sur le web ou dans un nouvel Outlook sur Windows.

Exemples

// Request permission from a user to access their devices from Office on the web.
if (Office.context.platform === Office.PlatformType.OfficeOnline) {
    const deviceCapabilities = [
        Office.DevicePermissionType.camera,
        Office.DevicePermissionType.microphone
    ];
    Office.devicePermission
        .requestPermissions(deviceCapabilities)
        .then((isGranted) => {
            if (isGranted) {
                // Do something with device capabilities.
            }
        })
        .catch((error) => {
            console.log("Permission denied.");
            console.error(error);
        });
}

Fournit une méthode permettant de déterminer quels ensembles de conditions requises sont pris en charge sur l’application et la plateforme Office actuelles.

requirements: RequirementSetSupport;

Valeur de propriété

Exemples

// To use the setCellProperties API, check if ExcelApi 1.9 is supported.
if (Office.context.requirements.isSetSupported("ExcelApi", "1.9")) {
    const cellProperties: Excel.SettableCellProperties[][] =
    colors2D.map(row =>
        row.map(color =>
            ({
                format: {
                    fill: {
                        color: color
                    }
                }
            })
        )
    );
    sheet.getRangeByIndexes(1, 1, originalSize, originalSize).setCellProperties(cellProperties);
}
...

Obtient un objet qui représente les paramètres personnalisés ou l’état d’un complément de messagerie enregistrés dans la boîte aux lettres d’un utilisateur.

L’objet RoamingSettings vous permet de stocker et d’accéder aux données d’un complément de messagerie stocké dans la boîte aux lettres d’un utilisateur. Il est donc disponible pour ce complément lorsqu’il s’exécute à partir de n’importe quelle application cliente utilisée pour accéder à cette boîte aux lettres.

roamingSettings: Office.RoamingSettings;

Valeur de propriété

Remarques

Niveau d’autorisation minimal : restreint

Mode Outlook applicable : Rédiger ou Lire

Exemples

// Get the current value of the 'myKey' setting.
const value = Office.context.roamingSettings.get('myKey');
// Update the value of the 'myKey' setting.
Office.context.roamingSettings.set('myKey', 'Hello World!');
// Persist the change.
Office.context.roamingSettings.saveAsync();

Obtient l’objet pour case activée la status du catalogue d’étiquettes de confidentialité dans Outlook et récupérer toutes les étiquettes de confidentialité disponibles si le catalogue est activé.

sensitivityLabelsCatalog: Office.SensitivityLabelsCatalog;

Valeur de propriété

Remarques

[ Ensemble d’API : Boîte aux lettres 1.13 ]

Niveau d’autorisation minimal : élément en lecture/écriture

Mode Outlook applicable : Compose

Exemples

// Check if the catalog of sensitivity labels is enabled on the current mailbox.
Office.context.sensitivityLabelsCatalog.getIsEnabledAsync((asyncResult) => {
    // If the catalog is enabled, get all available sensitivity labels.
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value == true) {
        Office.context.sensitivityLabelsCatalog.getAsync((asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                const catalog = asyncResult.value;
                console.log("Sensitivity Labels Catalog:");
                console.log(JSON.stringify(catalog));
            } else {
                console.log("Action failed with error: " + asyncResult.error.message);
            }
        });
    } else {
        console.log("Action failed with error: " + asyncResult.error.message);
    }
});

Spécifie si la plateforme et l’appareil autorisent l’interaction tactile. True si le complément s’exécute sur un appareil tactile, tel qu’un iPad ; false dans le cas contraire.

touchEnabled: boolean;

Valeur de propriété

Remarques

Applications : Excel, PowerPoint, Word

touchEnabled est uniquement pris en charge dans Office sur iPad.

Utilisez la propriété touchEnabled pour déterminer quand votre complément s’exécute sur un appareil tactile et, si nécessaire, ajustez le type de contrôles, ainsi que la taille et l’espacement des éléments dans l’interface utilisateur de votre complément pour prendre en charge les interactions tactiles.

Exemples

// Check if the add-in is running on an iPad.
const allowCommerce = Office.context.commerceAllowed;
const isTouchEnabled = Office.context.touchEnabled;
if (!allowCommerce && isTouchEnabled) {
    // Add-in is running on an iPad.
    // Do something.
}

Fournit des objets et des méthodes permettant de créer et de manipuler des composants d’interface utilisateur, comme les boîtes de dialogue.

ui: UI;

Valeur de propriété

Exemples

// Open a dialog and register an event handler.
Office.context.ui.displayDialogAsync(
    "https://www.contoso.com/myDialog.html",
    { height: 30, width: 20 },
    (asyncResult) => {
        const dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg) => {
            dialog.close();
            processMessage(arg);
        });
    }
);

Obtient l’objet pour récupérer les URL d’exécution d’un complément.

urls: Urls;

Valeur de propriété

Remarques

Applications : Outlook sur le web et sur Windows (clients nouveaux et classiques)

[ Ensemble d’API : Boîte aux lettres 1.14 ]

Niveau d’autorisation minimal : restreint

Mode Outlook applicable : Rédiger ou Lire

Important:

• Dans Outlook sur le web et outlook sur Windows, cette API n’est pas prise en charge dans les compléments qui implémentent un volet Office. Sur ces clients, l’API n’est prise en charge que dans les compléments qui implémentent l’activation basée sur les événements ou la création de rapports de courrier indésirable intégrés.

• Dans Outlook sur Windows classique, cette API est prise en charge dans les compléments qui implémentent un volet Office, une activation basée sur des événements ou un rapport de courrier indésirable intégré.

Exemples

// Get the value of the first parameter of the JavaScript runtime URL.
// For example, if the URL is https://wwww.contoso.com/training?key1=value1&key2=value2,
// the following function logs "First parameter value: value1" to the console.
const url = Office.context.urls.javascriptRuntimeUrl;
const regex = /=([^&]+)/;
console.log(`First parameter value: ${url.match(regex)[1]}`);