Edytuj

Udostępnij za pośrednictwem

context (Mailbox requirement set 1.14)

  • Artykuł

Office.context

Office.context provides shared interfaces that are used by add-ins in all of the Office apps. This listing documents only those interfaces that are used by Outlook add-ins. For a full listing of the Office.context namespace, see the Office.context reference in the Common API.

Requirements
Requirement Value
Minimum mailbox requirement set version 1.1
Applicable Outlook mode Compose or Read

Properties

Property Modes Return type Minimum
requirement set
auth Compose
Read		 Auth IdentityAPI 1.3
contentLanguage Compose
Read		 String 1.1
diagnostics Compose
Read		 ContextInformation 1.5
displayLanguage Compose
Read		 String 1.1
host Compose
Read		 HostType 1.5
mailbox Compose
Read		 Mailbox 1.1
platform Compose
Read		 PlatformType 1.5
requirements Compose
Read		 RequirementSetSupport 1.1
roamingSettings Compose
Read		 RoamingSettings 1.1
sensitivityLabelsCatalog Compose SensitivityLabelsCatalog 1.13
ui Compose
Read		 UI 1.1
urls Compose
Read		 UI 1.1

Property details

auth: Auth

Supports single sign-on (SSO) by providing a method that allows the Office application to obtain an access token to the add-in's web application. Indirectly, this also enables the add-in to access the signed-in user's Microsoft Graph data without requiring the user to sign in a second time.

Type
Requirements
Requirement Value
Minimum mailbox requirement set version 1.10
Applicable Outlook mode Compose or Read
Example
Office.context.auth.getAccessTokenAsync(function(result) {
    if (result.status === "succeeded") {
        var token = result.value;
        // ...
    } else {
        console.log("Error obtaining token", result.error);
    }
});

contentLanguage: String

Gets the locale (language) specified by the user for editing the item.

The contentLanguage value reflects the current Editing Language setting specified with File > Options > Language in the Office client application.

Type
  • String
Requirements
Requirement Value
Minimum mailbox requirement set version 1.1
Applicable Outlook mode Compose or Read
Example
function sayHelloWithContentLanguage() {
  var 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: ContextInformation

Gets information about the environment in which the add-in is running.

Note

For all Mailbox requirement sets, you can also use the Office.context.mailbox.diagnostics property to get similar information.

Type
Requirements
Requirement Value
Minimum mailbox requirement set version 1.5
Applicable Outlook mode Compose or Read
Example
var contextInfo = Office.context.diagnostics;
console.log("Office application: " + contextInfo.host);
console.log("Office version: " + contextInfo.version);
console.log("Platform: " + contextInfo.platform);

displayLanguage: String

Gets the locale (language) in RFC 1766 Language tag format specified by the user for the UI of the Office client application.

The displayLanguage value reflects the current Display Language setting specified with File > Options > Language in the Office client application.

Type
  • String
Requirements
Requirement Value
Minimum mailbox requirement set version 1.1
Applicable Outlook mode Compose or Read
Example
function sayHelloWithDisplayLanguage() {
  var 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;
}

host: HostType

Gets the Office application that is hosting the add-in.

Note

Alternatively, you can use the Office.context.diagnostics property to get the host. For all Mailbox requirement sets, you can also use the Office.context.mailbox.diagnostics property to get similar information.

Type
Requirements
Requirement Value
Minimum mailbox requirement set version 1.5
Applicable Outlook mode Compose or Read
Example
console.log(JSON.stringify(Office.context.host));

officeTheme: OfficeTheme

Provides access to the properties for Office theme colors.

Type
Requirements
Requirement Value
Minimum mailbox requirement set version 1.14
Applicable Outlook mode Compose or Read
Example
function applyOfficeTheme() {
    // Get office theme colors.
    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 body background color to a CSS class.
    $('.body').css('background-color', bodyBackgroundColor);
}

platform: PlatformType

Provides the platform on which the add-in is running.

Note

Alternatively, you can use the Office.context.diagnostics property to get the platform. For all Mailbox requirement sets, you can also use the Office.context.mailbox.diagnostics property to get similar information.

Type
Requirements
Requirement Value
Minimum mailbox requirement set version 1.5
Applicable Outlook mode Compose or Read
Example
console.log(JSON.stringify(Office.context.platform));

requirements: RequirementSetSupport

Provides a method for determining what requirement sets are supported on the current application and platform.

Type
Requirements
Requirement Value
Minimum mailbox requirement set version 1.1
Applicable Outlook mode Compose or Read
Example
console.log(JSON.stringify(Office.context.requirements.isSetSupported("mailbox", "1.1")));

roamingSettings: RoamingSettings

Gets an object that represents the custom settings or state of a mail add-in saved to a user's mailbox.

The RoamingSettings object lets you store and access data for a mail add-in that is stored in a user's mailbox, so that is available to that add-in when it is running from any Outlook client used to access that mailbox.

Type
Requirements
Requirement Value
Minimum mailbox requirement set version 1.1
Minimum permission level restricted
Applicable Outlook mode Compose or Read

sensitivityLabelsCatalog: SensitivityLabelsCatalog

Gets the object to check the status of the catalog of sensitivity labels in Outlook and retrieve all available sensitivity labels if the catalog is enabled.

Type
Requirements
Requirement Value
Minimum mailbox requirement set version 1.13
Minimum permission level read/write item
Applicable Outlook mode Compose

ui: UI

Provides objects and methods that you can use to create and manipulate UI components, such as dialog boxes, in your Office Add-ins.

Type
Requirements
Requirement Value
Minimum mailbox requirement set version 1.1
Applicable Outlook mode Compose or Read

urls: Urls

Provides the object to retrieve the runtime URLs of an add-in.

Type
Requirements
Requirement Value
Minimum mailbox requirement set version 1.14
Minimum permission level restricted
Applicable Outlook mode Compose or Read
Example
const url = Office.context.urls.javascriptRuntimeUrl;
const regex = /=([^&]+)/;
console.log(`First parameter value: ${url.match(regex)[1]}`);

Events

You can subscribe to and unsubscribe from the following events using addHandlerAsync and removeHandlerAsync respectively.

Event Description Minimum
requirement set
OfficeThemeChanged The Office theme in Outlook changed. Only available with task pane implementation. 1.14