From ad307804c6a502fb65e4be88b7e0ea9ec91860a4 Mon Sep 17 00:00:00 2001 From: icho Date: Wed, 20 Dec 2017 01:06:18 +0900 Subject: [PATCH] Translate data-system.md via GitLocalize --- .../ja/2.0/docs/devguide/data-system.md | 274 ++++++++---------- 1 file changed, 128 insertions(+), 146 deletions(-) diff --git a/app/_locales/ja/2.0/docs/devguide/data-system.md b/app/_locales/ja/2.0/docs/devguide/data-system.md index 2222ba2ed9..a77a77ce59 100644 --- a/app/_locales/ja/2.0/docs/devguide/data-system.md +++ b/app/_locales/ja/2.0/docs/devguide/data-system.md @@ -16,15 +16,15 @@ table.config-summary td { } -Polymerでは、エレメントのプロパティの変更を監視(observe)し、データ変更に基づき様々なアクションを実行することができます。これらのアクションや、*プロパティエフェクト*(property effects)には、次のものがあります。 +Polymerは、エレメントのプロパティに対する変更を監視(observe)し、データ変更に基づく様々なアクションの実行を可能にします。これらのアクションや、*プロパティエフェクト*(property effects)には、次のものが含まれます。 -* オブザーバー(observers):データの変更時に呼び出されるコールバック +- オブザーバー(observers):データの変更時に呼び出されるコールバック -* 算出プロパティ(computed properties):他のプロパティに基づき算出され、入力データが変更されたときに再計算が行われる仮想的なプロパティ。 +- 算出プロパティ(computed properties):他のプロパティに基づき算出され、入力データが変更されると再計算が行われる仮想的なプロパティ -* データバインディング(data binding):データが変更されたとき、DOMノードのプロパティまたは属性、テキストコンテンツをアップデートするアノテーション。 +- データバインディング(data binding):データが変更されたとき、DOMノードのプロパティまたは属性、テキストコンテンツをアップデートするアノテーション -各Polymer Elementは、独自のデータモデルとローカルDOMエレメントを管理します。エレメントのモデルとは、エレメントのプロパティです。データバインディングは、エレメントのモデルをローカルDOM内のエレメントとリンクします。 +Polymer Elementは、それぞれ独自のデータモデルとローカルDOMエレメントを管理します。エレメントの*モデル*とは、エレメントのプロパティのことです。データバインディングは、エレメントのモデルをローカルDOM内のエレメントとリンクします。 非常にシンプルなエレメントについて考えてみましょう。: @@ -52,12 +52,11 @@ which contains a single element, div. An arrow labeled 3 connects the JavaScript div element.](/images/1.0/data-system/data-binding-overview-new.png) 1. ``エレメントは、JavaScriptオブジェクトを参照する`name`プロパティを持っている。 -2. ``エレメントは、`
`を一つだけ持ったローカルDOMのホストになる。 -3. テンプレート内のデータバインディングは、Javascriptオブジェクトを`
`エレメントにリンクする。 +2. ``エレメントは、`
`を一つだけ持ったローカルDOMツリーの*ホスト*になる。 +3. テンプレート内のデータバインディングは、Javascriptオブジェクトを`
`エレメントにリンクする。 データシステムは、オブジェクトではなくパスに基づいており、パスはホストエレメントに関連するプロパティやサブプロパティを表します。例えば、``エレメントは、パス`name.first`とパス`name.last`に対するデータバインディングを持っています。仮に、``エレメントが`name`プロパティとして次のオブジェクトを持っている場合: - ```js { first: 'Lizzy', @@ -73,67 +72,64 @@ labeled 2 connect the paths name and name.first with the object itself and the s first, respectively.](/images/1.0/data-system/paths-overview-new.png) 1. `name`プロパティはJavascirptのオブジェクトを参照します。 -2. パス`name`はそのオブジェクト自身を参照します。パス`name.first`はサブプロパティ`first`(文字列`Lizzy`)を参照します。 +2. パス`name`はオブジェクトそのものを参照します。パス`name.first`はサブプロパティ`first`(文字列`Lizzy`)を参照します。 -Polymerは自動ですべてのデータ変更を検出するわけではありません。*プロパティエフェクト*は、プロパティまたはサブプロパティへ[監視可能(obsevable)な変更](#observable-changes)があった場合に生じます。 +Polymerはすべてのデータ変更を自動で検出するわけではありません。*プロパティエフェクト*は、プロパティまたはサブプロパティへ[*監視可能(obsevable)な変更*](#observable-changes)があった場合に生じます。 -**なぜパスを使うのでしょうか?**パスや*監視可能(obsevable)な変更*は、初めは少し奇妙にみえるかもしれません。しかし、これらによって、非常にハイパフォーマンスなデータバインディングシステムが実現されています。*監視可能(observable)な変更*が発生した場合、PolymerはDOM内で、その変更によって影響を受ける箇所にだけ変更を加えることができます。 +**なぜパスを使うのでしょうか?**パスや*監視可能(obsevable)な変更*は、初めは少し奇妙にみえるかもしれません。しかし、これらによって、非常にハイパフォーマンスなデータバインディングシステムを実現しています。*監視可能(observable)な変更*が発生した場合、PolymerはDOM内で、その変更によって影響を受ける箇所にだけ変更を加えることができます。 { .alert .alert-info } 要約: -* 単一のJavaScriptオブジェクトや配列は複数のエレメントから参照するこができますが、パスは**常に特定のエレメントに関連づけられます**。 -* あるパスに対して**監視可能(observable)な変更**があると、バインドされた値の更新やオブザーバーの呼び出しといった**プロパティエフェクト**を発生させます。 -* データバインディングは、異なるエレメント上のパス間にコネクションを確立します。 +- 一つのJavaScriptオブジェクトや配列を複数のエレメントから参照するこはできますが、パスは**常に特定のエレメントに関連づけられます**。 +- あるパスに対して**監視可能(observable)な変更**があると、バインドされた値の更新やオブザーバーの呼び出しといった**プロパティエフェクト**が生じます。 +- データバインディングは、異なるエレメント上のパス間にコネクションを確立します。 ## 監視可能(observable)な変更 {#observable-changes} -*監視可能(observable)な変更*とは、**Polymerがパスに関連付けることができるデータの変更**です。以下のような変更については自動的に監視することができます。: +*監視可能(observable)な変更*とは、**Polymerがパスに関連付けることができるデータの変更**です。以下のような変更については自動的に監視可能(observable)です。: -* エレメントのプロパティに直接設定する。 +- エレメントのプロパティに直接設定する。 - ~~~javascript - this.owner = 'Jane'; - ~~~ + `this.owner = 'Jane';` - もし、あるプロパティに関連した*プロパティエフェクト*が発生した場合(オブザーバー、算出プロパティやデータバインディングなど)、Polymerはプロパティエフェクトを自動的に発生させるプロパティに対してsetterメソッドを作成します。 + もし、あるプロパティに関連する*プロパティエフェクト*が発生した場合(オブザーバー、算出プロパティやデータバインディングなど)、Polymerはそのプロパティにsetterメソッドを生成し、プロパティエフェクトを自動で発生させるようにします。 -* 双方向データバインディングを使用してエレメントのサブプロパティを設定する。 +- 双方向データバインディングを使用してエレメントのサブプロパティを設定する。 - ~~~html + ```html - ~~~ - - データバインディングシステムによってもたらされた変更は、自動的に伝播されます。この例で言えば、``エレメントが自身の`name`プロパティに変更を加えると、パス`hostProperty.subProperty`に変更が行われたように、その変更をホストに向けて上に伝播します。 + ``` + データバインディングシステムによってもたらされた変更は、自動的に伝播されます。この例で言えば、``エレメントが自身の`name`プロパティに変更を加えると、パス`hostProperty.subProperty`に変更が行われたように、その変更をホストに向けて上位へ伝播します。 ### 監視不能(unobservable)な変更 -**オブジェクトまたは配列を命令的に変更した場合は、監視することができません**。例えば、以下のような場合です。: +**オブジェクトまたは配列への命令的な変更は、監視可能(observable)では*ありません***。例えば、以下のような場合です。: -* オブジェクトのサブプロパティを設定: +- オブジェクトのサブプロパティを設定: - ~~~javascript + ```js // unobservable subproperty change this.address.street = 'Elm Street'; - ~~~ + ``` - ここでサブプロパティ`address.street`を変更しても、`address`のsetterメソッドが呼び出されることはないので、自動的に監視することはできません。 + ここでサブプロパティ`address.street`を変更しても、`address`のsetterメソッドが呼び出される*ことはない*ので、自動で監視可能(observable)ではありません。 -* 配列の変更: +- 配列の変更: - ~~~javascript + ```js // unobservable change using native Array.push - this.users.push({ name: 'Maturin}); - ~~~ + this.users.push({ name: 'Maturin'}); + ``` - 配列を変更しても`users`のsetterメソッドが呼び出されることはないので、自動的に監視することはできません。 + 配列を変更しても`users`のsetterメソッドが呼び出されることはないので、自動で監視可能(observable)ではありません。 -どちらの場合も、変更を監視できるようにするには、Polymerの用意したメソッドを利用する必要があります。 +どちらの場合も、変更を監視可能(observable)なものにするには、Polymerの提供するメソッドを利用する必要があります。 ### オブジェクトと配列の変更を監視可能(observable)に {#make-observable-changes} -Polymerは、サブプロパティや配列を監視できるようにするメソッドを用意しています。: +Polymerは、サブプロパティや配列への変更を監視できるようにするメソッドを用意しています。: ```js // mutate an object observably @@ -143,16 +139,16 @@ this.set('address.street', 'Half Moon Street'); this.push('users', { name: 'Maturin'}); ``` -特定のケースにおいては、Polymerのメソッドを利用してオブジェクトや配列を変更することができません。(サードパーティのライブラリを使用している場合など)。この場合には、[`notifyPath`](/{{{polymer_version_dir}}}/docs/api/elements/Polymer.Element#method-notifyPath)メソッドや[`notifySplices`](/{{{polymer_version_dir}}}/docs/api/elements/Polymer.Element#method-notifySplices)メソッドを使用することで、**すでに発生した**変更をエレメントに通知できます。 +あるケースにおいては、Polymerのメソッドを利用してオブジェクトや配列を変更することができないかもしれません。(サードパーティーのライブラリを使用している場合など)。このような場合には、[`notifyPath`](/%7B%7B%7Bpolymer_version_dir%7D%7D%7D/docs/api/elements/Polymer.Element#method-notifyPath)メソッドや[`notifySplices`](/%7B%7B%7Bpolymer_version_dir%7D%7D%7D/docs/api/elements/Polymer.Element#method-notifySplices)メソッドを利用することで、**すでに生じた**変更をエレメントに*通知*できます。 ```js // Notify Polymer that the value has changed this.notifyPath('address.street'); ``` -`notifyPath`メソッドや`notifySplices`メソッドを呼び出すと、あたかも変更が発生したかのように、エレメントは適切な*プロパティエフェクト*を作用させます。 +`notifyPath`メソッドや`notifySplices`メソッドを呼び出すと、あたかも変更が発生したかのように、エレメントは適切な*プロパティエフェクト*を発生させます。 -`set`や`notifyPath`を呼び出す際は、変更された**正確なパス**を使用する必要があります。例えば、`address`オブジェクト自体は変更されていないのに、`this.notifyPath('address')`の呼び出しを行なった場合、`address.street`の変更は検出されません。これは、Polymerがオブジェクトの等価性からオブジェクトと配列に*ダーティチェック*を行うためです。指定されたパスの値が変更されていなければ、プロパティエフェクトは一切生じることがありません。 +`set`や`notifyPath`を呼び出す際は、変更された**正確なパス**を指定する必要があります。例えば、`address`オブジェクト自体は変更されていないのに、`this.notifyPath('address')`の呼び出しを行なった場合、`address.street`への変更は検出されません。これは、Polymerがオブジェクトの等価性によってオブジェクトや配列に対して*ダーティチェック*を行うためです。指定されたパスの値が変更されていなければ、プロパティエフェクトは一切生じることがありません。 ほとんどの場合、オブジェクトの一つ以上のプロパティが変更された場合、または配列内の一つ以上のアイテムが変更された場合、オブジェクトや配列を複製(cloning)することで、Polymerによる*ダーティチェック*を強制的に回避させることができます。 @@ -163,27 +159,26 @@ this.addresses.push(address2) this.addresses = this.addresses.slice(); ``` -多層的な(multiple levels)データ構造を持ったオブジェクトや配列の場合には、その変更内容を検出するために深いコピー(deep copy)を実行する必要があるかもしれません。 +多層的な(multiple levels)データ構造を持ったオブジェクトや配列の場合には、その変更を検出するために深いコピー(deep copy)を実行する必要があるかもしれません。 アプリケーションでそのような必要性が生じた場合は、`Polymer.MutableData`ミックスインを使用することで、エレメントごとにオブジェクトや配列のダーティチェックを回避できます。このミックスインは、利便性向上ためにいくらかパフォーマンスを犠牲にすることがあるかもしれません。詳細については、[MutableDataミックスインの利用](#mutable-data)を参照してください。 - 関連タスク: -* [オブジェクトのサブプロパティの設定](model-data#set-path) -* [配列の変更](model-data#array-mutation) -* [サブプロパティの変更をPolymerに通知](model-data#notify-pat) -* [配列の変更をPolymerに通知](model-data#notifysplices) +- オブジェクトのサブプロパティの設定 +- 配列の変更 +- サブプロパティの変更をPolymerに通知 +- 配列の変更をPolymerに通知 ### バッチ処理によるプロパティの変更 -バインディングシステム内におけるデータの伝播はバッチで処理されます、そうすることでコンプレックスオブザーバーや算出関数による変更は一度にまとまて実行されます。*まとまった変更*を生成する方法はいくつか存在します。: +バインディングシステム内におけるデータの伝播はバッチで処理されるので、コンプレックスオブザーバーや算出関数による変更は一度にまとまて実行されます。*まとまった(coherent)変更*を生成する手段はいくつか存在します。: -* エレメントが自身のプロパティを初期化する際は、*まとまった変更*を自動的に生成します。 +- エレメントが自身のプロパティを初期化する際は、*まとまった変更*を自動的に生成します。 -* オブジェクトまたは配列を設定する際は、*まとまった変更*を自動的に生成します。 +- オブジェクトまたは配列を設定する際は、*まとまった変更*を自動的に生成します。 -* `setProperties`メソッドを使用することで、複数のプロパティをアトミック(atomically)に設定できます。 +- `setProperties`メソッドを使用することで、複数のプロパティをアトミックに(atomically)設定できます。 ```js this.setProperties({item: 'Orange', count: 12 }); @@ -212,14 +207,13 @@ object.](/images/1.0/data-system/data-binding-paths-new.png) 1. ``エレメントは、Javascriptのオブジェクトを参照する`primaryAddress`プロパティを持っています。 2. ``エレメントは、同じオブジェクトを参照する`address`プロパティを持っています -重要なことですが、**Polymerは、これらのプロパティが同じオブジェクトを参照していることを自動的に認識するわけではありません。**``がオブジェクトへの変更を行っても、``上でプロパティエフェクトは生じるわけではありません。 +重要なことですが、**Polymerは、これらのプロパティが同じオブジェクトを参照していることを自動的に認識するわけではありません。**``がオブジェクトへの変更を行っても、``上でプロパティエフェクトは生じません。 **あるエレメントから別のエレメントへデータの変更が流れるようにするには、エレメントはデータバインディングによってコネクトされている必要があります。** ### データバインディングによるパスのリンク -データバインディングは、異なるエレメントのパス間にリンクを作成することができます。実は、**データバインディングは、異なるエレメントのパスにリンクを設定する唯一の手段です。**例えば、前のセクションの``の例で考えてみましょう。``が``エレメントのローカルDOM内に存在する場合、二つのパスはデータバインディングを使ってコネクトすることができます。: - +データバインディングは、異なるエレメントのパス間にリンクを作成することができます。実は、**データバインディングは、異なるエレメントのパスにリンクを設定する唯一の手段です。**例えば、前のセクションの``の例で考えてみましょう。``が``エレメントのローカルDOM内に存在する場合、二つのパスはデータバインディングを使うことでコネクトできます。: ```html @@ -246,7 +240,7 @@ object.](/images/1.0/data-system/data-binding-paths-new.png) パスは、現在のデータバインディングのスコープに関連づいています。 -どのエレメントにとっても最上位のスコープはエレメントのプロパティです。いつくかのデータバインディングのヘルパーエレメント([テンプレートリピーター](/{{{polymer_version_dir}}}/docs/devguide/templates#dom-repeat))のような)では、新たに入れ子のスコープを導入します。 +どのエレメントにとっても最上位のスコープはエレメントのプロパティです。データバインディングのヘルパーエレメントのいくつか([テンプレートリピーター](/%7B%7B%7Bpolymer_version_dir%7D%7D%7D/docs/devguide/templates#dom-repeat))では、新たに入れ子のスコープを導入します。 オブザーバーと算出プロパティの場合、スコープは常にエレメントのプロパティになります。 @@ -256,26 +250,22 @@ object.](/images/1.0/data-system/data-binding-paths-new.png) いくつか特殊なタイプのパスセグメントがあります。 -* ワイルドカード記号(`*`)は、パス内の最後のセグメントとして使用できます。(例:`foo.*`)ワイルドカードパスは、配列の変更を含む、指定されたパス及びそのサブプロパティに対する全ての変更を表します。 -* 文字列`splices`は、パス内の最後のセグメントとして使用できます。(例:`foo.splices`)splicesは指定された配列における全ての変更を表します。 -* 配列アイテムのパスは、(例:`foo.11`)ある配列内のアイテムを表し、数字のパスセグメントは配列のインデックスを表します。 - - +- ワイルドカード記号(`*`)は、パス内の最後のセグメントとして使用できます。(例:`foo.*`)ワイルドカードパスは、配列の変更を含む、指定されたパス及びそのサブプロパティに対する全ての変更を表します。 +- 文字列`splices`は、パス内の最後のセグメントとして使用できます。(例:`foo.splices`)splicesは指定された配列に対する全ての変更を表します。 +- 配列アイテムのパスは、(例:`foo.11`)ある配列内のアイテムを表し、数字のパスセグメントは配列のインデックスを表します。 #### ワイルドカードパス {#wildcard-paths} -ワイルドカード記号(`*`)をパス内の最後のセグメントとして使用すると、前のプロパティやそのサブプロパティへの変更を表します。例えば、`users`という配列があった場合、`users.*`と記述すると`users`配列自身またはそのサブプロパティへの変更について関心があることを示します。 +ワイルドカード記号(`*`)をパス内の最後のセグメントとして使用すると、ワイルドカードより前に指定されたプロパティやそのサブプロパティへの変更を表します。例えば、`users`という配列があった場合、`users.*`と記述すると配列`users`またはそのサブプロパティへの変更について関心があることを示します。 ワイルドカードパスは、オブザーバー、算出プロパティ、算出バインディングだけに使用されます。データバインディングにおいてワイルドカードパスを使用することはできません。 #### 配列変更パス -パスの最後のセグメントとして`splices`が使用されると、`splices`は配列への特定の*変更*(追加または削除)を表します。例えば、`users`が配列の場合、パス -`users.splices`は、配列への追加または削除を識別します。 +パスの最後のセグメントとして`splices`が使用されると、`splices`は配列への全ての*変更*(追加または削除)を表します。例えば、`users`が配列の場合、パス +`users.splices`は、配列への全ての追加または削除を識別します。 -パス`.splices`は、オブザーバー、算出プロパティ、または算出バインディングで -配列の変更を*認識*するに利用できます。 パス`.splices`を監視(observe)すると、ワイルドカードパスによって登録された変更の**サブセット**が得られます。 -(例えば、配列内に存在するオブジェクトのサブプロパティの変更には関心がないかもしれません。) **多くの場合、配列にはワイルドカードを使ったオブザーバーを利用する方が便利です。** +パス`.splices`は、オブザーバー、算出プロパティ、または算出バインディングで配列への変更を*識別*するに利用できます。 パス`.splices`を監視(observe)すると、ワイルドカードパスによって検出された変更の**サブセット**を得ることができます。(例えば、配列内に存在するオブジェクトのサブプロパティへの変更には関心がないかもしれません。) **多くの場合、配列にはワイルドカードを使ったオブザーバーを利用する方が便利です。** ### 同一オブジェクトを参照する二つのパス {#two-paths} @@ -283,66 +273,65 @@ object.](/images/1.0/data-system/data-binding-paths-new.png) 例えば、エレメントに配列`users`やオブジェクト`selectedUser`を参照する二つのプロパティがあったとします。あるユーザーが選択されると`selectedUser`は配列内の一つのオブジェクトを参照します。 - -![A user-list element and an array with four items labeled \[0\] through \[3\]. The user-list has two properties, users and selectedUser. The users property is connected to the array by an arrow labeled 1. The selectedUser property is connected to the array item, \[1\] by an arrow labeled 2.](/images/1.0/data-system/linked-paths-new.png) +![A user-list element and an array with four items labeled [0] through [3]. The user-list has two properties, users and selectedUser. The users property is connected to the array by an arrow labeled 1. The selectedUser property is connected to the array item, [1] by an arrow labeled 2.](/images/1.0/data-system/linked-paths-new.png) 1. プロパティ`users`は配列そのものを参照します。 -2. プロパティ`selectedUser`は配列内のアイテムを参照します。 +2. プロパティ`selectedUser`は配列内の特定のアイテムを参照します。 -この例では、エレメントには、配列内の二番目のアイテムを参照する以下の二つのパスが存在します。 +以下の例では、エレメントに、配列内の二番目のアイテムを参照する複数のパスが存在します。 -* `selectedUser` -* `users.1`(`1`は配列`users`内のアイテムのインデックスです) +- `selectedUser` +- `users.1`(`1`は配列`users`内のアイテムのインデックスです) デフォルトでは、Polymerには(`users.1`のような)配列のパスを`selectedUser`に関連付ける方法がありません。 -このようなケースに最適な手段として、Polymerは、データバインディングのヘルパーエレメント``を用意しており、配列とその配列から選択されたアイテムの間でパスの結合を保持します。(``は、配列から複数のアイテムを選択する場合にも動作します)。 +このようなケースに最適な手段として、Polymerは、データバインディングのヘルパーエレメント``を用意しており、配列とその配列から選択されたアイテムの間でパスの結合を保持します。(``は、配列から複数のアイテムを選択する場合にも使えます)。 - -他のユースケースのために、二つのパスを関連付けるための命令的なメソッドとして[linkPaths](/{{{polymer_version_dir}}}/docs/api/elements/Polymer.Element#method-linkPaths)があります。二つのパスがリンクされている場合、一方のパスに[監視可能(observable)な変更](#observable-changes)を加えると、もう一方のパスでも同様にその変更を監視できます。 +他のユースケースのために、二つのパスを関連付けるための命令的なメソッドとして[`linkPaths`](/%7B%7B%7Bpolymer_version_dir%7D%7D%7D/docs/api/elements/Polymer.Element#method-linkPaths)があります。二つのパスが*リンクされている*時、一方のパスに[監視可能(observable)な変更](#observable-changes)を加えると、もう一方のパスでも同様にその変更を監視できます。 関連タスク: -* [二つのパスを同一オブジェクトにリンク](model-data#linkpaths) -* [配列の選択をデータバインド](templates#array-selector) +- [二つのパスを同一オブジェクトにリンク](model-data#linkpaths) + +- [配列の選択をデータバインド](templates#array-selector) ## データフロー {#data-flow} -Polymerは*Mediatorパターン*を実装しており、ホストエレメントは、エレメント自身とそのローカルDOMのノード間のデータフローを管理します。 +Polymerは*Mediatorパターン*を実装しており、ホストエレメントは、自分自身とそのローカルDOMのノード間のデータフローを管理します。 -二つのエレメントがデータバインディングでコネクトされると、データの変更は、ホストからターゲットへ下に向けて(downward)、またターゲットからホストへ上に向けて、あるいはその両方に向けて流すことができます。 +二つのエレメントがデータバインディングでコネクトされると、データの変更は、ホストからターゲットへ*下に向けて(downward)*、またターゲットからホストへ*上に向けて(upward)*、あるいは双方向に流すことができます。 ローカルDOM内の二つのエレメントが同一のプロパティにバインドされている場合、データはあるエレメントから別のエレメントに流れるように思われますが、この流れはホストによって仲介(mediate)されたものです。一つのエレメントで生じた変更がホストへ**上に**伝播すると、ホストはその変更を他方のエレメントへ**下に**伝播させます。 ### データフローは同期的 -データフローは**同期的**です。あなたの記述したコードが[監視可能(observable)な変更](#observable-changes)を発生させると、その変更による全てのデータフローとプロパティエフェクトは、エレメントがアクションを明示的に遅延させない限り(例えば、非同期メソッドを呼び出すことによって)、次の行のJavaScriptが実行される前に発生します。 +データフローは**同期的**です。あなたの記述したコードが[監視可能(observable)な変更](#observable-changes)を発生させると、その変更によって生じる全てのデータフローとプロパティエフェクトは、エレメントがアクションを明示的に遅延させない限り(例えば、非同期メソッドを呼び出す)、次の行のJavaScriptが実行される前に発生します。 ### データフローの制御の仕組み {#data-flow-control} -個々のバインディングによってサポートされるデータフローのタイプは、以下の項目に依存して決まります。: +個々のバインディングによってサポートされるデータフローのタイプは、以下の項目によって決まります。: -* 使用されるバインディングアノテーションのタイプ。 -* ターゲットプロパティーの設定。 +- 使用されるバインディングアノテーションのタイプ +- ターゲットプロパティーの設定 二種類あるデータバインディングアノテーションは以下の通りです。: -* **自動的(automatic)**:上向き(ターゲットからホストへ)及び下向き(ホストからターゲットへ)のデータフローを許可します。自動バインディングには二重中括弧(`{{ }}`)を使用します。): +- **自動的(automatic)**:上向き(ターゲットからホストへ)及び下向き(ホストからターゲットへ)のデータフローを許可します。自動バインディングには二重中括弧(`{{ }}`)を使用します。): ```html ``` -* **一方向(one-way)**:下向きのデータフローだけ許可します。上向きのデータフローは無効です。一方向バインディングには二重角括弧(`[[ ]]`)を使用します。 +- **一方向(one-way)**:下向きのデータフローだけ許可します。上向きのデータフローは無効です。一方向バインディングには二重角括弧(`[[ ]]`)を使用します。 ```html ``` -次の設定フラグは、**ターゲットプロパティ間**におけるデータフローに影響を与えます。: +次の設定フラグは、ターゲットプロパティとのデータフローに影響を与えます。: -* `notify`:**上向きのデータフローをサポートします**。デフォルトでは、プロパティは`false`(non-notifying)であり、上向きのデータフローはサポートされません。 -* `readOnly`:**下向きのデータフローを防ぎます**。デフォルトでは、プロパティは`false`(read/write)であり、下向きのデータフローをサポートします。 +- `notify`:**上向きのデータフローをサポートします**。デフォルトでは、プロパティは`false`(non-notifying)であり、上向きのデータフローはサポートされません。 +- `readOnly`:**下向きのデータフローを防ぎます**。デフォルトでは、プロパティは`false`(read/write)であり、下向きのデータフローをサポートします。 プロパティ定義の例 {.caption} @@ -381,7 +370,8 @@ readOnly: false 一方向、下向き -
notify: false,
+  
+
notify: false,
 readOnly: true
データフローなし @@ -403,8 +393,7 @@ readOnly: true
-これとは対照的に、一方向バインディングは下向きのデータフローだけを許可するため、`notify`フラグは結果に影響することはありません。: - +これとは対照的に、一方向バインディングの場合、下向きのデータフローだけを許可するため、`notify`フラグは結果に影響することはありません。: @@ -416,7 +405,7 @@ readOnly: true - + @@ -434,8 +423,7 @@ readOnly: true
readOnly: false
- -**プロパティの設定(readOnlyやnotify)は、プロパティそのものに影響するだけで、サブプロパティには及びません。**特に、値にオブジェクトや配列を持つプロパティをバインディングした場合、ホストとターゲットエレメントの間で共有データが生成されますが、プロパティの設定による制御ができないので、どちらのエレメントでも共有されたオブジェクトや配列の変更を防ぐ方法はありません。詳細については、[オブジェクト及び配列のデータフロー](#data-flow-objects-arrays)を参照してください。 +**プロパティの設定(readOnlyやnotify)は、*プロパティそのものに影響するだけで*、サブプロパティには影響を及ぼしません。**特に、値にオブジェクトや配列を持つプロパティをバインディングした場合、ホストとターゲットエレメントの間で共有データが生成されますが、プロパティの設定による制御ができないので、どちらのエレメントでも共有されたオブジェクトや配列の変更を防ぐ方法はありません。詳細については、[オブジェクト及び配列のデータフロー](#data-flow-objects-arrays)を参照してください。 {.alert .alert-warning} ### データフローの例 @@ -506,7 +494,7 @@ readOnly: true 例3:一方向バインディング(下向き) -同様に、双方向バインディングデリミタは使用しながら、`someProp`プロパティで`notify: true`を省略すると、下向きの一方向バインディングが生成されます。`someProp` +同様に、双方向バインディングデリミタは使用しながら、`someProp`プロパティで`notify: true`を省略すると、下向きの一方向バインディングが生成されます。`someProp` ```html ``` - ### 上向きおよび下向きデータフロー ホストエレメントはデータフローを管理しているので、ターゲットエレメントと直接的にやりとりすることができます。ホストは、ターゲットエレメントのプロパティを設定したり、メソッドを呼び出すことで下に向けてデータを伝播します。 - ![An element, host-element connected to an element, target-element by an arrow labeled 1.](/images/1.0/data-system/data-flow-down-new.png) 1. ホストエレメントでプロパティが変更されると、ターゲットエレメントの対応するプロパティが設定され、関連するプロパティエフェクトが発生します。 -Polymer Elementは、イベントを使用してデータを上に向けて伝播させます。ターゲットエレメントは、*監視可能(observable)な変更*が発生するとノンバブリングイベントを発火します。(変更イベントに関する詳細は、[変更通知イベント](#change-events)で説明しています)。 - -**双方向バインディング**の場合、ホストエレメントは、これらの変更イベントをリッスンし、その変更を伝播させます。これら変更は、プロパティを設定したり、関連する*プロパティエフェクト*が作用することで生じます。プロパティエフェクトには以下のようなものが含まれるかもしれません。 +Polymer Elementsは、イベントを使用してデータを上に向けて伝播させます。ターゲットエレメントは、*監視可能(observable)な変更*が発生するとノンバブリングイベントを発火します。(変更イベントに関する詳細は、[変更通知イベント](#change-events)で説明しています)。 -* 兄弟エレメント(sibling elements)へ変更を伝播させるためにデータバインディングをアップデートする。 -* 変更を上に向けて伝播させるため、別の変更イベントを生成する。 +**双方向バインディング**の場合、ホストエレメントは、これらの変更イベントをリッスンし、その変更を伝播させます。これら変更は、例えばプロパティを設定したり、関連する*プロパティエフェクト*が作用することで生じます。プロパティエフェクトには以下のようなものが含まれるかもしれません。 +- 兄弟エレメント(sibling elements)へ変更を伝播させるためにデータバインディングをアップデートする。 +- 変更を上に向けて伝播させるため、別の変更イベントを生成する。 ![An element, target-element connected to an element, host-element by an arrow labeled 1. An arrow labeled 2 connects from the host element back to itself.](/images/1.0/data-system/data-flow-up-new.png) @@ -658,10 +641,10 @@ Polymer Elementは、イベントを使用してデータを上に向けて伝 プロパティがオブジェクトや配列の場合、データフローは少々複雑になります。オブジェクトや配列は複数のエレメントから参照することができ、また、あるエレメントが共有された配列を変更したり、オブジェクトのサブプロパティを変更したりするのを防ぐ術はありません。 -そのため、Polymerは配列やオブジェクトの内容を、常に双方向バインディング**可能なもの**として扱います。言い換えると: +そのため、Polymerは配列やオブジェクトの内容を、常に双方向バインディング**可能なもの**として扱います。要するに: -* ターゲットプロパティが読み取り専用(`readOnly:true`)に設定されていても、データの更新はいつも下に向かって流れます。 -* ターゲットプロパティが通知可能(`notify:ture`)に設定されていなくても、上向きのデータフローの変更イベントは常に発生します。 +- ターゲットプロパティが読み取り専用(`readOnly:true`)に設定されていても、データの更新はいつも下に向かって流れます。 +- ターゲットプロパティが通知可能(`notify:ture`)に設定されていなくても、上向きのデータフローの変更イベントは常に発生します。 一方向バインディングアノテーションはイベントリスナーを生成しないため、これらの変更通知がホストエレメントに伝播されないようにします。 @@ -669,10 +652,11 @@ Polymer Elementは、イベントを使用してデータを上に向けて伝 エレメントは、以下のいずれかの[監視可能(observable)な変更](#observable-changes)が発生した時点で*変更通知イベント*を発生させます。: -* 通知設定されたプロパティへの変更 -* サブプロパティの変更 -* 配列の変更 +- 通知設定されたプロパティへの変更 +- サブプロパティの変更 + +- 配列の変更 イベントの`type`プロパティは、どのプロパティが変更されたか示しています。:property-changedという命名規則従い、propertyの部分はダッシュケース(dash-case)に変換したプロパティ名になります。(つまり、`this.firstName`が変更されると`first-name-changed`が発火します)。 @@ -680,50 +664,54 @@ Polymer Elementは、イベントを使用してデータを上に向けて伝 イベントの内容は、変更によって異なります。 -* プロパティの変更の場合、`detail.value`フィールドにプロパティの新しい値が含まれます。 -* サブプロパティの変更の場合、サブプロパティへのパスが`detail.path`フィールドに含まれます、そして新しい値が`detail.value`フィールドに含まれます。 -* 配列の変更の場合、`detail.path`フィールドは`myArray.splices`のように配列の変更パスになります。そして`detail.value`フィールドがチェンジレコードになります。チェンジレコードについては、ドキュメントの[配列オブザーバー](/{{{polymer_version_dir}}}/docs/devguide/observers#array-observation)で解説されています。 +- プロパティの変更の場合、`detail.value`フィールドにプロパティの新しい値が含まれます。 + +- サブプロパティの変更の場合、サブプロパティへのパスが`detail.path`フィールドに含まれます、そして新しい値が`detail.value`フィールドに含まれます。 + +- 配列の変更の場合、`detail.path`フィールドは`myArray.splices`のように配列の変更パスになります。そして`detail.value`フィールドがチェンジレコードになります。これは、ドキュメントの[配列の監視](/%7B%7B%7Bpolymer_version_dir%7D%7D%7D/docs/devguide/observers#array-observation)で解説されている通りです。 + + 配列を変更した場合、Polymerは配列の`length`プロパティに対しても変更イベントを発生させます。(例えば、`detail.path`は`myArray.length`に、`detail.value`は新たな配列のlengthになります) -**注意**:**変更通知イベントの伝播は停止しないでください。**イベントオブジェクトの生成と廃棄を避けるため、Polymerは変更通知にキャッシュされたイベントオブジェクトを使用します。変更通知イベントで`stopPropagation`を呼び出ことで、**そのプロパティにおけるすべてのイベントを将来に渡って防止します。**変更通知イベントはバブリングしないので、伝播を停止する必要はありません。 +**注意:変更通知イベントの伝播は停止しないでください。**イベントオブジェクトの生成と削除を避けるため、Polymerは変更通知にキャッシュされたイベントオブジェクトを使用します。変更通知イベントで`stopPropagation`を呼び出ことで、{strong2}そのプロパティにおけるすべてのイベントが将来に渡って発生しないようにします。{/strong2}変更通知イベントはバブリングしないので、伝播を停止する必要はありません。 {.alert .alert-warning} + ### カスタム変更通知イベント ``のようなネイティブエレメントは、Polymerが上向きのデータフローに利用する変更通知イベントを用意していません。ネイティブの`input`エレメントで双方向データバインディングをサポートするために、Polymerでは**カスタム変更通知イベント**をデータバインディングと関連付けることができるようになっています。例えば、テキスト入力にバインドすると、その`input`または`change`イベントを指定することができるようになります。: - ```html ``` -この例では、`firstName`プロパティが`input`エレメントの`value`プロパティにバインドされています。`input`エレメントが`change`イベントを発生させるたびに、Polymerは`firstName`プロパティが`input`の`value`と一致させるように更新し、また関連するプロパティエフェクトがあればすべて発生させます。**イベントの内容は重要ではありません。** +この例では、`firstName`プロパティが`input`エレメントの`value`プロパティにバインドされています。`input`エレメントが`change`イベントを発生させるたびに、Polymerは`firstName`プロパティと`input`の`value`を一致させるようにアップデートし、また関連するプロパティエフェクトがあればすべて発生させます。**イベントの内容は重要ではありません。** この手法は、特にネイティブの`input`エレメントにとって便利ですが、Polymerを使って作成されていないコンポーネント(プロパティを公開しており、その変更時にイベントを発生させる)に双方向バインディングを提供する手段としても使うことができます。 関連タスク: -* [Polymer Elementでないエレメントへの双方向バインディング](data-binding#two-way-native) +- [Polymer Elementでないエレメントへの双方向バインディング](data-binding#two-way-native) ### エレメントの初期化 エレメントがローカルDOMを初期化する際は、エレメントはローカルDOMの子のプロパティを設定し、データバインディングの初期化も行います。 -初期化処理の中では、ホストの値が優先されます。例えば、ホストプロパティがターゲットプロパティにバインドされている場合、hostエレメントとtargetエレメントの両方でデフォルト値を指定すると、親のデフォルト値が使用されます。 +初期化処理の間は、ホストの値が優先されます。例えば、ホストプロパティがターゲットプロパティにバインドされている場合、hostエレメントとtargetエレメントの両方でデフォルト値を指定すると、親のデフォルト値が使用されます。 ## プロパティエフェクト(property effects) {#property-effects} -プロパティエフェクトは指定されたプロパティへ[監視可能な(observable)変更](#observable-changes)が発生した場合に引き起こされるアクションです。プロパティエフェクトは以下のようなケースで発生します。: +プロパティエフェクトは指定されたプロパティ(またはパス)へ[監視可能な(observable)変更](#observable-changes)が発生した場合に引き起こされるアクションです。プロパティエフェクトは以下のようなケースで発生します。: -* 算出プロパティの再計算 -* データバインディングの更新 -* プロパティ値をホストエレメントの属性に反映 -* オブザーバーの呼び出し -* 変更通知イベントの発火 +- 算出プロパティの再計算 +- データバインディングの更新 +- プロパティ値をホストエレメントの属性に反映 +- オブザーバーの呼び出し +- 変更通知イベントの発火 これらのプロパティエフェクトの実行順序は、しっかり定義されています。: 1. 算出プロパティ 2. データバインディング -3. 反映された(reflected)値 +3. 属性値への反映 4. オブザーバー 5. 変更通知イベント @@ -731,7 +719,7 @@ Polymer Elementは、イベントを使用してデータを上に向けて伝 ### データバインディング -*データバインディング*は、ホストエレメントのデータとホストのローカルDOM内の`target`ノードのプロパティや属性の間にコネクションを確立します。エレメントのローカルDOMのテンプレートにアノテーションを追加することでデータバインディングを生成します。 +*データバインディング*は、ホストエレメントのデータとホストのローカルDOM内の`target`ノードのプロパティや属性の間にコネクションを確立します。エレメントのローカルDOMのテンプレートにアノテーションを追加することでデータバインディングが生成されます。 *アノテーション*とは、ターゲットエレメントでデータバインディング用デリミタ`{{ }}`又は`[[ ]]`を使用した属性値です。 @@ -747,7 +735,7 @@ Polymer Elementは、イベントを使用してデータを上に向けて伝 target-attribute$="[[hostProperty]]" -また、エレメントの本体にデータバインディングアノテーションを使用することもできます。これは、エレメントの`textContent`プロパティに対してバインディングを行なったのと同じことです。 +また、エレメントのボディにデータバインディングアノテーションを使用することもできます。これは、エレメントの`textContent`プロパティに対してバインディングを行なったのと同じことです。 ```html
{{hostProperty}}
@@ -755,25 +743,24 @@ Polymer Elementは、イベントを使用してデータを上に向けて伝 デリミタ内のテキストは、次のいずれかになります。: -* プロパティまたはサブプロパティのパス(`users`、`address.street`)。 -* 算出バインディング(`_computeName(firstName, lastName, locale)`)。 -* 上記のそれぞれに、否定演算子(`!`)を後置したもの +- プロパティまたはサブプロパティのパス(`users`、`address.street`) +- 算出バインディング(`_computeName(firstName, lastName, locale)`) +- 上記のそれぞれに、否定演算子(`!`)を前置したもの 詳細については、[データバインディング](data-binding)を参照してください。 - -## UMutableDataミックスインの使用 {#mutable-data} +## MutableDataミックスインの使用 {#mutable-data} Polymer 1.xでは、*ダーティチェック*(dirty check)メカニズムを使用して、データシステムが余計な作業をするのを防いでいました。Polymer 2.xでもデフォルトでこのメカニズムを維持していますが、エレメントにおいてオブジェクトや配列に対する*ダーティチェック*をオプトアウト(利用者が機能の使用を制限)できるようになっています。 -デフォルトの*ダーティチェック*メカニズムによって、次のコードでは*プロパティエフェクト*を生成させません。: +デフォルトの*ダーティチェック*メカニズムによって、次のコードでは*プロパティエフェクト*が発生しません。: ```js this.property.subproperty = 'new value!'; this.notifyPath('property'); ``` -オブジェクトと配列に対する厳密なダーティチェックは、オブジェクトの同一性に基づいています。`property`は依然として同じオブジェクトを指しているので、ダーティチェックは失敗し、サブプロパティの変更は伝播しません。代わりに、Polymerの`set`メソッドや*配列変更メソッド*を使用するか、変更された正確なパス指定して`notifyPath`を呼び出す必要があります。: +オブジェクトと配列に対する厳密なダーティチェックは、オブジェクトの同一性に基づいています。`property`は依然として同じオブジェクトを参照しているので、ダーティチェックは失敗し、サブプロパティへの変更は伝播しません。代わりに、Polymerの提供する`set`メソッドや*配列変更メソッド*を使用するか、変更された正確なパス指定して`notifyPath`を呼び出す必要があります。: ```js this.set('property.subproperty', 'new value!'); @@ -782,12 +769,12 @@ this.property.subproperty = 'new value!'; this.notifyPath('property.subproperty'); ``` -一般に、ダーティチェックメカニズムはパフォーマンスの向上をもたらします。以下いずれかの要件が当てはまるアプリケーションでは特にうまくいきます。: +一般に、ダーティチェックメカニズムはパフォーマンスの向上をもたらします。以下いずれかの要件が当てはまるアプリケーションでは特にうまく機能します。: -* 不変データを使用する。 -* 小さな変更についても必ずPolymerのデータ変更メソッドを使用する。 +- 不変データを使用する。 +- 小さな変更についても必ずPolymerのデータ変更メソッドを使用する。 -しかし、不変のデータを使用せず、Polymerのデータ関連メソッドを使用できないアプリケーションに対して、Polymer 2.0は[`Polymer.MutableData`](/{{{polymer_version_dir}}}/docs/api/mixins/Polymer.MutableData)ミックスインを用意しています。 +しかし、不変のデータを使用せず、Polymerのデータ関連メソッドを使用できないアプリケーションに対して、Polymer 2.0は[`Polymer.MutableData`](/%7B%7B%7Bpolymer_version_dir%7D%7D%7D/docs/api/mixins/Polymer.MutableData)ミックスインを用意しています。 ```js class MyMutableElement extends Polymer.MutableData(Polymer.Element) { ... } @@ -802,7 +789,6 @@ this.notifyPath('property'); 可変(mutable)データモードでは、*プロパティエフェクト*を呼び出す前に、いくつかの変更をバッチで処理することもできます: - ```js this.property.arrayProperty.push({ name: 'Alice' }); this.property.stringProperty = 'new value!'; @@ -818,7 +804,7 @@ this.set('property', this.property); this.property = this.property; ``` -特定のサブプロパティを変更するのに`set`メソッドを利用するのが、多くのケースで最も効率的な手段となります。しかし、`MutableData`を使用するエレメントではこのAPIを使用する必要はなく、データバインディングや状態管理を行う代替ライブラリを利用することで互換性をさらに高めることができます。 +特定のサブプロパティを変更するのに`set`メソッドを利用するのが、多くのケースで最も効率的な手段となります。しかし、`MutableData`を使用するエレメントではこのAPIを使用する必要はなく、データバインディングや状態管理を行う代替ライブラリとの互換性を高めることができます。 トップレベルでプロパティを再設定すると、そのプロパティ、サブプロパティ、配列のアイテムなどに対する*プロパティエフェクト*が全て再実行されてしまうので注意が必要です。さらに、ワイルドカードパス(`prop.*`のような)を指定したオブザーバーには、トップレベルでの変更だけが通知されます。: @@ -831,13 +817,12 @@ this.notifyPath('property'); `set`メソッドを利用して特定のパスを設定すると、細かい通知も生成します。: - ```js // 'property.*' observers fire with the path 'property.deep.path' this.set('property.deep.path', 'new value'); ``` -エレメントのプロパティが文字列、数値、ブール値などのプリミティブな値しか取らない場合には、`MutableData`を使用する必要はありません。これらの値は常にダーティチェックされており`MutableData`にはメリットがありません。これは多くのシンプルなUIエレメントについて言えることです。`MutableData`は複雑で再利用可能なエレメント(`dom-repeat`または`iron-list`のような)や、複雑な状態の情報を持つアプリケーション固有のエレメントに対しては役立つでしょう。 +エレメントのプロパティが文字列、数値、ブール値などのプリミティブな値しか取らない場合には、`MutableData`を使用する必要はありません。これらの値は常にダーティチェックされており`MutableData`の利用によるメリットがありません。これは多くのシンプルなUIエレメントに対してあてはまることです。`MutableData`は複雑で再利用可能なエレメント(`dom-repeat`または`iron-list`のような)や、複雑な状態の情報を持つアプリケーション固有のエレメントに対しては役立つでしょう。 `MutableData`ミックスインは、エレメントのShadow DOMの子には影響を与えないことに注意してください。`Polymer.MutableData`**ミックスインを使用しないすべてのエレメントは、すべてデフォルトのダーティチェックポリシーに従います。** @@ -850,10 +835,9 @@ this.set('property.deep.path', 'new value'); ``` - ### 再利用可能なエレメントのオプションとしての可変(mutable)データ {#optional-mutable-data} -構造化されたデータを取り込む再利用可能なエレメントを構築する場合は、[`Polymer.OptionalMutableData`](/{{{polymer_version_dir}}}/docs/api/mixins/Polymer.OptionalMutableData)ミックスインが使用できます。このミックスインを使用すると、エレメント上に`mutableData`プロパティを設定することで、`MutableData`モードを選択できます。 +構造化されたデータを取り込む再利用可能なエレメントを構築する場合は、[`Polymer.OptionalMutableData`](/%7B%7B%7Bpolymer_version_dir%7D%7D%7D/docs/api/mixins/Polymer.OptionalMutableData)ミックスインが使用できます。このミックスインを使用すると、エレメントで`mutableData`プロパティを設定することで、`MutableData`モードを選択できます。 ```js class MyStructuredDataElement extends Polymer.OptionalMutableData(Polymer.Element) { @@ -861,7 +845,7 @@ class MyStructuredDataElement extends Polymer.OptionalMutableData(Polymer.Elemen } ``` -これにより、エレメントの利用者は、標準のデータフローまたは可変データモードのいずれかでエレメントを利用することができます。 +これにより、エレメントの利用者は、標準のデータフローまたは可変データモードのいずれかを選択して利用することができます。 ```html @@ -874,5 +858,3 @@ class MyStructuredDataElement extends Polymer.OptionalMutableData(Polymer.Elemen ``` `dom-repeat`エレメントは、このミックスインを利用して構成されたエレメントの例です。 - -