Interops
Knockout
Base
5.20241.9
Wijmo API Module wijmo.knockout.base Wijmo API モジュール

wijmo.knockout.base モジュール

Wijmoコントロール用のKnockoutJS連結が含まれています。

連結により、HTMLページで簡単なマークアップを使用して KnockoutJS アプリケーションにWijmoコントロールを追加できます。

Wijmoコントロールをページのマークアップ内で特定の位置に追加するには、 <div> 要素を追加し、 data-bind 属性でコントロールの連結を定義します。 連結名は、「wj」プレフィックスを持つコントロール名に対応します。 たとえば、wjInputNumber連結では、 Wijmo InputNumber コントロールを表します。 連結の値は、コントロールの読み取り/書き込みプロパティとイベント名に対応する プロパティを含むオブジェクトリテラルです。 また、それらの値は対応するコントロールのプロパティ値とイベントハンドラーを定義します。

次のマークアップでは、valueプロパティがビューモデルの theValueプロパティに連結され、stepプロパティが1に設定され、 およびinputTypeプロパティが 「text」に設定されている Wijmo InputNumberコントロールを作成します。

<div data-bind="wjInputNumber: { value: theValue, step: 1, inputType: 'text' }"></div>

カスタムの要素

標準のKnockout連結構文の代わりに、WijmoのKnockoutでは、ページのマークアップ内のコントロールをカスタム要素として宣言することができます。 この場合、タグ名はコントロールの連結名、および属性名はコントロールのプロパティ名を表します。 要素名とパラメータ名は、キャメルケースではなく、ダッシュ付きの小文字として書式設定する必要があります。 上記の例のコントロールは、カスタム要素構文を使用して次のように定義できます。 
<wj-input-number value="theValue" step="1" input-type="'text'"></wj-input-number>

属性値は、データ連結の定義で使用される値と同じJavaScript式構文を使用して定義する必要があります。 WijmoのKnockoutプリプロセッサーは、そのような要素を通常ののデータ連結形式に変換します。 詳細については、 カスタムの要素のプリプロセッサー を参照してください。

コントロールプロパティへの連結

KnockoutJSのWijmo連結は、コントロールの読み取り/書き込みプロパティへの連結をサポートします。 プロパティには、有効なKnockoutJS式（定数、ビューモデルの監視可能なプロパティ、複雑な式など）を割り当てることができます。

連結の式は、対応するWijmo JavaScriptコントロールが理解できる純粋なJavaScript値に（<;b>ko.unwrap(expression) を呼び出した後）解決する必要があることに注意してください。 これは、Wijmoコントロールの itemsSource これは、Wijmoコントロールの observableArray, 、または項目のプロパティがKnockout observableである配列に連結できないことを意味します。

ほとんどのプロパティは一方向の連結を提供します。 これは、連結された監視可能なビューモデルプロパティの変更により、監視可能なビューが連結されているコントロールのプロパティが変更されるが、その逆は発生しないことを意味します。 ただし、一部のプロパティは双方向バインディングをサポートしています。つまり、コントロールのプロパティで行われた変更は、コントロールプロパティに連結されている監視可能オブジェクトにも反映されます。 双方向連結は、コントロール自体、ユーザー操作、またはその他の操作によって変更できるプロパティに使用されます。 たとえば、InputNumberコントロールは、valueおよびtextプロパティに対して双方向連結を提供します。これらのプロパティは、ユーザーが新しい値を入力しているときに変更されます。 残りのInputNumberプロパティは、一方向バインディングモードで動作します。

コントロールイベントへの連結

コントロールイベントにハンドラーをアタッチするには、 コントロールの連結を定義するオブジェクトリテラルのプロパティとしてイベント名を指定し、 このプロパティの値としてこのイベントで呼び出す関数を指定します。 Wijmo連結は、click>やeventのような組み込みのKnockoutJS連結に使用されるのと同じイベントハンドラーの定義ルールに従います。 イベントハンドラーは、指定された順序で次のパラメーターのセットを受け取ります。
  • data: 現在のモデル値。 clickやeventなどのネイティブKnockoutJSバインディングの場合と同じです。
  • sender: イベントの送信者。
  • args: イベントの引数。

次の例では、 InputNumber コントロールを作成し、新しいコントロール値のダイアログを示す valueChanged イベントのハンドラを追加します。

<!-- HTML -->
<div data-bind="wjInputNumber: { value: theValue, step: 1, valueChanged: valueChangedEH }"></div>
 
//ビューモデル
this.valueChangedEH = function (data, sender, args) {
    alert(‘新しい値: ' + sender.value);
}

カスタムの要素構文を使用して定義されているInputNumberコントロール：

<wj-input-number value="theValue" step="1" value-changed="valueChangedEH"></wj-input-number>

未定義の監視可能なプロパティへの連結

ビューモデルの監視可能なプロパティがundefinedの値に割り当てられている場合、 初期化するときにWijmo連結によって特別に処理されます。 たとえば、ko.observable（undefined）またはko.observable（）としてオブザーバブルを作成し、 コントロールプロパティに連結した場合、Wijmoはコントロールに値を割り当てません。 これは、双方向連結をサポートするプロパティのコントロールのデフォルト値でオブザーバブルを初期化する方法です。 なぜなら、初期化後、コントロール連結は、連結されたオブザーバブルをそのようなプロパティのコントロール値で更新するためです。

null値を持つオブザーバブル、たとえば ko.observable（null）は通常どおり処理され、連結されているコントロールプロパティにnullを割り当てます。 一次初期化が完了した後、未定義の値を持つオブザーバブルはWijmoから通常の処理を取得し、 未定義のコントロールプロパティを割り当てます。

次の例では、InputNumber コントロールのvalueプロパティの初期値はデフォルト値0であり、 この値がビューモデルの theValue プロパティに割り当てられます。

<!-- HTML -->
<div data-bind="wjInputNumber: { value: theValue }"></div>
 
//ビューモデル
this.theValue = ko.observable();

複雑なオブジェクトと配列のプロパティの定義

一部のWijmoコントロールには、配列または複雑なオブジェクトを含むプロパティがあります。たとえば、 FlexChart コントロールは、Axisオブジェクトを表す axisX プロパティとaxisY プロパティを公開します。 また、 series プロパティは、 Series オブジェクトの配列です。 この場合、 Wijmoは、コントロール要素の子要素に追加する特別な連結を提供します。 コントロールが同じ複合型の複数のプロパティを公開する場合、 複合型の連結の wjPropertyプロパティは、定義されているコントロールプロパティを指定します。

次の例は、axisXおよびaxisYプロパティと2つのシリーズオブジェクトを含む FlexChartを作成するために使用されるマークアップを示しています。

<div data-bind="wjFlexChart: { itemsSource: data, bindingX: 'country' }">
    <div data-bind="wjFlexChartAxis: { wjProperty: 'axisX', title: chartProps.titleX }"></div>
    <div data-bind="wjFlexChartAxis: { wjProperty: 'axisY', title: chartProps.titleY }"></div>
    <div data-bind="wjFlexChartSeries: { name: 'Sales', binding: 'sales' }"></div>
    <div data-bind="wjFlexChartSeries: { name: 'Downloads', binding: 'downloads' }"></div>
</div>

カスタム要素構文を使用して定義されているFlexChartコントロール：

<wj-flex-chart items-source="data" binding-x="'country'">
    <wj-flex-chart-axis wj-property="'axisX'" title="chartProps.titleX"></wj-flex-chart-axis>
    <wj-flex-chart-axis wj-property="'axisY'" title="chartProps.titleY"></wj-flex-chart-axis>
    <wj-flex-chart-series name="'Sales'" binding"'sales'"></wj-flex-chart-series>
    <wj-flex-chart-series name="'Downloads'" binding"'downloads'"></wj-flex-chart-series>
</wj-flex-chart>

control プロパティ

各Wijmoコントロールの連結は、連結によって作成されたWijmoコントロールインスタンスを参照する control プロパティを公開します。 これにより、ビューモデルコードまたは他の連結でコントロールを参照できます。

たとえば、次のマークアップは、ビューモデルのflex監視可能プロパティに参照が格納され、 ボタンクリックイベントハンドラーで次のレコードに移動するために使用されるFlexGridコントロールを作成します。

<!-- HTML -->
<div data-bind="'wjFlexGrid': { itemsSource: data, control: flex }"></div>
<button data-bind="click: moveToNext">Next</button>
 
//ビューモデル
this.flex = ko.observable();
this.moveToNext = function () {
    this.flex().collectionView.moveCurrentToNext();
}

initialized イベント

各Wijmoコントロールの連結は、initializedイベントとブール値isInitializedプロパティを公開します。 イベントは、連結がコントロールを作成し、 連結属性で指定された値で完全に初期化した直後に発生します。 子連結を含む連結の場合、たとえば、子wjFlexGridColumn連結を持つwjFlexGridがあるとすると、 子連結は完全に初期化され、親連結によって表されるコントロールに適用されます。 isInitializedプロパティは、 initializedイベントが発生する直前にtrueに設定されます。 その値にアクセスするには、ビューモデルの監視可能なプロパティを連結のisInitializedプロパティに連結します。

次の例では、コントロールが連結により、完全に初期化された後にFlexGridColumnの書式設定を調整します。 これにより、書式設定が連結で定義されている書式設定で上書きされないことを確認します。

<!-- HTML -->
<div data-bind="'wjFlexGrid': { itemsSource: dataArray, initialized: flexInitialized }">
     <div data-bind="wjFlexGridColumn: { binding: 'sales', format: 'n2' }"></div>
     <div data-bind="wjFlexGridColumn: { binding: 'downloads', format: 'n2' }"></div>
</div>
 
//ビューモデル
this.flexInitialized = function (data, sender, args) {
    var columns = sender.columns;
    for (var i = 0; i < columns.length; i++) {
        if (columns[i].dataType = wijmo.DataType.Number) {
            columns[i].format = 'n0’;
        }
    }
}

id="custom_elem_preproc">カスタム要素プリプロセッサ

Wijmo Knockoutプリプロセッサーは、標準の Knockout ko.bindingProvider.instance.preprocessNode APIを使用します。 これにより、同じページで他のカスタムプリプロセッサが使用されている場合に問題が発生する可能性があります。 なぜなら、Knockoutはプリプロセッサ関数をアタッチするための単一のインスタンスプロパティを提供し、 次に登録するプリプロセッサは前のプリプロセッサの登録を削除するためです。

Wijmo Knockoutプリプロセッサーは、接続されている別のプリプロセッサーを保持するために、 初期化中に現在登録されているプリプロセッサーを保存し、別の処理中のノードがWijmoコントロール要素として認識されない場合に、 そのプリプロセッサーに作業を委任します。 ただし、Wijmo Knockoutのプリプロセッサーの後に（つまり、<script>がwijmo.knockout.jsモジュールを参照した後に) 別のプリプロセッサーを登録する場合は、他のプリプロセッサーが同様に動作することを確認する必要があります。 それ以外の場合、Wijmo Knockoutプリプロセッサは無効になります。

Wijmo Knockoutプリプロセッサを無効にする場合は、 wijmo.knockout.jsモジュール参照の前とWijmoコアモジュールへの参照を指定した後で、 wijmo.disableKnockoutTagsプロパティをfalseに設定します。 以下に例を示しています。

<script src="scripts/wijmo.js"></script>
<script src="scripts/wijmo.input.js"></script>
<script>
    wijmo.disableKnockoutTags = true;
</script>
<script src="scripts/wijmo.knockout.js"></script>

この場合、Wijmoのカスタム要素は認識されないため、ページマークアップにWijmoコントロールを追加する場合は、 通常のデータ連結構文しか使用できないことに注意してください。