From 8e423832ae4e19adbf6b664b75bf27ac01489fc4 Mon Sep 17 00:00:00 2001 From: Luke Shaheen Date: Wed, 10 May 2017 12:20:27 -0400 Subject: [PATCH 01/42] Fix anchor typo in table of contents --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 588f4fb..ff87c77 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ This guide is inspired by the [RiotJS Style Guide](https://github.com/voorhoede/ * [Module based development](#module-based-development) * [vue component names](#vue-component-names) -* [Keep component expressions simple](#keep-expressions-simple) +* [Keep component expressions simple](#keep-component-expressions-simple) * [Keep component props primitive](#keep-component-props-primitive) * [Harness your component props](#harness-your-component-props) * [Assign `this` to `component`](#assign-this-to-component) From 29c901188d937da7f6b490c87ed2fa17a6bbe1fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9mi=20Vanrenterghem?= Date: Thu, 11 May 2017 14:22:08 +0200 Subject: [PATCH 02/42] Add "Create components when needed" section --- README.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/README.md b/README.md index ff87c77..a049e62 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,7 @@ This guide is inspired by the [RiotJS Style Guide](https://github.com/voorhoede/ * [Document your component API](#document-your-component-api) * [Add a component demo](#add-a-component-demo) * [Lint your component files](#lint-your-component-files) +* [Create components when needed](#create-components-when-needed) @@ -601,6 +602,29 @@ Note: JSHint does not accept `vue` as extension, but only `html`. [↑ back to Table of Contents](#table-of-contents) + +## Create components when needed + +### Why? + +Vue.js is a component framework based. Not knowing when to create components can lead to issues like: + +* If the component is too big, it probably will be hard to (re)use and maintain; +* If the component is too small, your project gets flooded, harder to make components communicate; + +### How? + +* Always remember to build your components for your project needs, but you should also try to think of them being able to work out of it. If they can work out of your project, such as a library, it makes them a lot more robust and consistent; +* It's always better to build your components as early as possible since it allows you to build your communications (props & events) on existing and stable components. + +### Rules + +* First, try to build obvious components as early as possible such as: modal, popover, toolbar, menu, header, etc. Overall, components you know for sure you will need later on. On your current page or globally; +* Secondly, on each new development, for a whole page or a portion of it, try to think before rushing in. If you know some parts of it should be a component, build it; +* Lastly, if you're not sure, then don't! Avoid polluting your project with "possibly useful later" components, they might just stand there forever, empty of smartness. Note it's better to break it down as soon as you realize it should have been, to avoid the complexity of compatibility with the rest of the project; + +[↑ back to Table of Contents](#table-of-contents) + --- ## Wanna help? From 85a91a0dcd9d43f74726512113d7ab0da3ba644d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9mi=20Vanrenterghem?= Date: Thu, 11 May 2017 14:26:01 +0200 Subject: [PATCH 03/42] Revert "Add "Create components when needed" section" This reverts commit 29c901188d937da7f6b490c87ed2fa17a6bbe1fc. --- README.md | 24 ------------------------ 1 file changed, 24 deletions(-) diff --git a/README.md b/README.md index a049e62..ff87c77 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,6 @@ This guide is inspired by the [RiotJS Style Guide](https://github.com/voorhoede/ * [Document your component API](#document-your-component-api) * [Add a component demo](#add-a-component-demo) * [Lint your component files](#lint-your-component-files) -* [Create components when needed](#create-components-when-needed) @@ -602,29 +601,6 @@ Note: JSHint does not accept `vue` as extension, but only `html`. [↑ back to Table of Contents](#table-of-contents) - -## Create components when needed - -### Why? - -Vue.js is a component framework based. Not knowing when to create components can lead to issues like: - -* If the component is too big, it probably will be hard to (re)use and maintain; -* If the component is too small, your project gets flooded, harder to make components communicate; - -### How? - -* Always remember to build your components for your project needs, but you should also try to think of them being able to work out of it. If they can work out of your project, such as a library, it makes them a lot more robust and consistent; -* It's always better to build your components as early as possible since it allows you to build your communications (props & events) on existing and stable components. - -### Rules - -* First, try to build obvious components as early as possible such as: modal, popover, toolbar, menu, header, etc. Overall, components you know for sure you will need later on. On your current page or globally; -* Secondly, on each new development, for a whole page or a portion of it, try to think before rushing in. If you know some parts of it should be a component, build it; -* Lastly, if you're not sure, then don't! Avoid polluting your project with "possibly useful later" components, they might just stand there forever, empty of smartness. Note it's better to break it down as soon as you realize it should have been, to avoid the complexity of compatibility with the rest of the project; - -[↑ back to Table of Contents](#table-of-contents) - --- ## Wanna help? From b0e8dd51d1d52f4e45473410fa9d88afe6bf55db Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9mi=20Vanrenterghem?= Date: Thu, 11 May 2017 14:27:05 +0200 Subject: [PATCH 04/42] Revert "Revert "Add "Create components when needed" section"" This reverts commit 85a91a0dcd9d43f74726512113d7ab0da3ba644d. --- README.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/README.md b/README.md index ff87c77..a049e62 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,7 @@ This guide is inspired by the [RiotJS Style Guide](https://github.com/voorhoede/ * [Document your component API](#document-your-component-api) * [Add a component demo](#add-a-component-demo) * [Lint your component files](#lint-your-component-files) +* [Create components when needed](#create-components-when-needed) @@ -601,6 +602,29 @@ Note: JSHint does not accept `vue` as extension, but only `html`. [↑ back to Table of Contents](#table-of-contents) + +## Create components when needed + +### Why? + +Vue.js is a component framework based. Not knowing when to create components can lead to issues like: + +* If the component is too big, it probably will be hard to (re)use and maintain; +* If the component is too small, your project gets flooded, harder to make components communicate; + +### How? + +* Always remember to build your components for your project needs, but you should also try to think of them being able to work out of it. If they can work out of your project, such as a library, it makes them a lot more robust and consistent; +* It's always better to build your components as early as possible since it allows you to build your communications (props & events) on existing and stable components. + +### Rules + +* First, try to build obvious components as early as possible such as: modal, popover, toolbar, menu, header, etc. Overall, components you know for sure you will need later on. On your current page or globally; +* Secondly, on each new development, for a whole page or a portion of it, try to think before rushing in. If you know some parts of it should be a component, build it; +* Lastly, if you're not sure, then don't! Avoid polluting your project with "possibly useful later" components, they might just stand there forever, empty of smartness. Note it's better to break it down as soon as you realize it should have been, to avoid the complexity of compatibility with the rest of the project; + +[↑ back to Table of Contents](#table-of-contents) + --- ## Wanna help? From 8f302aaf246367466f21e124af1cdf2ffbe5910d Mon Sep 17 00:00:00 2001 From: sqrtthree Date: Mon, 29 May 2017 12:20:45 +0800 Subject: [PATCH 05/42] :memo: Translate the new section Translate the 'Create components when needed' part. #39 --- README-CN.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/README-CN.md b/README-CN.md index ea5d555..b387c89 100644 --- a/README-CN.md +++ b/README-CN.md @@ -38,6 +38,7 @@ * [提供组件 API 文档](#提供组件-api-文档) * [提供组件 demo](#提供组件-demo) * [对组件文件进行代码校验](#对组件文件进行代码校验) +* [只在需要时创建组件](#只在需要时创建组件) ## 基于模块开发 @@ -586,6 +587,26 @@ jshint --config modules/.jshintrc --extra-ext=html --extract=auto modules/ 注：JSHint 不接受 `vue` 扩展名的文件，只支持 `html`。 +## 只在需要时创建组件 + +### 为什么？ + +Vue.js 是一个基于组件的框架。如果你不知道何时创建组件可能会导致以下问题： + +* 如果组件太大, 可能很难重用和维护; +* 如果组件太小，你的项目就会（因为深层次的嵌套而）被淹没，也更难使组件间通信; + +### 怎么做? + +* 始终记住为你的项目需求构建你的组件，但是你也应该尝试想到它们能够从中脱颖而出（独立于项目之外）。如果它们能够在你项目之外工作，就像一个库那样，就会使得它们更加健壮和一致。 +* 尽可能早地构建你的组件总是更好的，因为这样使得你可以在一个已经存在和稳定的组件上构建你的组件间通信（props & events）。 + +### 规则 + +* 首先，尽可能早地尝试构建出诸如模态框、提示框、工具条、菜单、头部等这些明显的（通用型）组件。总之，你知道的这些组件以后一定会在当前页面或者是全局范围内需要。 +* 第二，在每一个新的开发项目中，对于一整个页面或者其中的一部分，在进行开发前先尝试思考一下。如果你认为它有一部分应该是一个组件，那么就创建它吧。 +* 最后，如果你不确定，那就不要。避免那些“以后可能会有用”的组件污染你的项目。它们可能会永远的只是（静静地）待在那里，这一点也不聪明。注意，一旦你意识到应该这么做，最好是就把它打破，以避免与项目的其他部分构成兼容性和复杂性。 + [↑ 回到目录](#目录) --- From ad3b736c98700228fd0cac118c0900012c3060a6 Mon Sep 17 00:00:00 2001 From: sqrtthree Date: Mon, 29 May 2017 12:24:43 +0800 Subject: [PATCH 06/42] :pencil2: Fix a typo --- README-CN.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README-CN.md b/README-CN.md index b387c89..efc2c64 100644 --- a/README-CN.md +++ b/README-CN.md @@ -380,7 +380,7 @@ Vue.js 支持通过 `ref` 属性来访问其它组件和 HTML 元素。并通过

Basic Modal

- + From 4cb5d99b9d95973d4e585fed98ef35d950c2d591 Mon Sep 17 00:00:00 2001 From: sqrtthree Date: Mon, 29 May 2017 14:23:18 +0800 Subject: [PATCH 07/42] =?UTF-8?q?:sparkles:=20Add=20a=20link=20to=20see=20?= =?UTF-8?q?what=E2=80=99s=20changed=20between=20the=20current=20and=20the?= =?UTF-8?q?=20latest?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: sqrtthree --- README-CN.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README-CN.md b/README-CN.md index efc2c64..52b5746 100644 --- a/README-CN.md +++ b/README-CN.md @@ -1,5 +1,7 @@ # Vue.js 组件编码规范 +> 这个 [链接](https://github.com/pablohpsilva/vuejs-component-style-guide/compare/6c5831912f9926a447f4d4531e745d53609aeb33...pablohpsilva:master) 用来查看本翻译与英文版是否有差别（如果你没有看到 README.md 发生变化，那就意味着这份翻译文档是最新的）。 +

From 564c7de3c168de7bd63d827ecda7136e88747dc6 Mon Sep 17 00:00:00 2001 From: Lee Sun-Hyoup Date: Thu, 1 Jun 2017 16:01:18 +0900 Subject: [PATCH 08/42] Translate korean the new section Hello @pablohpsilva, Is it allow to put this page into the book that I am writing? Thank you :) --- README-KR.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/README-KR.md b/README-KR.md index e95d043..b6e3d8a 100644 --- a/README-KR.md +++ b/README-KR.md @@ -595,6 +595,29 @@ jshint --config modules/.jshintrc --extra-ext=html --extract=auto modules/ [↑ 목차로 돌아가기](#목차) +## 필요하다면 컴포넌트 만들기 + +### 왜 그렇게 하나요? + +Vue.js는 컴포넌트 기반 프레임워크 입니다. 컴포넌트 만드는 시기를 모르면 다음과 같은 문제가 발생할 수 있습니다. + +* 컴포넌트가 너무 크다면, 사용 및 유지보수가 어려울 수 있습니다. +* 컴포넌트가 너무 작다면, 프로젝트가 너무 커지고 컴포넌트간 통신이 어려울 수 있습니다. + +### 어떻게 하나요? + +* 프로젝트 요구 사항에 맞는 컴포넌트를 작성하는 것을 잊으면 안되지만 특정 기능을 컴포넌트를 사용하여 만들 수 있다고 생각해야 합니다. 라이브러리처럼 작성 할 수 있다면 훨씬 강력하고 일관성이 있습니다. +* 가능한 빨리 컴포넌트를 만들면 기존 컴포넌트에 안정적으로 통신(props 및 event)을 구현 할 수 있습니다. + +### 규칙 + +* 첫째, 가능한 빠르게 현재 작성 중인 페이지 또는 전체적으로 모달, 팝 오버, 툴바, 메뉴, 헤더 등 필요할 것이 확실한 컴포넌트를 작성하세요. +* 둘째, 전체 페이지 또는 그 일부분에 대해 새롭게 개발하는 것을 서두르기 전에 생각해보세요. 당신이 작성해야할 그 일부분이 확실히 컴포넌트가 될 수 있을때 작성하세요. +* 마지막으로, 확실하지 않다면 만들지마세요! "나중에 쓸모있는 컴포넌트"로 프로젝트를 오염시키지 마십시오. 그 컴포넌트는 영원히 사용하지 않을 수도 있습니다. 프로젝트의 컴포넌트와의 호환성의 복잡성을 피하기 위해 필요할 때 컴포넌트를 만드는게 좋습니다. + +[↑ 목차로 돌아가기](#목차) + + --- ## 도움을 주시겠습니까? From 6ec8f1fa645299d2d750b096074c1529e3a1432f Mon Sep 17 00:00:00 2001 From: To-maruyama Date: Sat, 3 Jun 2017 00:29:03 +0900 Subject: [PATCH 09/42] add README-JP.md --- README-JP.md | 686 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 686 insertions(+) create mode 100644 README-JP.md diff --git a/README-JP.md b/README-JP.md new file mode 100644 index 0000000..87f6acf --- /dev/null +++ b/README-JP.md @@ -0,0 +1,686 @@ +# Vue.js コンポーネント スタイル ガイド + +

+ +

+ +### 翻訳 +* [ブラジルポルトガル語](https://pablohpsilva.github.io/vuejs-component-style-guide/#/portuguese) +* [中国語](https://pablohpsilva.github.io/vuejs-component-style-guide/#/chinese) +* [韓国語](https://pablohpsilva.github.io/vuejs-component-style-guide/#/korean) +* [ロシア語](https://pablohpsilva.github.io/vuejs-component-style-guide/#/russian) + +## 目的 + +このガイドはあなたの[Vue.js](http://vuejs.org/) のコードを統一する方法を提供します。 + +* 開発者／チームメンバがより問題を理解し、見つけやすくする。 +* IDEがよりコードを解釈し、支援を提供しやすくする。 +* すでに使用しているビルドツールを（再）利用しやすくする。 +* 別々のコードの塊を蓄え、供給しやすくする。 + +このガイドは[De Voorhoede](https://github.com/voorhoede)による[RiotJS Style Guide](https://github.com/voorhoede/riotjs-style-guide)に刺激を受け作られました。 + +## 目次 + +* [モジュールベースの開発](#module-based-development) +* [Vueコンポーネントの名前](#vue-component-names) + +* [コンポーネントの記述をシンプルに保つ](#keep-component-expressions-simple) +* [コンポーネントのpropをプリミティブに保つ](#keep-component-props-primitive) +* [コンポーネントのpropの利用](#harness-your-component-props) +* [`this`を`component`に割り当てる](#assign-this-to-component) +* [コンポーネント構成](#component-structure) +* [コンポーネントイベント名](#component-event-names) +* [`this.$parent`を避ける](#avoid-thisparent) +* [`this.$refs`は注意して使用する](#use-thisrefs-with-caution) +* [スタイルスコープとしてコンポーネント名を使用する](#use-component-name-as-style-scope) +* [コンポーネントAPIをドキュメント化する](#document-your-component-api) +* [コンポーネントデモの追加](#add-a-component-demo) +* [コンポーネントファイルをLintする](#lint-your-component-files) +* [必要に応じてコンポーネントを作成する](#create-components-when-needed) + + + +## モジュールベースの開発 + +常に単一の機能を持つ小さなモジュールからアプリケーションを構築しましょう。 + +モジュールはアプリケーションの自己完結型の小さな部品です。特にVue.jsライブラリはあなたが*view-logicなモジュール*を作れるように設計されています。 + +### 理由 + +小さなモジュールにすることで、あなたと他の開発者両方にとって、学びやすく、理解しやすく、維持しやすく、再利用しやすく、そして、 +デバッグしやすくなります。 + +### 方法 + +各Vueコンポーネント（モジュールのようなもの）は [FIRST](https://addyosmani.com/first/): ひとつのことに集中し (*Focused* ([単一責任](http://en.wikipedia.org/wiki/Single_responsibility_principle)))、独立していて(*Independent*)、 再利用可能で(*Reusable*)、小さく(*Small*) そしてテスト可能 (*Testable*)でなければなりません。 + +もしあなたのコンポーネントが多くのことをしていて大きすぎる場合、ひとつのことだけをする、より小さなコンポーネントに分けましょう。 +経験則から言うと、各コンポーネントは１００行以下のコードになるようにするのがいいでしょう。また、例えばスタンドアローンのデモを追加することによって、 +Vueコンポーネントが独立して動作することを確認しましょう。 + +[↑ 目次に戻る](#table-of-contents) + + +## Vueコンポーネントの名前 + +各コンポーネントの名前は、 + +* **意味のある名前で**: 具体的過ぎず、抽象的過ぎず。 +* **短く**: ２または３語。 +* **発音可能**: それらについて話せるようにしたい。 + +であるべきです。 + +さらにVueコンポーネントの名前は、 + +* **カスタム要素仕様に準拠**: [ハイフンを含み](https://www.w3.org/TR/custom-elements/#concepts)、 予約語は使用しない。 +* **`app-` ネームスペース**: 非常に汎用的、あるいは１語であれば、他のプロジェクトでも容易に再利用できる。 + +であるべきです。 + +### 理由 + +* 名前は、コンポーネントについて会話するときに使用されます。したがって、それは短く、意味があり、発音可能でなければなりません。 + +### 方法 + +```html + + + + + + + + + +``` + +[↑ 目次に戻る](#table-of-contents) + + +## コンポーネントの記述をシンプルに保つ + +Vue.jsのインラインの記述は100％JavaScriptです。これは非常に強力なことですが、複雑になる可能性もあるということです。 +ですので、**シンプルな記述を保つようにしましょう。**. + +### 理由 + +* 複雑なインラインの記述は判読困難です。 +* インラインの記述は他の場所で再利用できません。これはコードの重複と腐敗につながります。 +* IDEは基本的に式の構文サポート機能を持っていないため、自動補完や検証を行うことができません。 + +### 方法 + +もしあまりにも複雑だったり、判読困難な場合は**メソッド、またはcomputedプロパティに移動させましょう**! + +```html + + + + + + +``` + +[↑ 目次に戻る](#table-of-contents) + + +## コンポーネントのpropsをプリミティブに保つ + +Vue.jsは複雑なJavaScriptオブジェクトを渡せるようになっていますが, **コンポーネントのpropsはできるだけプリミティブに保つ** ようにするべきです。複雑なオブジェクトの使用を避け、[JavaScriptプリミティブ](https://developer.mozilla.org/en-US/docs/Glossary/Primitive)と関数のみを使うようにしましょう。 + +### 理由 + +* 各propの属性を別々に使用することにより、コンポーネントは明確で表現力豊かなAPIを持つことになります。 +* propsの値としてプリミティブとファンクションのみを使用することで、コンポーネントのAPIをネイティブHTML（5）のAPIに似たものにできます。 +* 各propの属性を使用することで、他の開発者がコンポネーントインスタンスに何が渡されるかを理解しやすくなります。 +* 複雑なオブジェクトが渡されると、そのオブジェクトのどのプロパティとメソッドが実際にカスタムコンポーネントで使われるかがわかりにくくなります。これによりコードのリファクタリングが難しくなり、腐敗を招くことになります。 + +### 方法 + +プリミティブまたは関数を値としたpropsごとのコンポーネント属性を使用します。 + +```html + + + + + + +``` + +[↑ 目次に戻る](#table-of-contents) + + +## コンポーネントのpropsの利用 + +Vue.jsでは、あなたのコンポーネントのpropsはあなたのAPIです。頑丈で予測しやすいAPIは、他の開発者があなたのコンポーネントを使用するのを簡単にします。 + +コンポーネントのpropsはカスタムHTML属性を介して渡されます。 これらの属性の値はVue.jsプレーンストリング (`:attr="値"` または `v-bind:attr="値"`)か、または無いこともあります。 あなたは **コンポーネントのpropsを利用** して、それらの異なるケースに対応できるようにしましょう。 + +### 理由 + +コンポーネントのpropsを利用することで、あなたのコンポーネントを常に機能するようになります（防御的プログラミング）。それは後で他の開発者が、あなたが想定していない方法でコンポーネントを使用する場合でもです。 + +### 方法 + +* propsのデフォルト値を使用します。 +* 期待するタイプの値の[検証](http://vuejs.org/v2/guide/components.html#Prop-Validation)のために、`type`オプションを使用します。**[1\*]** +* 使用される前にpropsが存在するかチェックします。 + +```html + + +``` + +[↑ 目次に戻る](#table-of-contents) + + +## `this`を`component`に割り当てる + +Vue.jsコンポーネントのコンテキスト内では、 `this`はコンポーネントインスタンスにバインドされています。 +したがって、別のコンテキストで参照する必要がある場合は、 `this` が`component`として使用できることを確認してください。 + +言い換えれば: `const self = this;`のようなコーディングはもう **しないで** ください。 Vueコンポーネントの使用は安全です。 + +### 理由 + +* `this`を`component`という名前の変数に代入することにより、この変数が使用されているコンポーネントインスタンスにバインドされていることが開発者に伝わります。 + +### 方法 + +```html + + + + +``` + +[↑ 目次に戻る](#table-of-contents) + + +## コンポーネント構成 + +論理的に考えやすく、思考の流れに従いやすいようにしましょう. 方法を見てください。 + +### 理由 + +* コンポーネントを明確かつグループ化されたオブジェクトとすることで、コードを読みやすくし、開発者はコードの基準を簡単に持てるようになります。 +* props、data、computed、watches、そしてmethodsをアルファベット順に並べることで、見つけやすくなります。 +* 繰り返しになりますが, コンポーネントをグループ化することで読みやすくなります (name、extends、props、dataそしてcomputed、components、 watch、methods、lifecycle methods、など); +* `name`属性を使いましょう. [vue devtools](https://chrome.google.com/webstore/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd?hl=en)とname属性を使うと、開発/テストが容易になります。 +* [BEM](https://medium.com/tldr-tech/bem-blocks-elements-and-modifiers-6b3b0af9e3ea#.bhnomd7gw)、または [rscss](https://github.com/rstacruz/rscss)のようなCSSの命名方法論を使いましょう。 - [詳細?](#use-component-name-as-style-scope); +* Vue.jsの製作者Evan Youが推奨するように、テンプレートスクリプト形式の.vueファイル構成を使用しましょう。 + +### 方法 + +コンポーネンのト構成: + +```html + + + + + +``` + +[↑ 目次に戻る](#table-of-contents) + +## コンポーネントイベント名 + +Vue.jsはすべてのVueハンドラ関数を提供し、式はViewModelに厳密にバインドされています。各コンポーネントのイベントは、開発中の問題を回避するような良い名前付けのスタイルを適用しましょう。 以下の **理由** を参照してください。 + +### 理由 + +* 開発者は好きなイベント名を自由に使うことができるため、混乱を招く可能性があります。 +* イベントに名前をつける自由は、 [DOMテンプレートの非互換性](https://vuejs.org/v2/guide/components.html#DOM-Template-Parsing-Caveats)につながる可能性があります。 + +### 方法 + +* イベント名前はケバブケースにするべきです。 +* あなたのコンポーネントで外部で関心を持つ独自のアクションのため、upload-success、upload-error、さらにはdropzone-upload-success、 dropzone-upload-errorのような固有の名前をつける必要があります。(スコープ付きプレフィックスを使用する必要がある場合は) +* イベント名は末尾が不定形の動詞(例 client-api-load)、または名詞(例 drive-upload-success)で終わるべきです。([出典](https://github.com/GoogleWebComponents/style-guide#events)); + +[↑ 目次に戻る](#table-of-contents) + +## `this.$parent`を避ける + +Vue.jsは、親コンテキストにアクセスできるネストされたコンポーネントをサポートしています。 あなたのVueコンポーネントの外部のコンテキストにアクセスすることは、 [モジュールベースの開発](#module-based-development)の[FIRST](https://addyosmani.com/first/)のルールに違反するため、 ** `this.$parent`の使用を避ける ** べきです。 + +### 理由 + +* vueコンポーネントは、他のコンポーネントと同様に、独立して動作する必要があります。 コンポーネントがその親にアクセスする必要がある場合、このルールは壊されます。 +* コンポーネントがその親にアクセスする必要がある場合、別のコンテキストで再利用することはできません。 + +### 方法 + +* 属性/プロパティを使用して、親から子コンポーネントに値を渡します。 +* 属性の式のコールバックを使用して、親コンポーネントで定義されたメソッドを子コンポーネントに渡します。 +* 子コンポーネントからイベントを発行し、それを親コンポーネントでキャッチします。 + +[↑ 目次に戻る](#table-of-contents) + +## `this.$refs`は注意して使用する + +Vue.jsは`ref`属性を介して他のコンポーネントや、基本的なHTML要素のコンテキストにアクセスできるコンポーネントをサポートしています。この属性は`this.$refs`を介して、コンポーネントまたDOM要素のコンテキストにアクセス可能な方法を提供します。ほとんどの場合、 `this.$refs`を介して **他のコンポーネント** のコンテキストにアクセスする必要性は避けることができます。このため、間違ったコンポーネントAPIを避けるためにこれを使用するときは注意が必要です。 + +### 理由 + +* vueコンポーネントは、他のコンポーネントと同様に、**独立して動作する必要があります**。 コンポーネントが必要なすべてのアクセスをサポートしていない場合、それは悪い設計/実装です。 +* ほとんどのコンポーネントでは、プロパティとイベントで十分です。 + +### 方法 + +* 良いコンポーネントAPIを作りましょう。 +* 独創的なコンポーネントの目的に常に注意してください。 +* 特殊なコードを書かないでください。ジェネリックコンポーネント内に特殊なコードを記述する必要がある場合は、APIが十分に一般的でないか、他のケースを管理するために新しいコンポーネントが必要になるということです。 +* すべてのpropsをチェックして、欠けているものがあるかどうか確認します。 もしあれば、課題を作成するかあなたのコンポーネントを強化しましょう。 +* すべてのイベントをチェックしましょう。ほとんどのケースで、開発者は子-親のコミュニケーション（イベント）が必要であることを忘れてしまいます。 そのため、（propsを使用した）親-子のコミュニケーションだけを覚えているのです。 +* **Propsは下へ、eventsは上へ!** ゴールとして良いAPIと分離を要求された場合、コンポーネントをアップグレードしましょう。 +* propsやeventsが消耗し、コンポーネントでの`this.$refs`の利用が利にかなっているときは、それを使用するべきです。 (下の例を参照してください). +* データバインディングやディレクティブで要素を操作できない場合、 (`jQuery`, `document.getElement*`, `document.queryElement`の代わりに) `this.$refs`を使用してDOM要素にアクセスすることは良い方法です。 + +```html + + +``` + +```html + + +

Basic Modal

+ + + + + + + + + +``` + +```html + + + + +``` + +[↑ 目次に戻る](#table-of-contents) + + +## スタイルスコープとしてコンポーネント名を使用する + +Vue.jsのコンポーネント要素は、スタイルスコープのルートとして非常によく使用されるカスタム要素です。 +あるいは、コンポーネント名はCSSクラスネームスペースとして、使用できます。 + +### 理由 + +* コンポーネント要素のスタイルをスコープすると、コンポーネントの外にスタイルが漏れるのを防ぐため、予測可能性が向上します。 + +* モジュールディレクトリに同じ名前を使用すると、Vue.jsコンポーネントとスタイルルートが同じところに属していることを開発者が理解しやすくなります。 + +### 方法 + +BEMとOOCSSに基づくネームスペースプレフィックスとしてコンポーネント名を使いましょう。 **そして** スタイルクラスで`scoped`属性を使いましょう。 +`scoped`を使用すると、` +``` + +[↑ 目次に戻る](#table-of-contents) + + +## コンポーネントAPIをドキュメント化する + +Vue.jsコンポーネントのインスタンスは、アプリケーション内のコンポーネント要素を使用して作成されます。インスタンスはそのカスタム属性によって構成されます。他の開発者がコンポーネントを使用するときのため、これらのカスタム属性（コンポーネントのAPI）を`README.md`ファイルに記述しましょう。 + +### 理由 + +* ドキュメンテーションは、開発者に、そのコードのすべてを伝えることなく、コンポーネントの概要を高レベルで表示します。これにより、コンポーネントのアクセスが容易になり、使いやすくなります。 +* コンポーネントのAPIは、それを構成するカスタム属性のセットです。したがって、これらは、コンポーネントを使用する（開発しない）開発者にとって特に重要です。 +* ドキュメンテーションはAPIを形式化し、コンポーネントのコードを変更するときに下位互換性を維持する機能を開発者に教えます。 +* `README.md`は最初に読み込まれるドキュメントのデファクトスタンダードファイル名です。 コードリポジトリホスティングサービス（Github、Bitbucket、Gitlabなど）は、ソースディレクトリを参照するときに、READMEファイルの内容を直接表示します。これは私たちのモジュールディレクトリにも当てはまります。 + +### 方法 + +コンポーネントのモジュールディレクトリに`README.md`ファイルを追加しましょう。 + +``` +range-slider/ +├── range-slider.vue +├── range-slider.less +└── README.md +``` + +READMEファイルに、モジュールの機能と使用方法を記述しましょう。 vueコンポーネントの場合、APIとしてサポートされているカスタム属性を記述するのが最も役立ちます。 + + +# Range slider + +## 機能 + +range sliderは、スライダーレールのハンドルを開始値と終了値の両方でドラッグして数値範囲を設定できます。 + +このモジュールはクロスブラウザとタッチサポートのため、noUiSliderを使用します。 + +## 使用方法 + +`` 次のカスタムコンポーネント属性をサポートしています: + +| 属性 | 型 | 説明 +| --- | --- | --- +| `min` | 数値 | レンジの始まりの数値 (下限)。 +| `max` | 数値 | レンジの終わりの数値 (上限). +| `values` | 数値[] *任意* | 開始値と終了値を含む配列。 例. `values="[10, 20]"`. デフォルトは`[opts.min, opts.max]`. +| `step` | 数値 *任意* | インクリメント/デクリメントの数値。デフォルトは1。 +| `on-slide` | 関数 *任意* | ユーザーが開始（`HANDLE == 0`）または終了（`HANDLE == 1`）ハンドルをドラッグしているときに、`(values, HANDLE)`で呼び出される関数。例. `on-slide={ updateInputs }` `component.updateInputs = (values, HANDLE) => { const value = values[HANDLE]; }`. +| `on-end` | 関数 *任意* | ユーザーがハンドルのドラッグを停止したとき、`(values, HANDLE)`で呼び出される関数。 + +スライダの外観をカスタマイズするには[noUiSliderドキュメントのStylingセクション](http://refreshless.com/nouislider/more/#section-styling)を参照してください。 + + +[↑ 目次に戻る](#table-of-contents) + + +## コンポーネントデモの追加 + +構成の異なるコンポーネントのデモを含むindex.htmlファイルを追加し、コンポーネントの使用方法を示しましょう。 + +### 理由 + +* コンポーネントのデモは、コンポーネントが単独で動作することを示します。 +* コンポーネントのデモは、ドキュメンテーションやコードを掘り起こす前に、開発者にプレビューを提供します。 +* デモでは、コンポーネントを使用できるすべての可能な構成とバリエーションを示すことができます。 + +[↑ 目次に戻る](#table-of-contents) + + +## コンポーネントファイルをLintする + +Lintersはコードの一貫性を高め、構文エラーの追跡に役立ちます。.vueファイルはプロジェクトに`eslint-plugin-html`を追加してlintすることができます。vue-cliを使用すれば、ESLintをデフォルトで有効にしてプロジェクトを開始できます。 + +### 理由 + +* コンポーネントファイルのLintは、すべての開発者が同じコードスタイルを使用するようにします。 +* コンポーネントファイルのLintは、遅くなる前に構文エラーの追跡をするのに役立ちます。 + +### 方法 + +lintersがあなたの`*.vue`ファイルからスクリプトを抽出するためには, [スクリプトを +``` + +Now let's investigate the desktop menu component. + +```html + + + +``` + +We can abstract the core functionalities of both into a mixin like this. + +```js +const MenuMixin = { + data () { + return { + language: 'EN' + } + }, + + methods: { + changeLanguage () { + if (this.language === 'DE') this.$set(this, 'language', 'EN') + if (this.language === 'EN') this.$set(this, 'language', 'DE') + } + } +} + +export default MenuMixin +``` + +To use the mixin, simply import into both components (I only show the mobile component). + +```html + + + + +[↑ back to Table of Contents](#table-of-contents) + --- ## Wanna help? From 7cb6e8727d1e03183f9113c173609c52ccd9b0fa Mon Sep 17 00:00:00 2001 From: cetaju Date: Sat, 29 Jul 2017 10:21:58 +0200 Subject: [PATCH 16/42] fixed wording and code example markdown --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 0256348..ba5df82 100644 --- a/README.md +++ b/README.md @@ -709,7 +709,7 @@ const MenuMixin = { export default MenuMixin ``` -To use the mixin, simply import into both components (I only show the mobile component). +To use the mixin, simply import it into both components (I only show the mobile component). ```html