diff --git a/src/style-guide/README.md b/src/style-guide/README.md index e2d3a3a4..a15a5a90 100644 --- a/src/style-guide/README.md +++ b/src/style-guide/README.md @@ -32,16 +32,16 @@ sidebar: auto Vue のいくつかの機能は、レアケースまたは従来のコードベースからスムーズな移行に対応するために存在します。しかしながらこれを使いすぎると、コードを保守することが難しくなり、またバグの原因になることさえあります。これらのルールは潜在的な危険な機能を照らし、いつ、なぜ避けなかればならないのかを説明しています。 -## Priority A Rules: Essential (Error Prevention) +## 優先度 A ルール: 必須 (エラー防止) -### Multi-word component names essential +### 複数単語のコンポーネント名 必須 -**Component names should always be multi-word, except for root `App` components, and built-in components provided by Vue, such as `` or ``.** +**ルートの `App` コンポーネントや、Vue が提供する `` や `` のようなビルトインコンポーネントを除き、コンポーネント名は常に複数単語とするべきです。** -This [prevents conflicts](http://w3c.github.io/webcomponents/spec/custom/#valid-custom-element-name) with existing and future HTML elements, since all HTML elements are a single word. +全ての HTML 要素は 1 単語なので、このルールを守ることで既に存在する HTML 要素や将来定義される HTML 要素との[衝突を防止することができます](http://w3c.github.io/webcomponents/spec/custom/#valid-custom-element-name)。
-

Bad

+

悪い例

``` js app.component('todo', { @@ -55,10 +55,11 @@ export default { // ... } ``` +
-

Good

+

良い例

``` js app.component('todo-item', { @@ -74,30 +75,30 @@ export default { ```
-### Prop definitions essential +### Prop の定義 必須 -**Prop definitions should be as detailed as possible.** +**Prop の定義は可能な限り詳細にするべきです。** -In committed code, prop definitions should always be as detailed as possible, specifying at least type(s). +コミットされたコードでは、prop の定義は常に可能な限り詳細にすべきで、少なくともタイプの指定をする必要があります。 -::: details Detailed Explanation -Detailed [prop definitions](https://vuejs.org/v2/guide/components.html#Prop-Validation) have two advantages: +::: details 詳細な説明 +詳細な[プロパティの定義](/guide/component-props.html#prop-validation) には 2 つの利点があります: -- They document the API of the component, so that it's easy to see how the component is meant to be used. -- In development, Vue will warn you if a component is ever provided incorrectly formatted props, helping you catch potential sources of error. +- コンポーネントの API が明文化されるため、そのコンポーネントの使用方法が簡単に確認できます。 +- 開発中、コンポーネントに対して誤った形式のプロパティが提供されると Vue は警告を通知するため、潜在的なエラー原因の検知に役立ちます。 :::
-

Bad

+

悪い例

``` js -// This is only OK when prototyping +// プロトタイピングの時に限り OK props: ['status'] ```
-

Good

+

良い例

``` js props: { @@ -106,7 +107,7 @@ props: { ``` ``` js -// Even better! +// さらに良いです! props: { status: { type: String, @@ -125,14 +126,14 @@ props: { ```
-### Keyed `v-for` essential +### キー付き `v-for` 必須 -**Always use `key` with `v-for`.** +**`v-for` に対しては常に `key` を使用してください。** -`key` with `v-for` is _always_ required on components, in order to maintain internal component state down the subtree. Even for elements though, it's a good practice to maintain predictable behavior, such as [object constancy](https://bost.ocks.org/mike/constancy/) in animations. +サブツリーの内部コンポーネントの状態を維持するために、コンポーネントでの `v-for` には _常に_ `key` を付ける必要があります。ただし要素の場合であっても、アニメーションでの[オブジェクトの一貫性](https://bost.ocks.org/mike/constancy/)のように、予測可能な振る舞いを維持することをお勧めします。 -::: details Detailed Explanation -Let's say you have a list of todos: +::: details 詳細な説明 +TODO リストを持っているとしましょう: ``` js data() { @@ -151,15 +152,15 @@ data() { } ``` -Then you sort them alphabetically. When updating the DOM, Vue will optimize rendering to perform the cheapest DOM mutations possible. That might mean deleting the first todo element, then adding it again at the end of the list. +次に、それらをアルファベット順に並べ替えます。 DOM を更新するとき、可能な限り安価な DOM の変更を行うために Vue はレンダリングを最適化します。 これは、最初の todo 要素を削除して、再度リストの最後に追加することを意味するかもしれません。 -The problem is, there are cases where it's important not to delete elements that will remain in the DOM. For example, you may want to use `` to animate list sorting, or maintain focus if the rendered element is an ``. In these cases, adding a unique key for each item (e.g. `:key="todo.id"`) will tell Vue how to behave more predictably. +問題は、DOM に残る要素を削除しないことが重要となる場合があることです。 例えば、 `` を使用してリストの並べ替えをアニメーション化する場合だったり、レンダリングされた要素が `` の時はフォーカスを維持したいといった場合があります。 このような場合、アイテムごとに一意のキー (`:key="todo.id"` など) を追加することで、 Vue に対してどうしたらより予期した通りの動作ができるかを伝えることができます。 -In our experience, it's better to _always_ add a unique key, so that you and your team simply never have to worry about these edge cases. Then in the rare, performance-critical scenarios where object constancy isn't necessary, you can make a conscious exception. +これまでの経験から、あなたとあなたのチームがこれらのエッジケースについて心配する必要がないように、 _常に_ 一意のキーを追加することをお勧めします。 その上で、オブジェクトの一貫性が必要なくてパフォーマンスが重要な稀なシナリオにおいては、意識的な例外を作成すると良いでしょう。 :::
-

Bad

+

悪い例

``` html
    @@ -171,7 +172,7 @@ In our experience, it's better to _always_ add a unique key, so that you and you
-

Good

+

良い例

``` html
    @@ -185,18 +186,18 @@ In our experience, it's better to _always_ add a unique key, so that you and you ```
-### Avoid `v-if` with `v-for` essential +### `v-for` と一緒に `v-if` を使うのを避ける 必須 -**Never use `v-if` on the same element as `v-for`.** +**`v-for` と同じ要素に `v-if` を決して使わないでください。** -There are two common cases where this can be tempting: +こうしたくなる一般的なケースが 2 通りほどあります: -- To filter items in a list (e.g. `v-for="user in users" v-if="user.isActive"`). In these cases, replace `users` with a new computed property that returns your filtered list (e.g. `activeUsers`). +- リストのアイテムをフィルタリングする時 (`v-for="user in users" v-if="user.isActive"` のように)。このような場合、 `users` をフィルタリングをされたリストを返す新しい算出プロパティ (例えば `activeUsers`) に置き換えます。 -- To avoid rendering a list if it should be hidden (e.g. `v-for="user in users" v-if="shouldShowUsers"`). In these cases, move the `v-if` to a container element (e.g. `ul`, `ol`). +- リストを非表示にする必要がある場合に、リストがレンダリングされるのを避ける時 (`v-for="user in users" v-if="shouldShowUsers"` のように)。このような場合、 `v-if` をコンテナ要素 (例えば `ul`, `ol`)に移動します。 -::: details Detailed Explanation -When Vue processes directives, `v-for` has a higher priority than `v-if`, so that this template: +::: details 詳細な説明 +Vue がディレクティブを処理する場合、`v-for` は `v-if` よりも優先度が高いため、次のようなテンプレートは: ``` html
    @@ -210,19 +211,9 @@ When Vue processes directives, `v-for` has a higher priority than `v-if`, so tha
``` -Will be evaluated similar to: - -``` js -this.users.map(user => { - if (user.isActive) { - return user.name - } -}) -``` - -So even if we only render elements for a small fraction of users, we have to iterate over the entire list every time we re-render, whether or not the set of active users has changed. +`v-if` ディレクティブが最初に評価され、反復変数の `user` がこの時点では存在しないためエラーが投げられます。 -By iterating over a computed property instead, like this: +これは、代わりに算出プロパティを元に反復処理をすることで修正できます。次のようになります: ``` js computed: { @@ -243,44 +234,22 @@ computed: { ``` -We get the following benefits: - -- The filtered list will _only_ be re-evaluated if there are relevant changes to the `users` array, making filtering much more efficient. -- Using `v-for="user in activeUsers"`, we _only_ iterate over active users during render, making rendering much more efficient. -- Logic is now decoupled from the presentation layer, making maintenance (change/extension of logic) much easier. - -We get similar benefits from updating: +または、 `v-for` と一緒に `