ヘッダーをスキップ

Oracle® Mobile Application Framework Oracle Mobile Application Frameworkでのモバイル・アプリケーションの開発 2.1.1.0.0 E64867-01 |
| 目次

前 | 次 |

# 19 カスタムMAF AMX UIコンポーネントの作成

この章では、カスタムMAF AMX UIコンポーネントを作成し、それらを開発環境の一部として指定する方法について説明します。

この章の内容は次のとおりです。

- 第19.1項「カスタムUIコンポーネントの作成の概要」

- 第19.2項「MAF APIを使用したカスタム・コンポーネントの作成」

- 第19.3項「カスタム・コンポーネントの作成」

## 19.1 カスタムUIコンポーネントの作成の概要

MAFによって提供されるJavaScriptとAPIの組合せを使用して、完全に機能する新しいインタラクティブなUIコンポーネントを作成し、それらをタグ・ライブラリに追加して、MAF AMXアプリケーション機能で使用できます。

## 19.2 MAF APIを使用したカスタム・コンポーネントの作成

MAFでは、カスタム・コンポーネントの作成用に次のAPIが提供されています。

- 静的API (第19.2.1項「静的APIの使用方法」を参照)

- `AmxEvent`クラス(第19.2.2項「AmxEventクラスの使用方法」を参照)

- `TypeHandler` (第19.2.3項「TypeHandlerの使用方法」を参照)

- `AmxNode` (第19.2.4項「AmxNodeの使用方法」を参照)

- `AmxTag` (第19.2.5項「AmxTagの使用方法」を参照)

- `VisitContext` (第19.2.6項「VisitContextの使用方法」を参照)

- `AmxAttributeChange` (第19.2.7項「AmxAttributeChangeの使用方法」を参照)

- `AmxDescendentChanges` (第19.2.8項「AmxDescendentChangesの使用方法」を参照)

- `AmxCollectionChange` (第19.2.9項「AmxCollectionChangeの使用方法」を参照)

- `AmxNodeChangeResult` (第19.2.10項「AmxNodeChangeResultの使用方法」を参照)

- `AmxNodeStates` (第19.2.11項「AmxNodeStatesの使用方法」を参照)

- `AmxNodeUpdateArguments` (第19.2.12項「AmxNodeUpdateArgumentsの使用方法」を参照)

### 19.2.1 静的APIの使用方法

表19-1に、カスタムUIコンポーネントの作成に使用できる静的APIを示します。

表19-1 静的API

戻り型 | 関数名 | パラメータ | 説明
--- | --- | --- | ---
`Function` | `adf.mf.api.amx.TypeHandler.register` | `String namespaceUrl`、 `String tagName`、 `adf.mf.api.amx.TypeHandler precreatedClass` | タグの名前空間および名前を指定して`TypeHandler`クラスを登録します。 プロトタイプ関数を追加できるように、登録されている`adf.mf.api.amx.TypeHandler`サブクラスを返します。 `precreatedClass`はオプションですが、`adf.mf.api.amx.TypeHandler`から継承するクラスを最初に作成する場合に使用できます。
`void` | `adf.mf.api.amx.addBubbleEventListener` | `Node domNode`、 `String eventType`、 `Function listener`、 `Object eventData` | バブル・イベント・リスナー(tap、taphold、keydown、touchstart、touchmove、touchend、focus、blur、resizeなど)を登録します。 Webブラウザが、すべてのDOMノードのすべてのイベント・タイプをサポートしているわけではないことに注意してください(詳細は、ブラウザのドキュメントを参照)。 `eventData`はオプションで、リスナー関数に使用できる追加データとして機能します。
`void` | `adf.mf.api.amx.removeBubbleEventListener` | `Node domNode`、 `String eventType`、 `Function listener` | `adf.mf.api.amx.addBubbleEventListener`で追加されたバブル・イベント・リスナーを登録解除します。 メタ・イベントtapおよびtapholdを削除すると、指定されたリスナーだけが削除されるのではなく、すべてのtouchstartおよびtouchendリスナー(他のメタ・イベントのこれらのリスナーも含む)が要素から削除されることに注意してください。
`void` | `adf.mf.api.amx.addDragListener` | `Node domNode`、 `Object payload`、 `Object eventData` | 要素に対して、MAF AMXドラッグ・イベントのトリガーを許可します。 `Object` `payload`では、3つのメンバー関数(`start`、`drag`、`end`)を定義します。各関数の最初のパラメータはDOMイベントで、2番目のパラメータは次のメンバーが含まれる`dragExtra` `Object`です。 `eventSource`: DOMイベント・ソース。 `pageX`: イベントの`x`座標。 `pageY`: イベントの`y`座標。 `startPageX`: 元の`pageX`。 `startPageY`: 元の`pageY`。 `deltaPageX`: `pageX`の変更。 `deltaPageY`: `pageY`の変更。 `originalAngle`: 定義されている場合は、ドラッグの元の角度(度)で、0度は東、90は北、-90は南、180は西です。 次の変更可能なメンバー・フラグがあります。 `preventDefault` `stopPropagation` `eventData`はオプションで、リスナー関数に使用できる追加データとして機能します。
`void` | `adf.mf.api.amx.removeDomNode` | `Node domNode` | DOMノードおよびその子を削除しますが、その前に、`adf.mf.api.amx.addBubbleEventListener`で追加されたイベント・リスナーを削除します。
void | `adf.mf.api.amx.emptyHtmlElement` | `Node domNode` | 子DOMノードを削除し、それらの各子ノードで`adf.mf.api.amx.removeDomNode`をコールすることで、HTML要素を空にします。
`void` | `adf.mf.api.amx.processAmxEvent` | `adf.mf.api.amx.AmxNode amxNode`、 `String amxEventType`、 `String attributeValueName`、 `String newValue`、 `AmxEvent amxEvent`、 `Function successCallback` `Function failureCallback` | `AmxEvent`を処理します。 `attributeValueName`が定義されている場合は値を変更し、適切な`setPropertyListener`および`actionListener`サブタグを処理し、次に`[amxEventType]Listener`属性を処理します。 イベントが正常に処理されると、成功コールバックが起動されます。そうでない場合は、失敗コールバックが起動されます。`successCallback`と`failureCallback`の両方はオプションです。
`void` | `adf.mf.api.amx.acceptEvent` | なし | `adf.mf.api.amx.processAmxEvent`に渡す必要がある可能性があるすべてのものを準備しなくても済むように、この関数の呼出しを続行しても安全であるかどうかを判断します(たとえば、ページ遷移の途中や、デザインタイム・プレビューなどの環境の場合)。
`void` | `adf.mf.api.amx.invokeEl` | `String expression`、 `Array<String> params`、 `String returnType`、 `Array<String> paramTypes`、 `Function successCallback`、 `Function failureCallback` | ELメソッドを呼び出す点で`adf.mf.el.invoke()`に類似しており、デザインタイム・プレビューなどの環境では実行を控える点が異なるユーティリティを表します。
`void` | `adf.mf.api.amx.enableAmxEvent` | `adf.mf.api.amx.AmxNode amxNode`、 `Node domNode`、 `String eventType` | DOMノードに対して、`amx:showPopupBehavior`、`amx:setPropertyListener`などのカスタムMAF AMXイベント(`tapHold`や`swipe`など)のトリガーを許可します。
`void` | `adf.mf.api.amx.doNavigation` | `String outcome` | 指定された結果へのナビゲーションを実行することをコントローラに指示します。
`void` | `adf.mf.api.amx.validate` | `Node domNode`、 `Function successCallback` | 不十分なバリデータ(必須または`amx:validationBehavior`)がある場合、ナビゲーションなどの操作を阻止します。 続行が許可されると、`successCallback`が呼び出されます。
`void` | `adf.mf.api.amx.showLoadingIndicator` | `Number failSafeDuration`、 `Function failSafeClientHandler` | ビジー・インジケータを示します。 パラメータは次のとおりです。 `failSafeDuration`: ローディング・インジケータの表示および非表示の間にMAFが待機するおよその期間(ミリ秒を表す負でない整数) (他のトリガーがすでにインジケータを表示していないと仮定した場合)。このパラメータが指定されていないか、または`null`に設定されている場合、MAFは10000 (10秒)の値を使用します。 `failSafeClientHandler`: `failSafeDuration`に達した場合に起動されるオプションのJavaScript関数。この関数を使用して、続行方法を決定できます。この関数は、次のいずれかの値で定義されている`String`を返す必要があります。 - `hide`: デフォルトのフェイルセーフのようにインジケータを非表示にします。 - `repeat`: 関数を再度呼び出せるように新たな期間についてタイマーを再起動します。 - `freeze`: インジケータを稼働させたまま無期限に待機させ、ページは再起動されるまでフリーズ状態で停止します。 インジケータが必要以上に表示されるのを回避するには、非表示にします。
`void` | `adf.mf.api.amx.hideLoadingIndicator` | なし | ローディング・インジケータの1つのインスタンスを非表示にします。
`Object` | `adf.mf.api.amx.createIterator` | `Object dataItems` | 3ノード・イテレータ(コレクション・モデル)に対するオブジェクトのJavaScript配列またはイテレータをサポートするイテレータを作成します。 `next`、`hasNext`および`isTreeNodeIterator`関数でイテレータ`Object`を返しますが、ここで、`next`は、使用可能なオブジェクトがそれ以上ない場合、undefinedを返します。
`void` | `adf.mf.api.amx.bulkLoadProviders` | `Object treeNodeIterator`、 `Number startingPoint`、 `Number maximumNumberOfRowsToLoad`、 `Function successCallback`、 `Function failCallback` | 一連のデータ・プロバイダをバルクロードして、これらがキャッシュされてローカルでアクセスできるようにします。
`String` | `adf.mf.api.amx.buildRelativePath` | `String url` | 現在のMAF AMXページに対して相対的であると想定して、指定されたリソースに基づく相対パスを作成します。リソース上にプロトコルがある場合は、絶対パスであると想定され、変更されません。
`void` | `adf.mf.api.amx.markNodeForUpdate` | `adf.mf.api.amx.AmxNodeUpdateArguments args` | `AmxNode`に対する状態変更(`AmxNode`階層がそのノード以下で更新される必要がある)をMAFに通知する、`TypeHandler`インスタンスの関数。 カスタム`createChildrenNodes`メソッドが`TypeHandler`に存在する場合は、これらの`AmxNode`インスタンス対して再度コールされます。これにより、子にスタンプ設定する`AmxNode`インスタンスは、ユーザー変更による新しいスタンプを追加できます。`refresh`メソッドは、`AmxNode`がレンダリングする準備ができた場合、指定されたプロパティを使用して`AmxNode`でコールされます。`AmxNode`がレンダリングする準備ができていない場合、MAFはELが解決されるのを待機し、すべてのデータが使用可能になった後に`refresh`メソッドがコールされます。

注意: `adf.mf.el`パッケージのその他のパブリックAPIは、ロギング、変換およびデータ・チャネルに使用できます。

### 19.2.2 AmxEventクラスの使用方法

表19-2に、カスタムUIコンポーネントの作成時に使用できる`AMXEvent`クラスをリストします。

表19-2 AMXEventクラス

クラス名 | パラメータ | 説明
--- | --- | ---
`adf.mf.api.amx.ActionEvent` | なし | 結果ベースのナビゲーションをトリガーするイベント。 ``Oracle Fusion Middleware Oracle Mobile Application Framework Java APIリファレンスのoracle.adfmf.amx.event.ActionEventも参照してください。
`adf.mf.api.amx.MoveEvent` | `Object rowKeyMoved`、 `Object rowKeyInsertedBefore` | 指定された行が移動されたことを通知するイベント。移動された行のキー、および移動済行がその前に挿入された行のキーが含まれます。 ``Oracle Fusion Middleware Oracle Mobile Application Framework Java APIリファレンスのoracle.adfmf.amx.event.MoveEventも参照してください。
`adf.mf.api.amx.SelectionEvent` | `Object oldRowKey`、 `Array<Object> selectedRowKeys` | コンポーネントの選択変更のイベント。 ``Oracle Fusion Middleware Oracle Mobile Application Framework Java APIリファレンスのoracle.adfmf.amx.event.SelectionEventも参照してください。
`adf.mf.api.amx.ValueChangeEvent` | `Object oldValue`、 `Object newValue` | コンポーネントの値変更のイベント。 ``Oracle Fusion Middleware Oracle Mobile Application Framework Java APIリファレンスのoracle.adfmf.amx.event.ValueChangeEventも参照してください。

### 19.2.3 TypeHandlerの使用方法

表19-3に、カスタムUIコンポーネントの作成に使用できる`TypeHandler` APIを示します。

表19-3 TypeHandler API

戻り型 | 関数名 | パラメータ | 説明
--- | --- | --- | ---
`HTMLElement` | `render` | `adf.mf.api.amx.AmxNode amxNode`、 `String id` | 初期DOM構造を作成し、その構造のルート要素を返します。 このメンバー関数は必須であり、定義されている必要があります。
`void` | `init` | `HTMLElement rootElement`、 `adf.mf.api.amx.AmxNode amxNode` | このコンポーネントで作成される一連のコンポーネントに属するすべての`create`関数が呼び出された後に呼び出されるハンドラを表します。
`void` | `postDisplay` | `HTMLElement rootElement`、 `adf.mf.api.amx.AmxNode amxNode` | このコンポーネントで作成される一連のコンポーネントに属するすべての`init`関数が呼び出された後に呼び出されるハンドラを表します。
`Boolean` | `createChildrenNodes` | `adf.mf.api.amx.AmxNode amxNode` | 処理する子`AmxNode`を選択して追加します。いずれかの子が示されている場合、この関数を使用すると、他の子が処理されなくなることに注意してください。 MAFがカスタム実装ではなく子ノードを作成する場合は、`false`を返す必要があります。 この関数はオプションです。
`adf.mf.api.amx.AmxNodeChangeResult` | `updateChildren` | `adf.mf.api.amx.AmxNode amxNode`、 `adf.mf.api.amx.AmxAttributeChange attributeChanges` | 次のいずれかのハンドラを表します。 古い子をすべて削除し、新しい子を作成して`AmxNode`に追加します。 戻り値を介して、実行する必要がある`adf.mf.api.amx.AmxNodeChangeResult`アクションを宣言します。 この関数はオプションです。
`adf.mf.api.amx.AmxNodeChangeResult` | `getDescendentChangeAction` | `adf.mf.api.amx.AmxNode amxNode`、 `adf.mf.api.amx.AmxDescendentChanges descendentChanges` | タイプ・ハンドラに対して、子孫`AmxNode`インスタンスへの変更処理のカスタマイズを許可します。
`void` | `refresh` | `adf.mf.api.amx.AmxAttributeChange attributeChanges`、 `adf.mf.api.amx.AmxDescendentChanges descendentChanges` | タイプ・ハンドラに対して、変更に応答したHTMLの選択的リフレッシュを許可します。このメソッドは、`updateChildren`メソッドの後にコールされます。 `attributeChanges`は変更された属性を定義します。`descendentChanges`が`null`でない場合は、リフレッシュする必要があるすべての子孫ノードに対する変更を定義します。
`Boolean` | `isFlattenable` | なし | `AmxNode`がフラット化可能であるかどうかを宣言します。フラット化されたAmxNodeにはレンダリング関連の動作がない可能性がある(フラット化されたAmxNodeのタイプ・ハンドラは子ノードの作成とアクセスのみを制御でき、レンダリングには影響を与えない)ことに注意してください。
`Boolean` | `visit` | `adf.mf.api.amx.VisitContext visitContext`、 `Function visitCallback` | この`AmxNode`から始まる`AmxNode`ツリー・アクセスを処理します。 アクセスでパラメータ`visitContext`および`AmxNode`を使用する場合に呼び出す`visitCallback`関数。アクセスが完了し、続行する必要がないかどうかを返します。
`Boolean` | `visitChildren` | `adf.mf.api.amx.AmxNode amxNode`、 `adf.mf.api.amx.VisitContext visitContext`、 `Function visitCallback` | この`AmxNode`の子から始まる`AmxNode`ツリー・アクセスを処理します。 アクセスでパラメータ`visitContext`および`AmxNode`を使用する場合に呼び出す`visitCallback`関数。アクセスが完了し、続行する必要がないかどうかを返します。
`void` | `preDestroy` | `HTMLElement rootElement`、 `adf.mf.api.amx.AmxNode amxNode` | 現在のビューが破棄される直前、つまり新しいビューに移動しようとするときにすべてを処理します。通常は、スクロール位置などのクライアント状態を保存するために使用されます(`adf.mf.api.amx.setClientState`を参照)。
`void` | `destroy` | `HTMLElement rootElement`、 `adf.mf.api.amx.AmxNode amxNode` | 新しいビューが表示され、古いビューが削除された後にすべてを処理します。

### 19.2.4 AmxNodeの使用方法

表19-4に、カスタムUIコンポーネントの作成に使用できる`AmxNode` APIを示します。

表19-4 AmxNode API

文字列 | 関数名 | パラメータ | 説明
--- | --- | --- | ---
`String` | `getId` | なし | この`AmxNode`の一意の識別子を取得します。この値はルートDOM要素のIDに寄与します。
`adf.mf.api.amx.AmxTag` | `getTag` | なし | この`AmxNode`を作成した`AmxTag`を取得します。
`adf.mf.api.amx.TypeHandler` | `getTypeHandler` | なし | この`AmxNode`に関連付けられた`TypeHandler`オブジェクトを取得します。
`void` | `setClientState` | `Object payloadJsonObject` | 指定された`AmxNode` IDのクライアント状態を格納または置換します。 タイプ・ハンドラは、状態変更が発生するたびにこの関数をコールする必要があります(たとえば、ある状態をキャッシュしておき、ユーザーが新しいページに移動してから戻ってきたときに、スクロール位置のように復元できるようにする必要があります)。つまり、状態変更の発生を常に検出できるとはかぎらないため、ビューが破棄される直前にコンポーネントの状態を更新する必要がある場合があります。考慮する必要があるシナリオとして次の2つが考えられます。 `refresh`: (同じビュー内の)DOM構造部分の再描画用。 `preDestroy`: 新しいビューに移動し、後で戻ったときのため。 `payloadJsonObject`は、このビュー・インスタンスのライフタイム用に格納するクライアント状態データです。
`Object` | `getClientState` | なし | このビュー・インスタンス時に`setClientState`関数を介して以前に格納された`payloadJsonObject`を取得します(取得できない場合はundefined)。
`void` | `setVolatileState` | `Object payloadJsonObject` | 指定された`AmxNode` IDのクライアント状態を格納または置換します。タイプ・ハンドラは、揮発状態変更が発生するたびに、この関数をコールする必要があります(たとえば、新しいMAF AMXページへの移動時に忘れられたが、コンポーネントの再描画時に備えて保持しておく必要があるものなどです)。 `payloadJsonObject`は、ナビゲーションが発生するまで格納する揮発状態データです。
`Object` | `getVolatileState` | なし | 最後のナビゲーション以降、`setVolatileState`関数を介して以前に格納された`payloadJsonObject`を取得します(取得できない場合はundefined)。
`Object` | `getConverter` | なし | 適用可能な場合、この`AmxNode`のコンバータを取得します。
`void` | `setConverter` | `Object converter` | この`AmxNode`のコンバータを設定します。
`String` | `storeModifyableEl` | `String nameOfTheAttribute` | 属性に関して、EL値をモデルに設定するために使用できるEL式を作成して格納します。 この値は状況非依存で、値を設定するためにいつでも使用できます。一般的な用途は、ユーザーとの対話に基づいて値を設定することです。 この関数は、タイプ・ハンドラによってコールされる場合があります。 サブジェクト属性がEL値にバインドされていない場合は、`null`を返します。
`Object` | `getStampKey` | なし | `AmxNode`のスタンプ・キーを取得します。スタンプ・キーは、反復コンテナの内部で生成された`AmxNode`インスタンスを特定します。 これは、親`AmxNode`によって提供されます。スタンプ・キーを使用するタグの例として、`amx:iterator`タグがあります。 `AmxNode`がスタンプ設定されていない場合は、`null`を返します。
`Array<String>` | `getDefinedAttributeNames` | なし | このノードに定義された属性名のリストを取得します。
`Object` | `getAttribute` | `String name` | 指定された名前の属性の属性値を取得します。 戻り値は`null`である可能性があります。 属性が設定されていない、またはまだロードされていない場合は、undefinedを返します。
`void` | `setAttributeResolvedValue` | `String name`、 `Object value` | タイプ・ハンドラまたはMAFが属性の属性値を`AmxNode`に格納するために使用されます。 この関数では、モデルは更新されません。
`void` | `setAttribute` | `String name`、 `String value` | モデルの属性の値を設定します。 この値は、EL値を更新するためにJava側に送信されます。`AmxNode`の値はこのコールでは更新されません。かわりに、データ変更イベントが`AmxNode`を更新することが想定されます。
`Boolean` | `isAttributeDefined` | `String name` | 属性がユーザーによって定義されているかどうかをチェックします。
`adf.mf.api.amx.AmxNode` | `getParent` | なし | 最上位の場合は、親`AmxNode`または`null`を取得します。
`void` | `addChild` | `adf.mf.api.amx.AmxNode child`、 `String facetName` | この`AmxNode`に子`AmxNode`を追加します。 子がファセットに属していない場合、`facetName`は`null`になります。
`Boolean` | `removeChild` | `adf.mf.api.amx.AmxNode child` | この`AmxNode`から子`AmxNode`を削除します。 子は階層から削除されますが、そのDOMは削除されないことに注意してください。DOMの削除は、コール元の責任です。 これにより、タイプ・ハンドラは、DOMの置換時にアニメーションやその他の遷移を処理できます。 子が検出されて削除されたかどうかを返します。
`Boolean` | `replaceChild` | `adf.mf.api.amx.AmxNode oldChild`、 `adf.mf.api.amx.AmxNode newChild` | 既存の子を別の子に置換します。 古いものが検出されて置換されたかどうかを返します。
`Array<adf.mf.api.amx.AmxNode>` | `getChildren` | `String facetName`、 `Object stampKey` | 子`AmxNode`を取得します。 これら2つのパラメータはオプションです。`facetName`には、非ファセットの子を取得するために`null`を指定できます。 子が存在しないか、または指定された修飾子の子が存在しない場合は、空の配列を返します。
`Map<String, Array<adf.mf.api.amx.AmxNode>>` | `getFacets` | `Object stampKey` | `AmxNode`のすべてのファセットを取得します。 `stampKey`はオプションで、指定された場合は、指定されたスタンプ・キーのファセット`AmxNode`インスタンスを取得します。
`Boolean` | `visit` | `adf.mf.api.amx.VisitContext visitContext`、 `Function visitCallback` | この`AmxNode`から開始するツリー・アクセスを実行します。 `visitCallback`関数は、引数として`visitContext`および`AmxNode`を受け入れる必要があります。 アクセスが完了し、続行する必要がないかどうかを返します。
`Boolean` | `visitChildren` | `adf.mf.api.amx.VisitContext visitContext`、 `Function visitCallback` | この`AmxNode`の子から開始するツリー・アクセスを実行します。 `visitCallback`関数は、引数として`visitContext`および`AmxNode`を受け入れる必要があります。 アクセスが完了し、続行する必要がないかどうかを返します。
`Boolean` | `visitStampedChildren` | `Object stampKey`、 `Array<String> facetNamesToInclude`、 `Function filterCallback`、 `adf.mf.api.amx.VisitContext visitContext`、 `Function visitCallback` | カスタム`visitChildren`関数内から子`AmxNode`にアクセスするよう子にスタンプ設定するタイプ・ハンドラ用の便利な関数。 `facetNamesToInclude`が空の場合、このスタンプのファセットは処理されません。`facetNamesToInclude`が`null`の場合、このスタンプのすべてのファセットが処理されます。 `filterCallback`に`null`を指定できます。`filterCallback`は、`true` (子の作成にタグを使用)または`false` (タグが処理されない)の`Boolean`を返す必要があります。 `visitCallback`は、引数として`visitContext`および`AmxNode`を受け入れる必要があります。 アクセスが完了し、続行する必要がないかどうかを返します。
`Array<adf.mf.api.amx.AmxNode>` | `getRenderedChildren` | `String facetName`、 `Object stampKey` | `AmxNode`のレンダリングされた子を取得します。 `facetName`は、レンダリングされた子の取得元となるファセットを示し、非ファセットの子の場合は`null`になります。 `stampKey`が指定されている場合は、指定されたスタンプ・キーの子`AmxNode`インスタンスを取得します。 指定されたスタンプ・キーでレンダリングされる子を返します。フラット化できる(フラット化可能な)あらゆるコンポーネントをフラット化し、レンダリングされないコンポーネントは返しません。
`Boolean` | `isFlattenable` | なし | `AmxNode`がフラット化可能であるかどうかを決定します。 フラット化されたAmxNodeにはレンダリング関連の動作が含まれていない可能性があること、つまり、フラット化されたAmxNodeのタイプ・ハンドラは子の作成およびアクセスのみを制御でき、レンダリングには影響しないことに注意してください。
`adf.mf.api.amx.AmxNodeStates` | `getState` | なし | `AmxNode`の現在の状態を(`adf.mf.api.amx.AmxNodeStates`の定数値として)取得します。
`void` | `setState` | `state` | `AmxNode`の`adf.mf.api.amx.AmxNodeStates`状態を移行します。MAFまたは`AmxNode`のタイプ・ハンドラによってのみコールされる必要があります。
`HTMLElement` | `render` | なし | `AmxNode`をレンダリングします。 レンダリングされたルート要素、または`null` (子がレンダリングされない場合、またはこの`AmxNode`のタイプ・ハンドラがない場合)を返します。
`Array<HTMLElement>` | `renderDescendants` | `String facetName`、 `Object key` | この`AmxNode`のサブノードをレンダリングします(適用可能な場合、最も近い子孫にフラット化します)。 `facetName`が`null`でない場合は、ファセットの子をレンダリングします。facetNameが`null`の場合は、非ファセットの子がレンダリングされます。 オプションのキーが、そのスタンプ・キーの子`AmxNode`インスタンスのレンダリングに使用されます。 各`subNode`のルート要素の配列を返します。
`void` | `rerender` | なし | `AmxNode`を再レンダリングします。
`Boolean` | `isRendered` | なし | `AmxNode`の状態をチェックして、レンダリングする必要があるかどうかを確認します。 `AmxNode`は、`ABLE_TO_RENDER、RENDERED`または`PARTIALLY_RENDERED`状態である場合、レンダリング可能であるとみなされます。
`void` | `refresh` | `adf.mf.api.amx.AmxAttributeChange attributeChanges`、 `adf.mf.api.amx.AmxDescendentChanges descendentChanges` | `AmxNode`のDOMをリフレッシュします。 このメソッドは、`updateChildren`メソッドの後にコールされ、変更に応答してタイプ・ハンドラのDOMを更新する必要があるタイプ・ハンドラによって実装される必要があります。
`void` | `createStampedChildren` | `Object stampKey`、 `Array<String> facetNamesToInclude`、 `Function filterCallback` | カスタム`createChildrenNodes`関数内から子`AmxNode`インスタンスを作成するよう子にスタンプ設定するタイプ・ハンドラ用の便利な関数。 この関数では、任意のUIタグの子が作成されます。 `facetNamesToInclude`が空の場合、このスタンプのファセットは処理されません。`facetNamesToInclude`が`null`の場合、すべてのファセットが処理されます。`facetNamesToInclude`で`null`値が配列内に含まれる場合、非ファセット・タグの子が作成されます。 `filterCallback`は、作成された子をフィルタ処理するオプションの関数です。`filterCallback`関数は、`AmxNode`、`stampKey`、子タグおよびファセット名(または、非ファセットの場合は`null`)を設定して呼び出されます。`filterCallback`関数は`boolean`を返す必要があります。`true`の場合、タグを使用して子が作成され、`false`の場合、タグは処理されません。

### 19.2.5 AmxTagの使用方法

表19-5に、カスタムUIコンポーネントの作成に使用できる`AmxTag` APIを示します。

表19-5

戻り型 | 関数名 | パラメータ | 説明
--- | --- | --- | ---
`String` | `getNamespace` | なし | タグのXML名前空間URIを取得します。
`String` | `getNsPrefixedName` | なし | (ローカル`xmlns`接頭辞ではなく)名前空間をその接頭辞として含むタグ名を返します。 これは、`"http://xmlns.example.com/custom:custom"`などの完全なXML名です。
`String` | `getName` | なし | タグ名を取得します。 これは、接頭辞がないローカルXMLタグ名です。
`adf.mf.api.amx.AmxTag` | `getParent` | なし | 親タグ、または`null` (最上位タグである場合)を取得します。
`String` | `getTextContent` | なし | タグのテキスト・コンテンツを返します。
`Array<adf.mf.api.amx.AmxTag>` | `findTags` | `String namespace`、 `String tagName` | 指定された名前空間とタグ名を使用して、タグのタグ階層を再帰的に検索します。 一致した場合は現在のタグを返します。
`Array<adf.mf.api.amx.AmxTag>` | `getChildren` | `String namespace`、 `String tagName` | タグの子を取得します。 子の名前空間およびタグ名のオプションのフィルタリングを提供します。名前空間が`null`の場合は、すべての子が返されます。`tagName`が`null`の場合、子はタグ名でフィルタリングされません。
`Array<adf.mf.api.amx.AmxTag>` | `getChildrenFacetTags` | なし | すべての子ファセット・タグを取得します。 この関数の目的は、`AmxNode`プロセスの作成を支援することです。
`adf.mf.api.amx.AmxTag` | `getChildFacetTag` | `String name` | 指定された名前のファセット・タグを取得します。 この関数の目的は、ファセットの存在によりタイプ・ハンドラの動作が変更される場合のコードを支援することです。 ファセットが見つからない場合は`null`を返します。
`Array<adf.mf.api.amx.AmxTag>` | `getChildrenUITags` | なし | UIタグであるすべての子タグを取得します。 この関数の目的は、`AmxNode`プロセスの作成を支援することです。 この関数では、ファセット・タグは返されません。
`Array<String>` | `getAttributeNames` | なし | タグで指定されている属性のすべての属性名を取得します。
`Boolean` | `isAttributeElBound` | `String name` | 指定された属性が(静的値ではなく) EL式にバインドされているかどうかを決定します。
`String` | `getAttribute` | `String name` | 指定された名前の属性の属性値(EL文字列である場合があります)を取得します。 属性が指定されていない場合はundefinedを返します。
`Map<String, String>` | `getAttributes` | なし | 属性およびその値のキー/値ペア・マップを取得します。
`Boolean` | `isUITag` | なし | ノードがタイプ・ハンドラを持つUIタグであるかどうかを決定し、コンテンツをレンダリングします。
`Object{name:string, children:Array<adf.mf.api.amx.AmxTag>}` | `getFacet` | なし | このファセットの子のタグ、およびこのタグがファセット・タグである場合はファセットの名前を取得します。 これは、`AmxNode`ツリーを構築する場合に便利な関数です。 そのファセットの名前、およびファセットの子タグを持つオブジェクトを返します。タグが`amx:facet`タグでない場合は、`null`を返します。
`adf.mf.api.amx.AmxNode` | `buildAmxNode` | `adf.mf.api.amx.AmxNode parentNode`、 `Object stampKey` | スタンプIDを設定してこのタグの`AmxNode`の新しいインスタンスを作成します。 タグがファセット・タグである場合、タグは子タグの`AmxNode`を作成します。 この関数では、`AmxNode`は初期化されません。かわりに、初期化されていない`AmxNode`、または非UIタグの場合は`null`を返します。
`adf.mf.api.amx.TypeHandler` | `getTypeHandler` | なし | このタグのタイプ・ハンドラを取得します。

### 19.2.6 VisitContextの使用方法

表19-6に、カスタムUIコンポーネントの作成時に使用できる`VisitContext` APIを示します。

表19-6 VisitContext API

戻り型 | 関数名 | パラメータ | 説明
--- | --- | --- | ---
`Boolean` | `isVisitAll` | なし | すべてのノードがアクセスされるかどうかを決定します。
`Array<adf.mf.api.amx.AmxNode>` | `getNodesToWalk` | なし | アクセス時に移動する必要があるノードを取得します。 このリストには、アクセスされる(コールバックが呼び出される)必要があるノードは必ずしも含まれていません。
`Array<adf.mf.api.amx.AmxNode>` | `getNodesToVisit` | なし | アクセスするノードのリストを取得します。
`Array<adf.mf.api.amx.AmxNode>` | `getChildrenToWalk` | `adf.mf.api.amx.AmxNode parentAmxNode` | 指定された親`AmxNode`から移動する必要がある子AmxNodeインスタンス(ある場合はファセットを含む)を決定します。 タイプ・ハンドラに対して、すべての子に移動するわけではない場合に、子への移動方法の最適化を許可します。 `null`を返す場合があります。

### 19.2.7 AmxAttributeChangeの使用方法

表19-7に、カスタムUIコンポーネントの作成時に使用できる`AmxAttributeChange` APIを示します。

表19-7 AmxAttributeChange API

戻り型 | 関数名 | パラメータ | 説明
--- | --- | --- | ---
`Array<String>` | `getChangedAttributeNames` | なし | 現在の変更時に影響を受けた属性の名前を取得します。
`Boolean` | `isCollectionChange` | `String name` | 属性の変更がコレクション変更であるかどうかを決定します。
`adf.mf.api.amx.AmxCollectionChange` | `getCollectionChange` | `String name` | 属性のコレクション・モデル変更情報を取得します。使用可能な変更オブジェクトがない場合はnullを返します。
`String` | `getOldValue` | `String name` | 変更が行われる前に、属性の値を取得します。
`Boolean` | `hasChanged` | `String name` | 指定された名前の属性が変更されたかどうかを決定します。
`Number` | `getSize` | なし | 属性の変更数を取得します。

### 19.2.8 AmxDescendentChangesの使用方法

表19-8に、カスタムUIコンポーネントの作成時に使用できる`AmxAttributeChange` APIを示します。

表19-8 AmxDescendentChanges API

戻り型 | 関数名 | パラメータ | 説明
--- | --- | --- | ---
`Array<adf.mf.api.amx.AmxNode>` | `getAffectedNodes` | なし | レンダリング前の変更済の子孫`AmxNode`インスタンスを取得します。
`adf.mf.api.amx.AmxAttributeChange` | `getChanges` | `adf.mf.api.amx.AmxNode amxNode` | 指定されたAmxNodeの変更を取得します。
`adf.mf.api.amx.AmxNodeStates` | `getPreviousNodeState` | `adf.mf.api.amx.AmxNode amxNode` | 変更が適用される前の子孫AmxNodeの状態を取得します。

### 19.2.9 AmxCollectionChangeの使用方法

表19-9に、カスタムUIコンポーネントの作成時に使用できる`AmxCollectionChange` APIを示します。

表19-9 AmxCollectionChange API

戻り型 | 関数名 | パラメータ | 説明
--- | --- | --- | ---
`Boolean` | `isItemized` | なし | コレクションに対する変更を項目化できるかどうか、つまりそのコレクションのキーと要素が特定されることで、`TypeHandler`が最初からリスト全体を再レンダリングするのではなく、適切な項目だけを更新できるようにするかどうかを決定します。
`Array<String>` | `getCreatedKeys` | なし | 作成されたキーの配列、または変更を項目化できない場合は`null`を取得します。
`Array<String>` | `getDeletedKeys` | なし | 削除されたキーの配列、または変更を項目化できない場合はnullを取得します。
`Array<String>` | `getUpdatedKeys` | なし | 更新されたキーの配列、または変更を項目化できない場合はnullを取得します。
`Array<String>` | `getDirtiedKeys` | なし | ダーティにされたキーの配列、または変更を項目化できない場合はnullを取得します。

### 19.2.10 AmxNodeChangeResultの使用方法

表19-10に、カスタムUIコンポーネントの作成時に使用できる`AmxNodeChangeResult` APIを示します。

表19-10 AmxNodeChangeResult API

メンバー | 説明
--- | ---
`adf.mf.api.amx.AmxNodeChangeResult["NONE"]` | レンダリング前の子孫`AmxNode`での属性変更に対してアクションを実行しません。
`adf.mf.api.amx.AmxNodeChangeResult["REFRESH"]` | 属性およびその子AmxNodeインスタンスがタイプ・ハンドラによって更新済で、DOMはタイプ・ハンドラの`refresh`関数によって更新されます。
`adf.mf.api.amx.AmxNodeChangeResult["RERENDER"]` | AmxNodeおよびその子AmxNodeインスタンスがタイプ・ハンドラによって更新済ですが、DOMは、`AmxNode`階層を変更する必要がないため、`refresh`関数がタイプ・ハンドラでコールされない場合にのみ再作成する必要があります。
`adf.mf.api.amx.AmxNodeChangeResult["REPLACE"]` | タイプ・ハンドラは変更を処理できません。DOMおよび`AmxNode`階層が再作成される必要があります。 この値は、タイプ・ハンドラの`updateChildren`メソッドからのみ返され、`getDescendentChangeAction`メソッドからは返されません。

### 19.2.11 AmxNodeStatesの使用方法

表19-11に、カスタムUIコンポーネントの作成時に使用できる`AmxNodeStates` APIを示します。

表19-11 AmxNodeStates API

メンバー | 説明
--- | ---
`adf.mf.api.amx.AmxNodeStates["INITIAL"]` | 初期状態。`AmxNode`が作成されていますが、移入されていません。
a`df.mf.api.amx.AmxNodeStates["WAITING_ON_EL_EVALUATION"]` | レンダリングに必要なELベースの属性がまだ完全にロードされていません。
`adf.mf.api.amx.AmxNodeStates["ABLE_TO_RENDER"]` | EL属性がロードされていますが、`AmxNode`はまだレンダリングされていません。
`adf.mf.api.amx.AmxNodeStates["PARTIALLY_RENDERED"]` | ELはまだ完全にロードされていませんが、`AmxNode`はそれ自体を部分的にレンダリングしています(今後使用するために予約されています)。
`adf.mf.api.amx.AmxNodeStates["RENDERED"]` | `AmxNode`は完全にレンダリングされています。
`adf.mf.api.amx.AmxNodeStates["UNRENDERED"]` | AmxNodeはレンダリングされません。

### 19.2.12 AmxNodeUpdateArgumentsの使用方法

表19-12に、カスタムUIコンポーネントの作成時に使用できる`AmxNodeUpdateArguments`のAPIをリストします。

表19-12 AmxNodeUpdateArguments API

戻り型 | 関数名 | パラメータ | 説明
--- | --- | --- | ---
`Array<adf.mf.api.amx.AmxNode>` | `getAffectedNodes` | なし | 影響を受ける`AmxNode`インスタンスの配列を取得します。
`Map<String,Boolean>` | `getAffectedAttributes` | `String amxNodeId` | 指定されたAmxNode IDの影響を受ける属性を表すオブジェクトを取得します。
`Map<String,adf.mf.api.amx.AmxCollectionChange>` | `getCollectionChanges` | `String amxNodeId` | 指定されたAmxNodeおよびプロパティのコレクション変更を取得します。 返されるマップは属性名によってキー設定されます。 `AmxNode`に変更がない場合はundefinedを返します。
`void` | `setAffectedAttribute` | `adf.mf.api.amx.AmxNode amxNode`、 `String attributeName` | 影響を受けたとしてAmxNodeの属性をマークします。
`void` | `setCollectionChanges` | `String amxNodeId`、 `String attributeName`、 `adf.mf.api.amx.AmxCollectionChange collectionChanges` | 指定された`AmxNode`の属性のコレクション変更を設定します。

## 19.3 カスタム・コンポーネントの作成

JavaScriptおよびMAF APIを使用して、カスタムUIコンポーネントを作成できます。このコンポーネントのJavaScriptファイルは、アプリケーション機能レベル包含を使用して、プロジェクトに追加できます。カスタム・タグ・ライブラリを追加すると、タグ・ライブラリの「コンポーネント」ウィンドウのリストに入力され、このライブラリが選択された場合は、カスタム・コンポーネントが「コンポーネント」ウィンドウで使用可能になり、その属性が「プロパティ」ウィンドウに表示されます。

始める前に

第19.2項「MAF APIを使用したカスタム・コンポーネントの作成」で説明されているAPIについて理解しておいてください。

カスタム・コンポーネントを作成するには、次の手順を実行します。

1. `adf.mf.api.amx.TypeHandler.register` API (表19-1「静的API」および例19-1「カスタム・コンポーネントのJavaScriptファイル」を参照)を使用して、タグ名前空間および1つ以上の一連のタイプ・ハンドラを登録するJavaScriptファイルを生成します。

2. 各タイプ・ハンドラで、レンダリング・メンバー関数を実装します。

3. オプションで、他の関数を実装します。

4. 1つ以上のJavaScriptおよびCSSファイルをMAF AMXアプリケーション機能に添付します。たとえば、開発コンピュータ上の``jdev_install`/jdeveloper/jdev/extensions/oracle.maf/Samples`ディレクトリ内の`PublicSamples.zip`ファイルに配置されている、次のサンプル・アプリケーションを参照してください。

   - CompGalleryという名前のMAFサンプル・アプリケーションに含まれる`custom.js`および`custom.css`ファイル。

   - WorkBetterサンプル・アプリケーションにはカスタム検索コンポーネントが含まれています。

   または、デザインタイム・パッケージングを実行できます。

5. いずれかのカスタム・コンポーネントを使用する各MAF AMXページで、`view`要素の`xmlns`エントリを追加します。

       xmlns:custom="http://xmlns.example.com/custom"

例19-1は、カスタム・コンポーネントを宣言するJavaScriptファイルを示しています。

例19-1 カスタム・コンポーネントのJavaScriptファイル

    (function() {
       // TypeHandler for custom "x" elements
       var x = adf.mf.api.amx.TypeHandler.register("http://xmlns.example.com/custom",
                                                   "x");
       x.prototype.render = function(amxNode) {
          var rootElement = document.createElement("div");
          rootElement.appendChild(document.createTextNode("Hello World"));
          return rootElement;
       };

       // TypeHandler for custom "y" elements
       var y = adf.mf.api.amx.TypeHandler.register("http://xmlns.example.com/custom",
                                                   "y");

       y.prototype.render = function(amxNode) {
          var rootElement = document.createElement("div");
          rootElement.appendChild(document.createTextNode("Goodbye World"));
          return rootElement;
       };

    })();

カスタムUIコンポーネントの作成方法の例については、CompGalleryという名前のMAFサンプル・アプリケーションに含まれる`custom.amx`、`customOther.amx`、`exampleEvents.amx`および`exampleList.amx`の各ファイルを参照してください。これらのサンプル・アプリケーションは、開発コンピュータ上の``jdev_install`/jdeveloper/jdev/extensions/oracle.maf/Samples`ディレクトリ内の`PublicSamples.zip`ファイル内にあります。