Partager via

Office.Context interface

  • Référence
Paquet:
office

Représente l’environnement d’exécution du complément et permet d’accéder à des objets clés de l’API. Le contexte actuel existe en tant que propriété d’Office. Il est accessible à l’aide Office.contextde .

Remarques

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

Office sur le web Office pour Windows Office sur Mac Office sur iPad Outlook sur les appareils mobiles
Exceller Pris en charge Pris en charge Pris en charge Pris en charge Non applicable
Perspective Pris en charge Pris en charge Pris en charge Pris en charge Pris en charge
PowerPoint Pris en charge Pris en charge Pris en charge Pris en charge Non applicable
Projet Non pris en charge Pris en charge Pris en charge Non pris en charge Non applicable
Word Pris en charge Pris en charge Pris en charge Pris en charge Non applicable

Propriétés

commerceAllowed

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

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

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

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

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

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

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

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

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

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.
platform

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

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.
roamingSettings

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.
sensitivityLabelsCatalog

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é.
touchEnabled

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.
ui

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.
urls

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

Détails de la propriété

commerceAllowed

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é

boolean

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

contentLanguage

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é

string

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

Office sur le web Office pour Windows Office sur Mac Office sur iPad Outlook sur les appareils mobiles
Exceller Pris en charge Pris en charge Non pris en charge Pris en charge Non applicable
Perspective Pris en charge Pris en charge Pris en charge Pris en charge Pris en charge
PowerPoint Pris en charge Pris en charge Non pris en charge Pris en charge Non applicable
Projet Non pris en charge Pris en charge Non pris en charge Non pris en charge Non applicable
Word Pris en charge Pris en charge Non pris en charge Pris en charge Non applicable

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

diagnostics

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

diagnostics: ContextInformation;

Valeur de propriété

Office.ContextInformation

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

displayLanguage

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é

string

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

Office sur le web Office pour Windows Office sur Mac Office sur iPad Outlook sur les appareils mobiles
Exceller Pris en charge Pris en charge Pris en charge Pris en charge Non applicable
Perspective Pris en charge Pris en charge Pris en charge Pris en charge Pris en charge
PowerPoint Pris en charge Pris en charge Pris en charge Pris en charge Non applicable
Projet Non pris en charge Pris en charge Pris en charge Non pris en charge Non applicable
Word Non pris en charge Pris en charge Pris en charge Pris en charge Non applicable

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

document

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é

Office.Document

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

host

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

host: HostType;

Valeur de propriété

Office.HostType

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

license

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

license: object;

Valeur de propriété

object

Exemples

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

mailbox

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

mailbox: Office.Mailbox;

Valeur de propriété

Office.Mailbox

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;

officeTheme

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

officeTheme: OfficeTheme;

Valeur de propriété

Office.OfficeTheme

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

partitionKey

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é

string

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

platform

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

platform: PlatformType;

Valeur de propriété

Office.PlatformType

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

requirements

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é

Office.RequirementSetSupport

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

roamingSettings

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é

Office.RoamingSettings

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();

sensitivityLabelsCatalog

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é

Office.SensitivityLabelsCatalog

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

touchEnabled

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é

boolean

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

ui

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é

Office.UI

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

urls

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

urls: Urls;

Valeur de propriété

Office.Urls

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]}`);