Office.Context interface

パッケージ:

office

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

注釈

サポートの詳細

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

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

	Office on the web	Office on Windows	Office on Mac	Office on iPad	モバイル デバイス上の Outlook
秀でる	サポート	サポート	サポートされている	サポート	該当なし
前途	サポート	サポート	サポート	サポート	サポートされている
PowerPoint	サポート	サポート	サポート	サポート	該当なし
プロジェクト	非サポート	サポート	サポート	非サポート	該当なし
Word	サポート	サポート	サポート	サポート	該当なし

プロパティ

commerceAllowed	True の場合、現在のプラットフォームでアドインに販売またはアップグレード用の UI を表示できます。それ以外の場合は 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	プラットフォームとデバイスでタッチ操作を許可するかどうかを指定します。 True を指定すると、iPad などのタッチ デバイスでアドインが実行されます。それ以外の場合は false。
ui	ダイアログ ボックスなどの UI コンポーネントの作成や操作に使用できるオブジェクトとメソッドを提供します。
urls	アドインのランタイム URL を取得する オブジェクトを取得します。

プロパティの詳細

commerceAllowed

True の場合、現在のプラットフォームでアドインに販売またはアップグレード用の UI を表示できます。それ以外の場合は False を返します。

commerceAllowed: boolean;

プロパティ値

boolean

注釈

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

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

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

例

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

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

contentLanguage: string;

プロパティ値

string

注釈

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

サポートの詳細

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

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

	Office on the web	Office on Windows	Office on Mac	Office on iPad	モバイル デバイス上の 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

注釈

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

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

Outlook でを使用する場合、該当するモードはComposeまたは読み取りになります。

サポートの詳細

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

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

	Office on the web	Office on Windows	Office on Mac	Office on iPad	モバイル デバイス上の 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 アドインのユーザーに関する情報を提供します。

例

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

例

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

注釈

最小アクセス許可レベル: 制限あり

適用できる 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

プラットフォームとデバイスでタッチ操作を許可するかどうかを指定します。 True を指定すると、iPad などのタッチ デバイスでアドインが実行されます。それ以外の場合は 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]}`);