Office.Context interface

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

auth: Auth;

プロパティ値

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

commerceAllowed: 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: string;

プロパティ値

注釈

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

サポートの詳細

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

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

例

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

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

displayLanguage: string;

プロパティ値

注釈

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

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

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

サポートの詳細

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

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

例

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

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

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

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

license: object;

プロパティ値

例

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

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

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;

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

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

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

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

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

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

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

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

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

touchEnabled: 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;

プロパティ値

例

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

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

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