[アーティクル]
08/19/2015

この記事は機械翻訳されたものです。

Microsoft Office

新しい JavaScript API for Office について調べる (機械翻訳)

この資料は、Microsoft Office の 2013 年に新しく導入されたオフィス、JavaScript API で深いルックスのシリーズで初めてです。 Office のアプリケーションに精通していることを前提とします。 MSDN ドキュメントのページではなく場合は、「Office のアプリケーションの概要」(bit.ly/12nBWHG）、の概要と、API の一般的な概要を提供します。

この記事、このシリーズで、他のない包括的な方法の固体、豊かな理解を与えるキーの側面に触れる深い API に行く Office API のアプリ。

この最初の記事では、Office オブジェクトモデルのアプリを確認します。パート 2 は、Office ファイルのコンテンツにアクセスする方法の中核作業に焦点を当てるし、イベントモデルを確認します。その 3 データバインディングの概念を検討し、カスタム XML パーツの操作の基本を確認します。最後に、第 4 シリーズにはメールのアプリを終了します。

このシリーズ全体を通して、私たちはしばしば Office API ドキュメントのアプリケーションへの参照をを。公式ドキュメント、コードサンプル、コミュニティリソースでアプリを Office と SharePoint デベロッパーセンターを検索することができます (dev.office.com)。

オフィスの JavaScript API の概要

JavaScript API のオフィスには完全なオブジェクトモデルがあります。 API は、office.js ファイル、JavaScript ファイルのセット内で含まれています。アプリケーションは、オフィスの JavaScript API を使用するには、office.js ファイルへの参照を含める必要があります。負荷をホスト環境とロケール文字列に必要なスクリプトを含むその他の必要なスクリプトはそれが動作する必要があります office.js ファイルを読み込みます。幸いにも、あなたのアプリケーションと共に office.js ファイルのコピーを展開する必要はありませんので、コンテンツ配信ネットワーク (CDN) を使用して office.js ファイルへの参照を追加できます。その例を次に示します。

<!-- When deploying an app, you should always
  load the CDN version of the office.js file.
-->
<script src=
  "https://appsforoffice.microsoft.com/lib/1.0/hosted/office.js">
</script>

オブジェクトモデルは、いくつかの目標の周り設計されました。

「一度、どこにでも実行」それは拡張する必要がある-特定のホストアプリケーションに関連付けられていないが、複数のホストアプリケーションで利用できる機能を中心に構築します。アプリケーションホスト固有の機能を一貫した方法でアクセスします。
クロスプラットフォーム。互換性高もこのリストにランク。したがって、オブジェクトモデルは、特定のバージョンの Office に接続されていません。同様に、同じコードは、Office クライアントアプリケーションの Web アプリケーションバージョンですサポートされている場合。たとえば、Excel のアプリケーション Excel の Web アプリケーションにだけでなく Excel クライアントアプリケーションと同様に操作できます。
パフォーマンスとセキュリティ。アプリケーションは、できるだけユーザーに目障りなことができるようにパフォーマンスの最大化に必要な。また、JavaScript API ドキュメントのコンテンツを直接 Office アプリケーションを自動化することなくが、対話に安定性とセキュリティソリューションの向上設計されました。

JavaScript API の別主要な目標は、Office プラットフォーム Web 開発者を引き付けるためにだった。したがって、オブジェクトモデルは、意識のプログラミング、モダンな Web を構築されました。 JavaScript API のオフィスと組み合わせてアプリケーションを作成するときは、あなたの現在のスキルや知識の jQuery などの他の JavaScript ライブラリを活用できます。

非同期プログラミングパターン

述べたように、パフォーマンスは Office API のアプリの設計に重要な目標でした。デザイナーが、API のパフォーマンス強化された方法の 1 つの非同期関数の多用をだった。

非同期関数の使用は、関数を返すには時間がかかる場合、アプリケーションの実行中にブロックできます。非同期関数が呼び出されますが、プログラムの実行は、関数が返すを待機しません。非同期関数の実行中に、それが継続されます。これは、アプリケーションも動作している間、Office ドキュメントを使用する続行できます。

Office のこのセクションで取り上げた API は、アプリケーションで非同期のデザインを理解するためいくつか重要なポイントです。

Office API のアプリケーションで非同期機能の一般的な署名
非同期関数の省略可能なパラメーターの使用
AsyncResult オブジェクトに非同期関数の役割

私たちは順番にそれぞれについて説明します。

Office API のアプリケーションで非同期機能の一般的な署名 Office API のアプリ内のすべての非同期機能は、同じ名前付け規則と同じ基本的な署名があります。すべての非同期関数名"Async"では、たとえば、このような終了します。Document.getSelectedDataAsync。

すべての非同期関数のシグネチャは、次の基本的なパターンに準拠します。

functionNameAsync(
    requiredParameters,
    [, options], [callback]);

必要なパラメーターは、他の 2 つのパラメーターによって行われます。省略可能なパラメーターとどちらの常に省略可能なコールバック関数を保持するオブジェクト。

非同期関数の省略可能なパラメーター 非同期関数のシグネチャで任意の JavaScript オブジェクトは、キーパラメーターの名前ですあり、値は、このパラメーターに使用するデータですがコロンで区切られたキーと値のペアのコレクションです。パラメーター名が正しい限り、キー/値ペアの順序は関係ありません。 MSDN ドキュメントの各非同期関数パラメーターオプションオブジェクトでその特定の関数を使用するための詳細します。

たとえば、Document.setSelectedDataAsync メソッドは同じ基本的な署名をすべての非同期関数に共通のアプリのためのオフィスがあります。

Office.context.document.setSelectedDataAsync(
  data [, options], callback);

すべての非同期関数 API では、Document.set のようなSelectedDataAsync が省略可能なパラメーターを保持するオプションオブジェクトがデータを設定するこの関数のポイントであるため、オプションのオブジェクトのパラメーターがその他の非同期機能 API では、異なっています。だから Document.setSelectedDataAsync のオプションのパラメーターは、データの設定に関連しています。

coercionType:形式を指定する CoercionType 列挙体のデータ (テキスト、HTML、OOXML、表またはマトリックス) を挿入
上:その唯一のパラメーターとしてコールバック関数に渡された AsyncResult オブジェクトで返されるユーザー定義のオブジェクトを変更

その同じ概念は、他のすべての非同期機能に適用されます。

オブジェクトリテラルインラインの非同期関数呼び出しとして省略可能なパラメーターが含まれているオブジェクトを提供または最初オブジェクトを作成し、そのオブジェクトにパラメーターを渡すできます。 Document.setSelectedDataAsync 関数を使用して、オプションのオブジェクトの両方の方法を示す 2 つのコードサンプルを次に示します。

オプションパラメーターインラインを渡します。

function setData(data) {
  Office.context.document.setSelectedDataAsync(data, {
  coercionType: Office.CoercionType.Text }  
  );
}

オプションパラメーターは、JavaScript オブジェクトを渡します。

function setData(data) {
  var options = { coercionType: Office.CoercionType.Text };
  Office.context.document.setSelectedDataAsync(data, options );
}

AsyncResult オブジェクトに非同期関数の役割 3 番目のパラメーターで非同期関数 JavaScript api ではオフィスのための共通の署名は、オプションのコールバックパラメーターです。それとして丁度鳴るコールバックパラメーターです。非同期操作の完了時に呼び出される、提供する関数。もちろん、名前付き関数または匿名関数の非同期関数の呼び出しをインラインを提供することができます。ここで注意する重要なことは、AsyncResult オブジェクトコールバック関数の役割です。

ランタイムは、コールバックを呼び出すと、非同期で渡しますとして、コールバックの唯一の引数は、結果オブジェクト。 AsyncResult オブジェクトにはなど、非同期操作に関する情報が含まれています。かどうか、操作が成功した; あれば、どのようなエラーが発生しました。戻り値は、非同期関数のいずれかの場合。実際には、いくつかの種類のデータやオブジェクトを返すすべての非同期関数で、AsyncResult ですで返される値を得ることができる唯一の方法。これを行うには、AsyncResult.value プロパティを使用します。

たとえば、次のコードスニペットは、ドキュメントのサイズを取得します、アプリケーション UI の指定した HTML 要素が表示されます。ファイルサイズを取得するには、まず Document.getFileAsync メソッドが返されるファイルオブジェクト AsyncResult.value プロパティを通じて取得します。ここでこれを行う方法は、次のとおりです。

function getFileData(elementId) {
  Office.context.document.getFileAsync(Office.FileType.Text,
  function (asyncResult) {
    if (asyncResult.status === 'succeeded') {
      var myFile = asyncResult.value;
      $(elementId).val(myFile.size);
    }
  });
}

GetFileData 関数は、ファイルの内容をテキストとしてを返す必要がありますを指定する、Document.getFileAsync メソッドを呼び出します。匿名関数コールバックに渡された AsyncResult オブジェクトの value プロパティを使用して、ファイルオブジェクトへの参照を取得します。後それファイルオブジェクトのサイズプロパティを使用して、指定した要素で、ファイルのサイズを表示します。同様の方法では、AsyncResult.value プロパティを使用して、非同期関数の戻り値のアプリ Office API を取得します。

詳細を読むことができます Document.getFileAsync 法このシリーズの次の記事について。

オブジェクトモデルの階層

JavaScript API のオフィスは別のホストアプリケーションで Office と対称性のバージョン間で互換性を提供を目指しています。これらの目標をサポートするには、JavaScript API を無駄のないオブジェクトモデルは特定のホストアプリケーションに直接関連付けられていない異なる階層があります。代わりに、オブジェクトモデルは、目的のスコープを使用するアプリケーション（タスクペイン、コンテンツまたはメールアプリケーション) の種類に設定、Office ドキュメントと対話するための機能のセットをホストします。

図 1 オフィス (オブジェクトモデル全体が表示されていないことに注意してください)、JavaScript API でのオブジェクトの最上位の階層の省略概要します。具体的には、図オフィス、コンテキスト、文書、設定、メールボックスおよび RoamingSettings のオブジェクト間の関係を示しています。

The Object Model Hierarchy in the JavaScript API for Office
オフィスの JavaScript API でのオブジェクトモデルの階層図 1

各ホストアプリケーション (Word、Excel、Excel Web App、PowerPoint、プロジェクト、Outlook および Outlook Web App) API に含まれる機能のサブセットを使用することができます。たとえば、約 40 ％、オブジェクトモデルの Outlook および Outlook Web App では、使用するメールアプリケーションのみに関係します。オブジェクトモデルの別の部分はカスタム XML 部分との相互作用はのみ Word 2013 年に利用可能ですできます。

図 2 の特定に使用できるホストアプリケーションの機能を示しています。

図 2 可用性機能 Office ホストアプリケーションでの JavaScript API での

説明	Word の場合	Excel/Excel Web App	PowerPoint の場合	Outlook/Outlook Web App	Project の場合
テキスト、表、マトリックスとしてデータを取得/設定	すべて。	すべて。	テキストのみ		テキストのみ
[設定]	すべて。	すべて。	すべて。	(RoamingSettings)
ファイルを取得します。	すべて。		のみ圧縮
Bindings (バインド)	すべて。	すべて。
カスタム XML パーツ	すべて。
HTML と OOXML	すべて。
メールボックス				すべて。

オブジェクトモデル内のオブジェクトを共有オフィスの JavaScript API が決定的なエントリポイントですべての種類のアプリケーションのすべてのホストアプリケーションで利用可能な Office オブジェクトがあります。 Office のオブジェクト、ドキュメント、ブック、プレゼンテーション、プロジェクト、電子メールメッセージまたは予定に挿入は、アプリケーションの特定のインスタンスを表します。バインド、アプリケーションとドキュメントを使用してアクセスすることができます、 を選択メソッド。 (バインド、今後の記事で詳しく説明します。)最も重要なは、Office オブジェクト (これについては今後の記事で）のアプリケーションのための初期化ロジックを構築することができますアプリケーションの初期化イベントを公開します。最後に、Office オブジェクトには、アプリケーションのコンテキストオブジェクトへの参照が含まれています。

またすべてのタイプのアプリケーションのすべてのホストアプリケーションで利用可能なコンテキストオブジェクトは、アプリケーションをホストしているランタイム環境に関する情報を公開します。アプリケーションの言語設定を保存するのに加えて、コンテキストオブジェクトは、アプリケーションがアクティブ化されたホストに固有事務所の JavaScript API のランタイム機能へのエントリポイントを提供します。

たとえば、Context.document プロパティを通じてアプリケーションに関連付けられているドキュメント (Document オブジェクト) をアクセスすることができます。ただし、このプロパティは、それは、内からをサポートするホストアプリケーション内からのみ呼び出すときに、値を返しますタスクウィンドウまたはコンテンツアプリケーション。 Context.document プロパティには、メール・アプリケーションからアクセスすると我々は「未定義オブジェクト」エラーが発生します。 Context.mailbox のプロパティと同様に。メールアプリケーションでは、それをホストアプリケーションで開くメールボックス (メールボックスオブジェクト) を返します。タスクウィンドウアプリケーションでは、定義されていません。

タスクペインとコンテンツのサポート アプリオブジェクトモデルコンテンツアプリケーションの作業ウィンドウは、ドキュメントオブジェクト、文書、ブック、プレゼンテーションまたはに、アプリケーションが挿入されているプロジェクトを表します。ドキュメントオブジェクトは高度なファイルのコンテンツへのアクセスを提供します-基本的に、アプリケーションおよび Office ドキュメント間の接触の主なポイントです。

ほとんどすべての Office ドキュメントのコンテンツにアクセスするための技術の文書オブジェクトを使用する必要があります。このために示すように、アプリケーションを初期化するときドキュメントオブジェクトへの参照を取得したいのですが図 3。

図 3 アプリケーションを初期化するときドキュメントオブジェクトへの参照を格納します。

// Add a handler to the initialize event of the Office object
Office.initialize = function (reason) {
  $(document).ready(function () {
    app.get_Document(Office.context.document);
 
    // Other initialization logic goes here
  })
}
 
// Use a self-executing anonymous function to encapsulate the
// functionality that the app uses
var app = (function () {
 
  var _document;
  function get_Document(officeDocument) {
    _document = officeDocument;
  }
 
  // Other fields and functions associated with the app
 
  return {
    get_Document: get_Document
    // Other exposed members
  };
})()

アプリケーションプロジェクトファイル内でアクティブになったときは、ドキュメントオブジェクトのプロジェクトファイルを特定の追加機能を公開します。ドキュメントオブジェクトをアプリケーションプロジェクトにデータを特定のタスク、ビュー、フィールドおよびリソースを得ることができます。アプリケーションはユーザーが選択したビュー、タスクまたはリソースのプロジェクトを選択を変更を監視するイベントリスナーを追加することもできます。 (我々はドキュメントオブジェクトでアプリケーションプロジェクトのための次の記事で使用について説明します。)

また、ドキュメントオブジェクトによって公開されるアプリケーション「プロパティバッグ」を表す設定オブジェクトです。アプリケーションは格納し、複数のアプリケーションセッション設定オブジェクトを使用して、同じドキュメント内のカスタムプロパティを保持できます。プロパティは、ドキュメントに旅行します。誰かとアプリケーションが含まれている Office ファイルを共有する場合、他の人がファイルを読み込むときアプリケーションに格納されているカスタムプロパティは利用可能ななります。

格納するプロパティバッグを使用して設定を取得する簡単です。 Settings.set メソッドには、キー/値ペアとしてメモリ内の設定を作成します。プロパティをプロパティバッグから取得するには、値を取得する設定の名前 (キー) を渡して、Settings.get メソッドを使用します。 Set および get アクセサーメソッドは同期的です。セッション間で設定を保存するには、我々は、ドキュメントを保存するときに含まれるカスタムプロパティのすべてのアプリケーションを保存します Settings.saveAsync メソッドを呼び出す必要があります。

コードサンプルは、「Office のアプリケーション。カスタム設定を保持」(bit.ly/UEiZff)、設定オブジェクトを使用する方法と、アプリケーションでデータを格納する方法の例を示します。

メールアプリオブジェクトモデルのサポートメールアプリケーションでは、メールボックスオブジェクトはデータアクセスメールアプリケーション特有の機能のためのエントリポイントを提供します。名前が示すように、メールボックスオブジェクトは、現在のユーザーのメールボックスに対応して、移動ユーザーは、e メールを読んでどこに — Outlook クライアントアプリケーションまたは Outlook Web App のいずれか。個々の電子メールメッセージや予定 (Mailbox.item プロパティ) をへのアクセスを提供することに加えて、メールボックスオブジェクトは、新しい予定を作成、ローカルユーザーのプロファイルにアクセスしてもユーザーのローカル時刻を取得するアプリケーションをことができます。

コンテンツとタスクのウィンドウアプリケーションのためのドキュメントオブジェクトのようなアプリケーションは、初期化時に示すようにメールボックスオブジェクトへの参照をキャプチャする必要があります図 4。

図 4 アプリケーションを初期化するとメールボックスオブジェクトへの参照をグローバル変数に格納します。

// Add a handler to the initialize event of the Office object
Office.initialize = function (reason) {
  $(document).ready(function () {
    app.get_Mailbox(Office.context.mailbox);
 
    // Other initialization logic goes here
  })
}
 
// Use a self-executing anonymous function to encapsulate the
// functionality that the app uses
var app = (function () {
 
  var _mailbox;
  function get_Mailbox(mailbox) {
    _mailbox = mailbox;
  }
 
  // Other fields and functions associated with the app
 
  return {
    get_Mailbox: get_Mailbox
    // Other exposed members
  };
})()

またメールのアプリでのみ利用可能な RoamingSettings オブジェクトは、ドキュメント中心のアプリケーション（タスクウィンドウとコンテンツアプリケーション）の設定オブジェクトに似ています。カスタムプロパティ名/値のペアとしてセッション間で保持するアプリケーションできます。ただし、ホスト Office ファイル内のカスタムプロパティを保存の設定オブジェクトとは異なり RoamingSettings オブジェクトを現在のユーザーのメールボックスにカスタム設定を保存します。これは、カスタムプロパティはユーザーがどのようなメッセージに関係なくアプリケーションを見て、またはどのようにユーザーが彼のメールボックス（Outlook または Outlook Web App) にアクセスしたします。

オフィスの JavaScript API でのオブジェクトモデルの階層については、MSDN のドキュメントページ「理解 JavaScript API のオフィス」を参照してください (bit.ly/UV2POY)。

機能は、ホストアプリケーションで使用することができるかどうかをテスト

我々は以前に触れたように、オフィスの JavaScript API の強みの 1 つ「を一度開発すれば、多くの場所は、ホスト」自然のオフィスのためのアプリです。 (そのマニフェストでこれらの機能のすべてが許容されている）たとえば、同じタスクウィンドウアプリケーションは Word、Excel、プロジェクト、PowerPoint 内でアクティブにできます。

まだ、すべてのアプリの機能の正確な同じリストへのアクセスがあるため、アプリケーション、アプリケーションを必要とする機能を許可しないホストアプリケーションに挿入できませんでした。たとえば、プロジェクトは現在設定オブジェクトへのアクセスを提供しません。プロジェクトに挿入すると、設定オブジェクトにアクセスしようとすると、アプリケーションは「"未定義オブジェクト」のエラーが発生します。

したがって、開発者は必要な機能の可用性をテストするためのアプリケーションロジックを含める必要があります。プロジェクトの例では、ホストアプリケーションの機能を検出するための最良の手法は簡単です場合ブロック。

// Test for Settings object in host application
if (Office.context.document.settings) {
 
  // Provide implementation that uses the Settings object
 
}
else {
 
  // Use some other technique for saving custom properties,
  // like localStorage, sessionStorage or cookies
 
}

メンバーがホストアプリケーションで使用できるかどうかを検出する方法については、MSDN のマニュアルページを参照してください"どのように。ホストアプリケーションのサポート API の特定のメンバーを判断" bit.ly/TR5ZlB。

この記事を要約するには、JavaScript API のオフィスの肉とジャガイモを説明しました。我々は、オブジェクトモデルの階層を高レベルで説明されている、オブジェクトモデルの実装、非同期パターンについて説明。我々も、機能は、ホストアプリケーションでサポートされてかどうかをテストする方法を説明しました。

このシリーズの次の記事で私たちのためのオフィスアプリケーション内のデータを操作するための最も簡単なまだ最も強力な方法を詳しく見てをみましょう。我々は、取得しより多くの深さで選択したデータを設定する方法について説明します。我々は、すべてのファイルの内容とそれを解析する方法を得ることで見てみましょう。また、我々はアプリケーションプロジェクトおよびタスクを読む方法について説明しますリソースおよびビューデータ。最後に、JavaScript API のオフィスでのイベントモデルを確認します。コードに対してどのようなイベントとその結果を処理する方法。

Stephen Oliver* *オフィス部門では、マイクロソフト認定プロフェッショナルデベロッパー (SharePoint 2010) のプログラミング関連ライターです。彼は PowerPoint オートメーションサービス開発者向けのドキュメントと一緒に Excel Services および Word Automation Services 開発者向けのドキュメントを書いています。彼はバーテンし、Excel のマッシュアップサイトでデザインを助けた ExcelMashup.com。

Eric Schmidt* *事務部門でのプログラミング関連ライターです。彼は人気のある「永続化設定」のコードサンプルを含め、Office のアプリケーションのためのいくつかのコードサンプルを作成しています。さらに、彼は記事を書かれており、その他の製品とテクノロジ内で Office のプログラミング機能についてのビデオを作成します。

この記事のレビュー、次技術専門家のおかげで。 ブリュースター、シル Kothari、フアン Balmori Labra をマークします。

Microsoft Office

新しい JavaScript API for Office について調べる (機械翻訳)

オフィスの JavaScript API の概要

非同期プログラミング パターン

オブジェクト モデルの階層

機能は、ホスト アプリケーションで使用することができるかどうかをテスト

その他のリソース

非同期プログラミングパターン

オブジェクトモデルの階層

機能は、ホストアプリケーションで使用することができるかどうかをテスト