Office.Context interface

パッケージ:

office

アドインのランタイム環境を表し、API の主要なオブジェクトへのアクセスを提供します。 現在のコンテキストは、Office のプロパティとして存在します。 Office.context を使用してアクセスします。

注釈

サポートの詳細

Office アプリケーションとサーバーの要件の詳細については、「Office アドインを実行するための要件」を参照してください。

サポートされているアプリケーション (プラットフォーム別)

	Office on the web	Office on Windows	Office on Mac	Office on iPad	モバイル デバイスでの Outlook
Excel	サポート	サポート	サポート	サポート	該当なし
Outlook	サポート	サポート	サポート	サポート	サポート
PowerPoint	サポート	サポート	サポート	サポート	該当なし
プロジェクト	非サポート	サポート	サポート	サポート対象外	該当なし
Word	サポート	サポート	サポート	サポート	該当なし

例

// Get the Office host, version, and platform in which the add-in is running.
const contextInfo = Office.context.diagnostics;
console.log("Office application: " + contextInfo.host);
console.log("Office version: " + contextInfo.version);
console.log("Platform: " + contextInfo.platform);

プロパティ

commerceAllowed	現在のプラットフォームでアドインが販売またはアップグレードのための UI を表示できる場合は true。それ以外の場合は False が返されます。
contentLanguage	ドキュメントまたはアイテムを編集するためにユーザーによって指定されるロケール (言語) を取得します。
diagnostics	アドインが実行されている環境に関する情報を取得します。
displayLanguage	Office アプリケーションの UI に対してユーザーが指定したロケール (言語) を取得します。
document	コンテンツ アドインまたは作業ウィンドウ アドインによって操作するドキュメントを表すオブジェクトを取得します。
host	アドインが実行されている Office アプリケーションが含まれます。
license	ユーザーの Office インストールのライセンス情報を取得します。
mailbox	Microsoft Outlook アドイン オブジェクト モデルへのアクセスを提供します。
officeTheme	Office テーマの色のプロパティにアクセスできるようにします。
partitionKey	ローカル ストレージのパーティション キーを取得します。 アドインは、データを安全に格納するためのストレージ キーの一部として、このパーティション キーを使用する必要があります。 パーティション キーは、Windows アプリケーションのブラウザー コントロールなど、パーティション分割のない環境で undefined されます。
platform	アドインが実行されるプラットフォームを提供します。
requirements	現在の Office アプリケーションおよびプラットフォームでサポートされている要件セットを決定するための方法を提供します。
roamingSettings	ユーザーのメールボックスに保存されている、メール アドインのカスタム設定や状態を表すオブジェクトを取得します。 RoamingSettings オブジェクトを使用すると、ユーザーのメールボックスに保存されているメール アドインのデータを保存してアクセスできるため、そのメールボックスへのアクセスに使用されるクライアント アプリケーションから実行されているときに、そのアドインが使用できます。
sensitivityLabelsCatalog	オブジェクトを取得して、Outlook の秘密度ラベルのカタログの状態をチェックし、カタログが有効になっている場合は使用可能なすべての秘密度ラベルを取得します。
touchEnabled	プラットフォームとデバイスでタッチ操作を許可するかどうかを指定します。 アドインが iPad などのタッチ デバイスで実行されている場合は true。それ以外の場合は false。
ui	ダイアログ ボックスなどの UI コンポーネントの作成や操作に使用できるオブジェクトとメソッドを提供します。
urls	オブジェクトを取得して、アドインのランタイム URL を取得します。

プロパティの詳細

commerceAllowed

現在のプラットフォームでアドインが販売またはアップグレードのための UI を表示できる場合は true。それ以外の場合は False が返されます。

commerceAllowed: boolean;

プロパティ値

boolean

注釈

アプリケーション: Excel、Word

commerceAllowed iPad 上の Office でのみサポートされます。

iOS アプリ ストアでは、追加の支払いシステムへのリンクを提供するアドインを含むアプリをサポートしません。 ただし、Windows デスクトップ上の Office、またはブラウザーで実行されている Office アドインでは、このようなリンクが許可されます。 アドインの UI で iOS 以外のプラットフォーム上の外部支払いシステムへのリンクを提供する場合は、commerceAllowed プロパティを使用して、そのリンクを表示するタイミングを制御できます。

例

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

contentLanguage

ドキュメントまたはアイテムを編集するためにユーザーによって指定されるロケール (言語) を取得します。

contentLanguage: string;

プロパティ値

string

注釈

contentLanguage値は、Office アプリケーションの File>Options>Language で指定された編集言語設定を反映します。

サポートの詳細

Office アプリケーションとサーバーの要件の詳細については、「Office アドインを実行するための要件」を参照してください。

サポートされているアプリケーション (プラットフォーム別)

	Office on the web	Office on Windows	Office on Mac	Office on iPad	モバイル デバイスでの Outlook
Excel	サポート	サポート	非サポート	サポート	該当なし
Outlook	サポート	サポート	サポート	サポート	サポート
PowerPoint	サポート	サポート	非サポート	サポート	該当なし
プロジェクト	非サポート	サポート	サポート対象外	サポート対象外	該当なし
Word	サポート	サポート	非サポート	サポート	該当なし

例

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

アドインが実行されている環境に関する情報を取得します。

diagnostics: ContextInformation;

プロパティ値

Office.ContextInformation

注釈

重要: Outlook では、このプロパティはメールボックス要件セット 1.5 以降で使用できます。 すべてのメールボックス要件セットについて、Office.context.mailbox.診断プロパティを使用して同様の情報を取得できます。

例

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

displayLanguage

Office アプリケーションの UI に対してユーザーが指定したロケール (言語) を取得します。

displayLanguage: string;

プロパティ値

string

注釈

返される値は、RFC 1766 言語タグ形式の文字列 (en-US など) です。

displayLanguage値は、Office アプリケーションの File>Options>Language で指定されている現在の表示言語設定を反映します。

Outlook で使用する場合、適用可能なモードは Compose または Read です。

サポートの詳細

Office アプリケーションとサーバーの要件の詳細については、「Office アドインを実行するための要件」を参照してください。

サポートされているアプリケーション (プラットフォーム別)

	Office on the web	Office on Windows	Office on Mac	Office on iPad	モバイル デバイスでの Outlook
Excel	サポート	サポート	サポート	サポート	該当なし
Outlook	サポート	サポート	サポート	サポート	サポート
PowerPoint	サポート	サポート	サポート	サポート	該当なし
プロジェクト	非サポート	サポート	サポート	サポート対象外	該当なし
Word	非サポート	サポート	サポート	サポート	該当なし

例

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

コンテンツ アドインまたは作業ウィンドウ アドインによって操作するドキュメントを表すオブジェクトを取得します。

document: Office.Document;

プロパティ値

Office.Document

例

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

アドインが実行されている Office アプリケーションが含まれます。

host: HostType;

プロパティ値

Office.HostType

注釈

重要: Outlook では、このプロパティはメールボックス要件セット 1.5 以降で使用できます。 Office.context.diagnostics プロパティを使用して、要件セット 1.5 で始まるアプリケーションを取得することもできます。 すべてのメールボックス要件セットについて、Office.context.mailbox.診断プロパティを使用して同様の情報を取得できます。

例

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

ユーザーの Office インストールのライセンス情報を取得します。

license: object;

プロパティ値

object

例

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

mailbox

Microsoft Outlook アドイン オブジェクト モデルへのアクセスを提供します。

mailbox: Office.Mailbox;

プロパティ値

Office.Mailbox

注釈

最小アクセス許可レベル: 制限付き

適用可能な Outlook モード: Composeまたは読み取り

主なプロパティ:

• diagnostics : Outlook アドインに診断情報を提供します。

• item : Outlook アドインのメッセージまたは予定にアクセスするためのメソッドおよびプロパティを提供します。

• userProfile : Outlook アドインでユーザーに関する情報を提供します。

Mailbox オブジェクトの詳細については、「Outlook アドイン API」を参照してください。

例

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

officeTheme

Office テーマの色のプロパティにアクセスできるようにします。

officeTheme: OfficeTheme;

プロパティ値

Office.OfficeTheme

注釈

重要: Outlook では、メールボックス要件セット 1.14 以降、officeTheme がサポートされています。 イベント ベースのライセンス認証を実装する Outlook アドインではサポートされていません。

例

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

ローカル ストレージのパーティション キーを取得します。 アドインは、データを安全に格納するためのストレージ キーの一部として、このパーティション キーを使用する必要があります。 パーティション キーは、Windows アプリケーションのブラウザー コントロールなど、パーティション分割のない環境で undefined されます。

partitionKey: string;

プロパティ値

string

注釈

詳しくは、「 アドインの状態と設定を保持する」 をご覧ください。

例

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

アドインが実行されるプラットフォームを提供します。

platform: PlatformType;

プロパティ値

Office.PlatformType

注釈

重要:

• Outlook では、このプロパティはメールボックス要件セット 1.5 以降で使用できます。 Office.context.diagnostics プロパティを使用して、要件セット 1.5 から始まるプラットフォームを取得することもできます。 すべてのメールボックス要件セットについて、Office.context.mailbox.診断プロパティを使用して同様の情報を取得できます。

• Outlook では、Outlook on the web または新しい Outlook on Windows でアドイ ソフトウェアが実行されている場合、OfficeOnline が返されます。

例

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

現在の Office アプリケーションおよびプラットフォームでサポートされている要件セットを決定するための方法を提供します。

requirements: RequirementSetSupport;

プロパティ値

Office.RequirementSetSupport

例

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

ユーザーのメールボックスに保存されている、メール アドインのカスタム設定や状態を表すオブジェクトを取得します。

RoamingSettings オブジェクトを使用すると、ユーザーのメールボックスに保存されているメール アドインのデータを保存してアクセスできるため、そのメールボックスへのアクセスに使用されるクライアント アプリケーションから実行されているときに、そのアドインが使用できます。

roamingSettings: Office.RoamingSettings;

プロパティ値

Office.RoamingSettings

注釈

API セット: メールボックス 1.1

最小アクセス許可レベル: 制限付き

適用可能な Outlook モード: Composeまたは読み取り

例

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

オブジェクトを取得して、Outlook の秘密度ラベルのカタログの状態をチェックし、カタログが有効になっている場合は使用可能なすべての秘密度ラベルを取得します。

sensitivityLabelsCatalog: Office.SensitivityLabelsCatalog;

プロパティ値

Office.SensitivityLabelsCatalog

注釈

API セット: メールボックス 1.13

最小アクセス許可レベル: 項目の読み取り/書き込み

適用可能な Outlook モード: Compose

例

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

プラットフォームとデバイスでタッチ操作を許可するかどうかを指定します。 アドインが iPad などのタッチ デバイスで実行されている場合は true。それ以外の場合は false。

touchEnabled: boolean;

プロパティ値

boolean

注釈

アプリケーション: Excel、PowerPoint、Word

touchEnabled iPad 上の Office でのみサポートされます。

touchEnabled プロパティを使用して、アドインがタッチ デバイスで実行されるタイミングを判断し、必要に応じて、コントロールの種類、アドイン UI の要素のサイズと間隔を調整してタッチ操作に対応します。

例

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

ダイアログ ボックスなどの UI コンポーネントの作成や操作に使用できるオブジェクトとメソッドを提供します。

ui: UI;

プロパティ値

Office.UI

例

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

オブジェクトを取得して、アドインのランタイム URL を取得します。

urls: Urls;

プロパティ値

Office.Urls

注釈

アプリケーション: Outlook on the web および Windows (新規および従来のクライアント)

API セット: メールボックス 1.14

最小アクセス許可レベル: 制限付き

適用可能な Outlook モード: Composeまたは読み取り

重要:

• Outlook on the web と新しい Outlook on Windows では、この API はタスク ウィンドウを実装するアドインではサポートされていません。 これらのクライアントでは、イベント ベースのライセンス認証または統合されたスパム報告を実装するアドインでのみ、API がサポートされます。

• 従来の Outlook on Windows では、この API は、作業ウィンドウ、イベント ベースのライセンス認証、または統合されたスパム報告を実装するアドインでサポートされます。

例

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