コンポーネントのマニフェスト
コンポーネント マニフェストの構成は、コード コンポーネントを構築する上で重要な手順です。 ControlManifest.Input.xml ファイルは、pac pcf init コマンドを使用する場合、コンポーネントの名前とタイプなど何らかの選択肢で初期化されます。 使用しているプロパティやリソースを指定して、コンポーネントで使用するフレームワークの機能を有効にする場合にも、このファイルをカスタマイズする必要があります。
コンポーネントのプロパティ
プロパティは、コード コンポーネントとホスト アプリケーションの間の契約を定義します。 これらは、コンポーネントの実装方法から所有者を抽象化する必要がありますが、そのコンポーネントを使用する所有者の構成可能な機能を提供します。 コンポーネントにプロパティを追加する必要があるプロパティの一般的ないくつかのタイプを次に示します。
- コード コンポーネントに対するビジネス データの受け渡しを許可します。 たとえば、コンポーネントに位置情報を渡すと、コンポーネントは特定の場所を強調表示するマップを表示できます。
- コンポーネントの機能と動作の制御を許可します。 たとえば、マップの例では、ユーザーがマップ上で拡大または縮小できるかどうかを示すプロパティを追加できます。
- コンポーネント スタイルの一部の側面をカスタマイズできます。 たとえば、マップ上で、作成者が構成できるプロパティを指定することで、コンポーネントによりピンの色をカスタマイズできる場合があります。
次のスクリーン ショットは、進行状況インジケーター コンポーネントに対して定義されたプロパティを示すサンプル マニフェストです。
作成者がコード コンポーネントを構成すると、マニフェストで定義されたプロパティを構成に使用できます。 この画像は、進行状況インジケーター コンポーネントの上記のマニフェストがアプリケーション デザイナーの所有者に示されている方法を示しています。 これにより、使用可能なプロパティを確認し、カスタマイズできます。
プロパティ属性
ニーズに応じて構成できるプロパティには、複数の属性を構成できます。 考慮すべきいくつかの一般的な属性を次に示します。
of-type - この属性は、プロパティのデータ型を定義します。 選択できる型は多数あります (SingleLine.Text から Enum まで)。 Enum のような一部の型では、選択できる固定リストを使用することで、作成者の構成エクスペリエンスがさらに豊かになります。 その他は、ホスト アプリから渡す型に基づいてデータのコンテンツを制限します。 Lookup.Simple のように、データ バインドにより適したものがあります。 コンポーネントの公開後は、データ型が変更されるのを常に避けるようにしてください。
usage - この属性は、プロパティが入力、出力、またはバインドされたかどうかを識別します。 これはモデル駆動型アプリ用です。 バインドされたオプションには、データ値を提供するテーブル データ列が関連付けられている必要があります。
required - プロパティの値が必要かどうかを示します。 コンポーネントの公開後に新しいプロパティを追加する場合は、そのコンポーネントを使用する既存のアプリで必要なプロパティを作成した場合の影響を考慮します。
default-value - この属性には、コンポーネントに対して指定された既定値があります。 モデル駆動型アプリでは、このプロパティは、用途タイプが入力であるプロパティでのみ許可されます。 既定値を指定すると、作成者にとってプロパティの設定方法を考えるのに役立つ場合があります。 既存のコンポーネントに新しいプロパティを追加すると、多くの場合、既定値はプロパティを介して構成可能になる前に、使用されるコンポーネントの値に設定されます。
追加する予定のプロパティを評価する際に、考慮すべきいくつかの点を次に示します。
- 作成者がオプションの長い一覧を移動する必要がなくなるように、コンポーネントのプロパティをできるだけ少なくします。
- プロパティには明瞭な名前を使用します。 可能な場合は、最低限必要な詳細を説明に入力して、作成者にその目的を通知します。
- 作成者がコンポーネントのスタイルを設定できるように、一部のプロパティの追加を検討してください。 これらのプロパティは、さまざまなアプリケーションでコンポーネントを使用する場合に重要になる可能性があります。
- コンポーネントを公開した後でプロパティの名前を変更したり、プロパティを削除したりしないようにします。そうすると、既存の消費アプリでは破壊的変更になる可能性があります。
コンポーネントのリソース
マニフェスト中のリソース ノードは、コンポーネントに必要なリソース ファイルを識別します。 新しいコンポーネントでは、最初は必要なコード要素のみが含まれる場合があります。 コンポーネントが依存している他のリソースを追加できます。 最も一般的なのは css と resx です。
css 要素を使用すると、読み込む必要がある CSS (カスケード スタイル シート) ファイルを識別できます。 複数のファイルがある場合は、必要に応じて、それらを読み込む順序を指定できます。 次のコードに、2 つの CSS ファイルを読み込む例を示します。
<css path="css/ComponentCommon.css" order="1" />
<css path="css/ProgressIndicator.css" order="2" />
マニフェストでの resx ノードは、定義するローカライズされた文字列の管理に使用するファイルを識別します。 ローカライズする場合は、これを新しいコンポーネントに追加し、プロパティを追加して更新した方が簡単です。 display-name-key 属性および description-key 属性のマニフェスト値のプロパティは、読み込まれた resx リソース ファイル内にローカライズされた値がある場合、その値を検索するために使用されます。
たとえば、次のプロパティ定義、およびこれらの属性の定義方法を確認します。
<property name="PercentComplete" description-key="PercentComplete_Desc" display-name-key="PercentComplete" required="true" usage="input" of-type="Whole.None" default-value="40" />
Microsoft ResX Schema を使用する XML ファイルである resx ファイルでは、プロパティ キーに次のデータ要素を定義します。
<data name="PercentComplete" xml:space="preserve">
<value>Percent Complete</value>
</data>
<data name="PercentComplete_Desc" xml:space="preserve">
<value>Percent Complete is the current value for how much has been completed.</value>
</data>
その後、サポートする言語ごとに個別の resx ファイルを作成します。
次に、マニフェスト リソース ノードで、コンポーネントの使用時にファイルを読み込むために、次の resx ノードを追加します。
<resx path="strings/ProgressIndicator.1033.resx" version="1.0.0" />
<resx path="strings/ProgressIndicator.1035.resx" version="1.0.0" />
<resx path="strings/ProgressIndicator.3082.resx" version="1.0.0" />
コンポーネントの機能の使用
フレームワークのデバイス、ユーティリティ、および WebAPI 機能は、モデル駆動型アプリで使用するコンポーネントで使用できます。 これらの機能の 1 つを使用するには、use-feature ノードを追加して、feature-usage ノード内でマニフェストを宣言する必要があります。 次のコードに、WebAPI 機能の使用を有効にする例を示します。
<feature-usage>
<uses-feature name="WebAPI" required="true" />
</feature-usage>