プライマリ・コンテンツに移動

Oracle® Application Express APIリファレンス リリース5.1 E85937-02 |
| 目次 | 索引

前 | 次 |

# 31.10 apex.region

`apex.region` APIによって、共通リージョンに関連するApplication Express機能すべてに単一のインタフェースが提供されます。このAPIでApplication Expressリージョン・オブジェクトを戻し、それをリージョン関連のファンクションおよびプロパティにアクセスするために使用できます。

- apex.region
- apex.region.create
- apex.region.destroy
- apex.region.isRegion
- apex.region.findClosest

## 31.10.1 apex.region

このAPIは、指定されたリージョンIDについて、Application Expressリージョン・オブジェクトを戻します。戻されたリージョン・オブジェクトを使用すると、リージョン関連のファンクションとプロパティにアクセスできます。

プラグイン開発者は、`apex.region.create`をコールしてリージョンの動作を定義できます。

パラメータ

表31-51 apex.region

名前 | タイプ | 説明
--- | --- | ---
`pRegionId` | String | リージョンIDまたはリージョンの静的ID。JavaScriptから使用する予定の場合は、リージョンに静的IDを指定することをお薦めします。指定しない場合は、内部生成されるIDが使用されます。リージョン・テンプレートでは、`#REGION_STATIC_ID#`文字列を使用してリージョンIDが置き換えられます。リージョンIDは、ブラウザでページのソースを表示すると確認できます。

戻り値

リージョン・オブジェクトが戻されるか、pRegionIdに等しいIDのDOM要素がない場合にはnullが戻されます。リージョン・オブジェクトには、次のプロパティとメソッドがあります。

- focus

- refresh

- widget

特定のリージョンでは、追加のプロパティまたはファンクションがある場合もあります。追加のプロパティまたはファンクションを文書化するどうかは、リージョン・プラグイン次第です。

例

これは、単独では使用されず、次に示す各APIで説明されているように、アイテム固有のファンクションおよびプロパティにアクセスするために使用されます。

参照:

apex.region.create

- focus
- refresh
- widget

### 31.10.1.1 focus

このリージョン・オブジェクト・ファンクションの機能で、Application Expressリージョンがフォーカスを取得します。ネイティブまたはプラグイン・リージョンが、すべてフォーカスの取得に対応しているわけではありません。フォーカスがどこに移動するかは、各リージョンによって異なります。デフォルト動作では、フォーカスはリージョンでタブ移動が可能な最初の要素に設定されます。タブ・ストップが1回(または指定された回数)になるようフォーカスを管理しているリージョンもあり、その場合はそのリージョン内でユーザーが直前にフォースを置いた位置にフォーカスが置かれる場合があります。

パラメータ

なし

例

次の例では、`myRegion`という静的IDのリージョンがフォーカスを取得します。

    var region = apex.region( "myRegion" );
    region.focus();

### 31.10.1.2 refresh

このリージョン・オブジェクト・ファンクションは、Application Expressリージョンをリフレッシュします。通例はこのとき、サーバーからコンテンツまたはデータが更新されます。ネイティブまたはプラグイン・リージョンが、すべてリフレッシュに対応しているわけではありません。

注意:

リージョンをレガシー的にリフレッシュする場合、つまりリージョン要素に対して`apexrefresh`イベントをトリガーする場合には、このファンクションを使用する必要があります。このように旧式の動作をとるリージョンの場合、リフレッシュのデフォルト実装で`apexrefresh`イベントがトリガーされます。

パラメータ

なし

例

次の例では、`myRegion`という静的IDのリージョンをリフレッシュします。

    var region = apex.region( "myRegion" );
    region.refresh();

### 31.10.1.3 widget

このリージョン・オブジェクト・ファンクションは、Application Expressリージョンに関連付けられたウィジェットを戻します。または、リージョンにウィジェットが実装されていない場合にはnullを戻します。カレンダ、対話グリッド、ツリーなど高度なリージョン・タイプは、ウィジェットを使用して実装されます。このファンクションは通例、ウィジェット要素のjQueryオブジェクトを戻すことによってウィジェットを利用します。このとき、jQueryオブジェクトでウィジェットのメソッドをコールできます。

パラメータ

なし

例

次の例では、`interactiveGrid`ウィジェットにアクセスするリージョン・ウィジェット・ファンクションを使用し、次に行追加アクションを呼び出して、インタラクティブ・グリッドに行を追加します。

    apex.region( "myGridRegion" ).widget().interactiveGrid( "getActions" ).invoke( "add-row" )

## 31.10.2 apex.region.create

このファンクションは、リージョン・プラグインの開発者専用です。そのリージョンについて、プラグイン固有の実装を提供します。

パラメータ

表31-52 apex.region.create

名前 | タイプ | 説明
--- | --- | ---
`pRegionId` | String | リージョンIDまたはリージョンの静的ID。JavaScriptから使用する予定の場合は、リージョンに静的IDを指定することをお薦めします。指定しない場合は、内部生成されるIDが使用されます。リージョン・テンプレートでは、`#REGION_STATIC_ID#`文字列を使用してリージョンIDが置き換えられます。リージョンIDは、ブラウザでページのソースを表示すると確認できます。
`pRegionImpl` | Object | リージョンのファンクションおよびプロパティを提供するオブジェクト。文字列タイプのプロパティを提供する必要があります。開発者にとって便利な任意の機能を追加できます。標準のファンクションまたはプロパティが省略されている場合は、デフォルトの実装が提供されます。

例

仮想的なリージョン・プラグインのリージョン初期化コードがどのように動作するかを示すための例、次に示します。

    function initFancyList( pRegionId, … ) {
        …
        apex.region.create( pRegionId, {
            type: "FancyList",
            focus: function() {
                /* code to focus region */
            },
            refresh: function() {
                /* code to refresh region */
            }
        });
    }

## 31.10.3 apex.region.destroy

このファンクションは、リージョン・プラグインの開発者専用です。リージョン要素に関連する動作を破棄して削除します。リージョン要素をDOMから削除することはありません。ページが存続する間リージョンが存在する場合、このファンクションをコールする必要はありません。destroyメソッドを持つウィジェットによってリージョンが実装される場合は、ウィジェットを破棄する際にこのファンクションをコールできます。

パラメータ

表31-53 apex.region.destroy

名前 | タイプ | 説明
--- | --- | ---
`pRegionId` | String | リージョンIDまたはリージョンの静的ID。JavaScriptから使用する予定の場合は、リージョンに静的IDを指定することをお薦めします。指定しない場合は、内部生成されるIDが使用されます。リージョン・テンプレートでは、`#REGION_STATIC_ID#`文字列を使用してリージョンIDが置き換えられます。リージョンIDは、ブラウザでページのソースを表示すると確認できます。

例

リージョンを破棄しても、ページ・コールにリージョン要素が残っているという例を、次に示します。

    apex.region.destroy( someRegionId );

## 31.10.4 apex.region.isRegion

このファンクションは、`pRegionId`にIDが等しく、`apex.region.create`によってそこにリージョンが作成されているDOM要素がある場合にのみ、trueを戻します。(`apex.region.create`をコールして)リージョン・インタフェースを実装しない旧式のリージョンをサポートするために、`apex.region`のデフォルトの実装では、Application Expressリージョンであるかのように、IDを指定して任意のDOM要素を作成しようとします。このファンクションを使用すると、trueのApplication Expressリージョンを任意のDOM要素から区別できます。

パラメータ

表31-54 apex.region.isRegion

名前 | タイプ | 説明
--- | --- | ---
`pRegionId` | String | リージョンIDまたはリージョンの静的ID。JavaScriptから使用する予定の場合は、リージョンに静的IDを指定することをお薦めします。指定しない場合は、内部生成されるIDが使用されます。リージョン・テンプレートでは、`#REGION_STATIC_ID#`文字列を使用してリージョンIDが置き換えられます。リージョンIDは、ブラウザでページのソースを表示すると確認できます。

戻り値

`pRegionId`が、リージョン・インタフェースを実装するApplication Expressリージョンの場合は`true`を戻し、それ以外の場合は`false`を戻します。

例

次の例では、Application Expressリージョンである場合にのみリージョンにフォーカスを当てます。

    if ( apex.region.isRegion( someId ) ) {
        apex.region( someId ).focus();
    }

## 31.10.5 apex.region.findClosest

`pTarget`要素を含むリージョンを戻します。`pTarget`要素がない場合、または`apex.region.create`をコールして初期化されたリージョンではない場合、nullを戻します。

パラメータ

表31-55 apex.region.findClosest

名前 | タイプ | 説明
--- | --- | ---
`pTarget` | DOM要素 | 文字列 | jQueryファンクションの第1引数として適切なDOM要素またはCSSセレクタ。

戻り値

リージョン・オブジェクトが戻されるか、`pTarget`に対応する要素がリージョン内部にない場合にはnullが戻されます。リージョン・オブジェクトの詳細は、`apex.region`の戻り値を参照してください。

例

次の例では、`.refresh-button`クラスのボタンを含むリージョンを、ボタンのクリック時にリフレッシュします。

    apex.jQuery( ".refresh-button" ).click( function( event ) {
        var region = apex.region.findClosest( event.target );
        if ( region ) {
            region.refresh();
        }
    });