Freigeben über

Office.Context interface

  • Referenz
Paket:
office

Stellt die Laufzeitumgebung des Add-Ins dar und stellt den Zugriff auf Schlüsselobjekte der API bereit. Der aktuelle Kontext ist als Eigenschaft von Office vorhanden. Auf sie wird mithilfe von Office.contextzugegriffen.

Hinweise

Supportdetails

Weitere Informationen zu Office-Anwendungs- und Serveranforderungen finden Sie unter Anforderungen für die Ausführung von Office-Add-Ins.

Unterstützte Anwendungen nach Plattform

Office im Web Office unter Windows Office für Mac Office auf dem iPad Outlook auf mobilen Geräten
Ausstechen Unterstützt Unterstützt Unterstützt Unterstützt Nicht zutreffend
Aussicht Unterstützt Unterstützt Unterstützt Unterstützt Unterstützt
PowerPoint Unterstützt Unterstützt Unterstützt Unterstützt Nicht zutreffend
Projekt Nicht unterstützt Unterstützt Unterstützt Nicht unterstützt Nicht zutreffend
Word Unterstützt Unterstützt Unterstützt Unterstützt Nicht zutreffend

Eigenschaften

auth

Stellt Informationen und Zugriff für den angemeldeten Benutzer bereit.
commerceAllowed

True, wenn die aktuelle Plattform zulässt, dass das Add-In eine Benutzeroberfläche zum Verkaufen oder Aktualisieren anzeigt; andernfalls wird False zurückgegeben.
contentLanguage

Ruft das Gebietsschema (Sprache) für Daten ab, das vom Benutzer für die Bearbeitung des Dokuments oder Elements festgelegt wurde.
diagnostics

Ruft Informationen zur Umgebung ab, in der das Add-In ausgeführt wird.
displayLanguage

Ruft das Gebietsschema (Sprache) ab, das vom Benutzer für die Benutzeroberfläche der Office-Anwendung angegeben wurde.
document

Ruft ein Objekt ab, das das Dokument darstellt, mit dem das Inhalts- oder Aufgabenbereichs-Add-In interagiert.
host

Enthält die Office-Anwendung, in der das Add-In ausgeführt wird.
license

Ruft die Lizenzinformationen für die Office-Installation des Benutzers ab.
mailbox

Bietet Zugriff auf das Microsoft Outlook-Add-In-Objektmodell.
officeTheme

Bietet Zugriff auf die Eigenschaften für Office-Farbdesigns.
partitionKey

Ruft einen Partitionsschlüssel für den lokalen Speicher ab. Add-Ins sollten diesen Partitionsschlüssel als Teil des Speicherschlüssels verwenden, um Daten sicher zu speichern. Der Partitionsschlüssel befindet sich undefined in Umgebungen ohne Partitionierung, z. B. in den Browsersteuerelementen für Windows-Anwendungen.
platform

Stellt die Plattform bereit, auf der das Add-In ausgeführt wird.
requirements

Stellt eine Methode bereit, um zu bestimmen, welche Anforderungssätze in der aktuellen Office-Anwendung und -Plattform unterstützt werden.
roamingSettings

Ruft ein Objekt ab, das die benutzerdefinierten Einstellungen oder den Status eines Mail-Add-Ins im Postfach eines Benutzers darstellt.

Mit RoamingSettings dem -Objekt können Sie Daten für ein E-Mail-Add-In speichern und darauf zugreifen, die im Postfach eines Benutzers gespeichert sind, sodass es für dieses Add-In verfügbar ist, wenn es von einer Clientanwendung aus ausgeführt wird, die für den Zugriff auf dieses Postfach verwendet wird.
sensitivityLabelsCatalog

Ruft das -Objekt ab, um die status des Katalogs von Vertraulichkeitsbezeichnungen in Outlook zu überprüfen und alle verfügbaren Vertraulichkeitsbezeichnungen abzurufen, wenn der Katalog aktiviert ist.
touchEnabled

Gibt an, ob die Plattform und das Gerät Touchinteraktionen ermöglichen. True, wenn das Add-In auf einem Touchgerät wie einem iPad ausgeführt wird; Andernfalls false.
ui

Bietet Objekte und Methoden, die Sie zum Erstellen und Bearbeiten von Teilen der Benutzeroberfläche, z. B. Dialogfeldern, verwenden können.
urls

Ruft das -Objekt ab, um die Laufzeit-URLs eines Add-Ins abzurufen.

Details zur Eigenschaft

auth

Hinweis

Diese API wird als Vorschau für Entwickler bereitgestellt. Je nachdem, welches Feedback wir dazu erhalten, werden möglicherweise Änderungen vorgenommen. Verwenden Sie diese API nicht in einer Produktionsumgebung.

Stellt Informationen und Zugriff für den angemeldeten Benutzer bereit.

auth: Auth;

Eigenschaftswert

Office.Auth

commerceAllowed

True, wenn die aktuelle Plattform zulässt, dass das Add-In eine Benutzeroberfläche zum Verkaufen oder Aktualisieren anzeigt; andernfalls wird False zurückgegeben.

commerceAllowed: boolean;

Eigenschaftswert

boolean

Hinweise

Anwendungen: Excel, Word

commerceAllowed wird nur in Office auf dem iPad unterstützt.

Der iOS App Store unterstützt keine Apps mit Add-Ins, die Links zu zusätzlichen Zahlungssysteme bereitstellen. Office-Add-Ins, die in Office auf dem Windows-Desktop oder im Browser ausgeführt werden, lassen solche Links jedoch zu. Wenn die Benutzeroberfläche Ihres Add-Ins einen Link zu einem externen Zahlungssystem auf anderen Plattformen als iOS bereitstellt, können Sie die commerceAllowed-Eigenschaft verwenden, um zu steuern, wann dieser Link angezeigt wird.

Beispiele

// 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

Ruft das Gebietsschema (Sprache) für Daten ab, das vom Benutzer für die Bearbeitung des Dokuments oder Elements festgelegt wurde.

contentLanguage: string;

Eigenschaftswert

string

Hinweise

Der contentLanguage Wert spiegelt die Einstellung Bearbeitungssprache wider, die in der Office-Anwendung mit Der SprachefürDateioptionen>> angegeben wurde.

Supportdetails

Weitere Informationen zu Office-Anwendungs- und Serveranforderungen finden Sie unter Anforderungen für die Ausführung von Office-Add-Ins.

Unterstützte Anwendungen nach Plattform

Office im Web Office unter Windows Office für Mac Office auf dem iPad Outlook auf mobilen Geräten
Ausstechen Unterstützt Unterstützt Nicht unterstützt Unterstützt Nicht zutreffend
Aussicht Unterstützt Unterstützt Unterstützt Unterstützt Unterstützt
PowerPoint Unterstützt Unterstützt Nicht unterstützt Unterstützt Nicht zutreffend
Projekt Nicht unterstützt Unterstützt Nicht unterstützt Nicht unterstützt Nicht zutreffend
Word Unterstützt Unterstützt Nicht unterstützt Unterstützt Nicht zutreffend

Beispiele

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

Ruft Informationen zur Umgebung ab, in der das Add-In ausgeführt wird.

diagnostics: ContextInformation;

Eigenschaftswert

Office.ContextInformation

Hinweise

Wichtig: In Outlook ist diese Eigenschaft im Postfachanforderungssatz 1.5 verfügbar. Für alle Postfachanforderungssätze können Sie die Office.context.mailbox.Diagnose-Eigenschaft verwenden, um ähnliche Informationen abzurufen.

Beispiele

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

displayLanguage

Ruft das Gebietsschema (Sprache) ab, das vom Benutzer für die Benutzeroberfläche der Office-Anwendung angegeben wurde.

displayLanguage: string;

Eigenschaftswert

string

Hinweise

Der zurückgegebene Wert ist eine Zeichenfolge im RFC 1766 Language-Tagformat, z. B. en-US.

Der displayLanguage Wert spiegelt die aktuelle Einstellung für die Anzeigesprache wider, die in der Office-Anwendung mit derDateioptionensprache>> angegeben wurde.

Wenn Sie in Outlook verwenden, sind die anwendbaren Modi Compose oder Lesen.

Supportdetails

Weitere Informationen zu Office-Anwendungs- und Serveranforderungen finden Sie unter Anforderungen für die Ausführung von Office-Add-Ins.

Unterstützte Anwendungen nach Plattform

Office im Web Office unter Windows Office für Mac Office auf dem iPad Outlook auf mobilen Geräten
Ausstechen Unterstützt Unterstützt Unterstützt Unterstützt Nicht zutreffend
Aussicht Unterstützt Unterstützt Unterstützt Unterstützt Unterstützt
PowerPoint Unterstützt Unterstützt Unterstützt Unterstützt Nicht zutreffend
Projekt Nicht unterstützt Unterstützt Unterstützt Nicht unterstützt Nicht zutreffend
Word Nicht unterstützt Unterstützt Unterstützt Unterstützt Nicht zutreffend

Beispiele

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

Ruft ein Objekt ab, das das Dokument darstellt, mit dem das Inhalts- oder Aufgabenbereichs-Add-In interagiert.

document: Office.Document;

Eigenschaftswert

Office.Document

Beispiele

// 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

Enthält die Office-Anwendung, in der das Add-In ausgeführt wird.

host: HostType;

Eigenschaftswert

Office.HostType

Hinweise

Wichtig: In Outlook ist diese Eigenschaft im Postfachanforderungssatz 1.5 verfügbar. Sie können auch die Office.context.diagnostics -Eigenschaft verwenden, um die Anwendung ab Anforderungssatz 1.5 abzurufen. Für alle Postfachanforderungssätze können Sie die Office.context.mailbox.Diagnose-Eigenschaft verwenden, um ähnliche Informationen abzurufen.

Beispiele

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

Ruft die Lizenzinformationen für die Office-Installation des Benutzers ab.

license: object;

Eigenschaftswert

object

Beispiele

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

mailbox

Bietet Zugriff auf das Microsoft Outlook-Add-In-Objektmodell.

mailbox: Office.Mailbox;

Eigenschaftswert

Office.Mailbox

Hinweise

Mindestberechtigungsstufe: eingeschränkt

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtige Eigenschaften:

  • diagnostics : Stellt Diagnoseinformationen für ein Outlook-Add-In bereit.

  • item : Stellt Methoden und Eigenschaften für den Zugriff auf eine Nachricht oder einen Termin in einem Outlook-Add-In bereit.

  • userProfile : Stellt Informationen zum Benutzer in einem Outlook-Add-In bereit.

Beispiele

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

officeTheme

Bietet Zugriff auf die Eigenschaften für Office-Farbdesigns.

officeTheme: OfficeTheme;

Eigenschaftswert

Office.OfficeTheme

Beispiele

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

Ruft einen Partitionsschlüssel für den lokalen Speicher ab. Add-Ins sollten diesen Partitionsschlüssel als Teil des Speicherschlüssels verwenden, um Daten sicher zu speichern. Der Partitionsschlüssel befindet sich undefined in Umgebungen ohne Partitionierung, z. B. in den Browsersteuerelementen für Windows-Anwendungen.

partitionKey: string;

Eigenschaftswert

string

Hinweise

Weitere Informationen finden Sie im Artikel Beibehalten des Add-In-Zustands und der Einstellungen .

Beispiele

// 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

Stellt die Plattform bereit, auf der das Add-In ausgeführt wird.

platform: PlatformType;

Eigenschaftswert

Office.PlatformType

Hinweise

Wichtig:

  • In Outlook ist diese Eigenschaft im Postfachanforderungssatz 1.5 verfügbar. Sie können die Office.context.diagnostics -Eigenschaft auch verwenden, um die Plattform ab Anforderungssatz 1.5 abzurufen. Für alle Postfachanforderungssätze können Sie die Office.context.mailbox.Diagnose-Eigenschaft verwenden, um ähnliche Informationen abzurufen.

  • In Outlook wird zurückgegeben, OfficeOnline wenn ein Add-Is in Outlook im Web oder in einem neuen Outlook unter Windows ausgeführt wird.

Beispiele

// 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

Stellt eine Methode bereit, um zu bestimmen, welche Anforderungssätze in der aktuellen Office-Anwendung und -Plattform unterstützt werden.

requirements: RequirementSetSupport;

Eigenschaftswert

Office.RequirementSetSupport

Beispiele

// 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

Ruft ein Objekt ab, das die benutzerdefinierten Einstellungen oder den Status eines Mail-Add-Ins im Postfach eines Benutzers darstellt.

Mit RoamingSettings dem -Objekt können Sie Daten für ein E-Mail-Add-In speichern und darauf zugreifen, die im Postfach eines Benutzers gespeichert sind, sodass es für dieses Add-In verfügbar ist, wenn es von einer Clientanwendung aus ausgeführt wird, die für den Zugriff auf dieses Postfach verwendet wird.

roamingSettings: Office.RoamingSettings;

Eigenschaftswert

Office.RoamingSettings

Hinweise

Mindestberechtigungsstufe: eingeschränkt

Anwendbarer Outlook-Modus: Compose oder Lesen

Beispiele

// 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

Ruft das -Objekt ab, um die status des Katalogs von Vertraulichkeitsbezeichnungen in Outlook zu überprüfen und alle verfügbaren Vertraulichkeitsbezeichnungen abzurufen, wenn der Katalog aktiviert ist.

sensitivityLabelsCatalog: Office.SensitivityLabelsCatalog;

Eigenschaftswert

Office.SensitivityLabelsCatalog

Hinweise

[ API-Satz: Postfach 1.13 ]

Minimale Berechtigungsstufe: Element lesen/schreiben

Anwendbarer Outlook-Modus: Compose

Beispiele

// 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

Gibt an, ob die Plattform und das Gerät Touchinteraktionen ermöglichen. True, wenn das Add-In auf einem Touchgerät wie einem iPad ausgeführt wird; Andernfalls false.

touchEnabled: boolean;

Eigenschaftswert

boolean

Hinweise

Anwendungen: Excel, PowerPoint, Word

touchEnabled wird nur in Office auf dem iPad unterstützt.

Verwenden Sie die touchEnabled-Eigenschaft, um zu bestimmen, wann Ihr Add-In auf einem Touchgerät ausgeführt wird, und passen Sie bei Bedarf die Art der Steuerelemente sowie die Größe und den Abstand von Elementen in der Benutzeroberfläche Ihres Add-Ins an, um Touchinteraktionen zu ermöglichen.

Beispiele

// 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

Bietet Objekte und Methoden, die Sie zum Erstellen und Bearbeiten von Teilen der Benutzeroberfläche, z. B. Dialogfeldern, verwenden können.

ui: UI;

Eigenschaftswert

Office.UI

Beispiele

// 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

Ruft das -Objekt ab, um die Laufzeit-URLs eines Add-Ins abzurufen.

urls: Urls;

Eigenschaftswert

Office.Urls

Hinweise

Anwendungen: Outlook im Web und unter Windows (neue und klassische Clients)

[ API-Satz: Postfach 1.14 ]

Mindestberechtigungsstufe: eingeschränkt

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig:

  • In Outlook im Web und outlook unter Windows wird diese API in Add-Ins, die einen Aufgabenbereich implementieren, nicht unterstützt. Auf diesen Clients wird die API nur in Add-Ins unterstützt, die eine ereignisbasierte Aktivierung oder integrierte Spamberichterstattung implementieren.

  • Im klassischen Outlook unter Windows wird diese API in Add-Ins unterstützt, die einen Aufgabenbereich, eine ereignisbasierte Aktivierung oder integrierte Spamberichterstattung implementieren.

Beispiele

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