Office.Context interface

パッケージ:

office

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

注釈

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

プロパティ

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

プロパティの詳細

auth

注意

この API は開発者向けにプレビューとして提供されており、寄せられたフィードバックにもとづいて変更される場合があります。 この API は運用環境で使用しないでください。

サインインしているユーザーに情報を提供して、アクセスを許可します。

auth: Auth;

プロパティ値

Office.Auth

commerceAllowed

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

commerceAllowed: boolean;

プロパティ値

boolean

注釈

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

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

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

contentLanguage

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

contentLanguage: string;

プロパティ値

string

注釈

値はcontentLanguage、Office アプリケーションの [ファイル>オプション言語]で指定された [編集言語]> 設定を反映します。

サポートの詳細

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

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

	Windows での Office	Web ブラウザーの Office	Office on iPad	モバイル デバイス上の Outlook	Office on Mac
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

注釈

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

値はdisplayLanguage、Office アプリケーションの [ファイル>オプション言語]> で指定されている現在の表示言語設定を反映します。

Outlook でを使用する場合、該当するモードは Compose または Read です。

サポートの詳細

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

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

	Windows での Office	Web ブラウザーの Office	Office on iPad	モバイル デバイス上の Outlook	Office on Mac
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.診断 プロパティを使用して同様の情報を取得できます。

license

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

license: string;

プロパティ値

string

mailbox

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

mailbox: Office.Mailbox;

プロパティ値

Office.Mailbox

注釈

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

適用できる Outlook モード: 新規作成または読み取り

主なプロパティ:

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

partitionKey

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

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 では、OfficeOnlineアドインが Outlook on the web または新しい Outlook on Windows (プレビュー) で実行されている場合に返されます。

requirements

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

requirements: RequirementSetSupport;

プロパティ値

Office.RequirementSetSupport

roamingSettings

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

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

roamingSettings: Office.RoamingSettings;

プロパティ値

Office.RoamingSettings

注釈

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

適用できる Outlook モード: 新規作成または読み取り

例

// 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 モード: 新規作成

例

// 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 内のコントロールの種類と要素のサイズと間隔を調整します。

ui

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

ui: UI;

プロパティ値

Office.UI

urls

注意

この API は開発者向けにプレビューとして提供されており、寄せられたフィードバックにもとづいて変更される場合があります。 この API は運用環境で使用しないでください。

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

urls: Urls;

プロパティ値

Office.Urls

注釈

[ API セット: メールボックス プレビュー ]

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

適用できる Outlook モード: 新規作成または読み取り

例

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