Office.Context interface

"True", wenn die aktuelle Plattform zulässt, dass das Add-In eine Benutzeroberfläche für den Verkauf oder das Upgrade anzeigt; Andernfalls wird FALSE zurückgegeben.

commerceAllowed: boolean;

Eigenschaftswert

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 Verknüpfungen jedoch zu. Wenn die Benutzeroberfläche Ihres Add-Ins einen Link zu einem externen Zahlungssystem auf anderen Plattformen als iOS bereitstellen soll, können Sie die commerceAllowed-Eigenschaft verwenden, um zu steuern, wann dieser Link angezeigt wird.

Beispiele

// Detect iPad users so your add-in can switch to an iPad-specific experience.
const isTouchEnabled = Office.context.touchEnabled;
const allowCommerce = Office.context.commerceAllowed;

// On iPad, touchEnabled returns true and commerceAllowed returns false.
if (isTouchEnabled && !allowCommerce) {
        enableIPadInterface();
        hideCommerceFeatures();
}

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

contentLanguage: string;

Eigenschaftswert

Hinweise

Der contentLanguage Wert spiegelt die Einstellung "Bearbeitungssprache" wider, die in der Office-Anwendung mit "Dateioptionen>>" angegeben wurde.

Supportdetails

Weitere Informationen zu den Anforderungen an Office-Anwendungen und -Server finden Sie unter Anforderungen für die Ausführung von Office-Add-Ins.

Unterstützte Anwendungen nach Plattform

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

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

diagnostics: ContextInformation;

Eigenschaftswert

Hinweise

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

Beispiele

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

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

displayLanguage: string;

Eigenschaftswert

Hinweise

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

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

Bei Verwendung in Outlook sind die anwendbaren Modi Compose oder Read.

Supportdetails

Weitere Informationen zu den Anforderungen an Office-Anwendungen und -Server finden Sie unter Anforderungen für die Ausführung von Office-Add-Ins.

Unterstützte Anwendungen nach Plattform

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

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

document: Office.Document;

Eigenschaftswert

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

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

host: HostType;

Eigenschaftswert

Hinweise

Wichtig: In Outlook ist diese Eigenschaft ab Postfachanforderungssatz 1.5 verfügbar. Sie können die Office.context.diagnostics Eigenschaft auch 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 zu erhalten.

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

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

license: object;

Eigenschaftswert

Beispiele

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

Ermöglicht den Zugriff auf das Microsoft Outlook-Add-In-Objektmodell.

mailbox: Office.Mailbox;

Eigenschaftswert

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 über den Benutzer in einem Outlook-Add-In bereit.

Weitere Informationen zu dem Mailbox Objekt finden Sie unter Add-In-APIs für Outlook.

Beispiele

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

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

officeTheme: OfficeTheme;

Eigenschaftswert

Hinweise

Wichtig: In Outlook officeTheme wird ab Postfachanforderungssatz 1.14 unterstützt. Es wird in Outlook-Add-Ins, die eine ereignisbasierte Aktivierung implementieren, nicht unterstützt.

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

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 Browsersteuerungen für Windows-Anwendungen.

partitionKey: string;

Eigenschaftswert

Hinweise

Weitere Informationen finden Sie im Artikel "Add-In-Status und -Einstellungen beibehalten ".

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

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

platform: PlatformType;

Eigenschaftswert

Hinweise

Wichtig:

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

• Wird in Outlook zurückgegeben, OfficeOnline wenn ein Add-Is in Outlook im Web oder im 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);
        });
}

Stellt eine Methode zum Bestimmen der Anforderungssätze bereit, die in der aktuellen Office-Anwendung und -Plattform unterstützt werden.

requirements: RequirementSetSupport;

Eigenschaftswert

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

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

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

roamingSettings: Office.RoamingSettings;

Eigenschaftswert

Hinweise

API-Satz: Postfach 1.1

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

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

sensitivityLabelsCatalog: Office.SensitivityLabelsCatalog;

Eigenschaftswert

Hinweise

API-Satz: Mailbox 1.13

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

Gibt an, ob die Plattform und das Gerät Touchinteraktionen zulassen. "True", wenn das Add-In auf einem Gerät mit Toucheingabe ausgeführt wird, z. B. einem iPad; andernfalls "false".

touchEnabled: boolean;

Eigenschaftswert

Hinweise

Anwendungen: Excel, PowerPoint, Word

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

Verwenden Sie die touchEnabled-Eigenschaft, um zu bestimmen, wann das Add-In auf einem Touchgerät ausgeführt wird, und passen Sie ggf. die Art der Steuerelemente sowie Größe und 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.
}

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

ui: UI;

Eigenschaftswert

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

Ruft das Objekt zum Abrufen der Laufzeit-URLs eines Add-Ins ab.

urls: Urls;

Eigenschaftswert

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