Vue.js 组件样式指南.zip

# Vue.js Component Style Guide <p align="center"> <img src="https://raw.githubusercontent.com/pablohpsilva/vuejs-component-style-guide/master/img/logo.png"/> </p> ### Translations * [Brazilian Portuguese](https://pablohpsilva.github.io/vuejs-component-style-guide/#/portuguese) * [Chinese](https://pablohpsilva.github.io/vuejs-component-style-guide/#/chinese) * [Japanese](https://pablohpsilva.github.io/vuejs-component-style-guide/#/japanese) * [Korean](https://pablohpsilva.github.io/vuejs-component-style-guide/#/korean) * [Russian](https://pablohpsilva.github.io/vuejs-component-style-guide/#/russian) ## Purpose This guide provides a uniform way to structure your [Vue.js](http://vuejs.org/) code. Making it: * easier for developers/team members to understand and find things. * easier for IDEs to interpret the code and provide assistance. * easier to (re)use build tools you already use. * easier to cache and serve bundles of code separately. This guide is inspired by the [RiotJS Style Guide](https://github.com/voorhoede/riotjs-style-guide) by [De Voorhoede](https://github.com/voorhoede). ## Table of Contents * [Module based development](#module-based-development) * [vue component names](#vue-component-names) * [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) * [Component structure](#component-structure) * [Component event names](#component-event-names) * [Avoid `this.$parent`](#avoid-thisparent) * [Use `this.$refs` with caution](#use-thisrefs-with-caution) * [Use component name as style scope](#use-component-name-as-style-scope) * [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) <!-- * [Use `*.vue` extension](#use-vue-extension) --> <!-- * [Add badge to your project](#add-badge-to-your-project) --> ## Module based development Always construct your app out of small modules which do one thing and do it well. A module is a small self-contained part of an application. The Vue.js library is specifically designed to help you create *view-logic modules*. ### Why? Small modules are easier to learn, understand, maintain, reuse and debug. Both by you and other developers. ### How? Each Vue component (like any module) must be [FIRST](https://addyosmani.com/first/): *Focused* ([single responsibility](http://en.wikipedia.org/wiki/Single_responsibility_principle)), *Independent*, *Reusable*, *Small* and *Testable*. If your component does too much or gets too big, split it up into smaller components which each do just one thing. As a rule of thumb, try to keep each component file less than 100 lines of code. Also ensure your Vue component works in isolation. For instance by adding a stand-alone demo. [↑ back to Table of Contents](#table-of-contents) ## Vue Component Names Each component name must be: * **Meaningful**: not over specific, not overly abstract. * **Short**: 2 or 3 words. * **Pronounceable**: we want to be able to talk about them. Vue component names must also be: * **Custom element spec compliant**: [include a hyphen](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name), don't use reserved names. * **`app-` namespaced**: if very generic and otherwise 1 word, so that it can easily be reused in other projects. ### Why? * The name is used to communicate about the component. So it must be short, meaningful and pronounceable. ### How? ```html <!-- recommended --> <app-header></app-header> <user-list></user-list> <range-slider></range-slider> <!-- avoid --> <btn-group></btn-group> <!-- short, but unpronounceable. use `button-group` instead --> <ui-slider></ui-slider> <!-- all components are ui elements, so is meaningless --> <slider></slider> <!-- not custom element spec compliant --> ``` [↑ back to Table of Contents](#table-of-contents) ## Keep component expressions simple Vue.js's inline expressions are 100% Javascript. This makes them extremely powerful, but potentially also very complex. Therefore you should **keep expressions simple**. ### Why? * Complex inline expressions are hard to read. * Inline expressions can't be reused elsewhere. This can lead to code duplication and code rot. * IDEs typically don't have support for expression syntax, so your IDE can't autocomplete or validate. ### How? If it gets too complex or hard to read **move it to methods or computed properties**! ```html <!-- recommended --> <template> <h1> {{ `${year}-${month}` }} </h1> </template> <script type="text/javascript"> export default { computed: { month() { return this.twoDigits((new Date()).getUTCMonth() + 1); }, year() { return (new Date()).getUTCFullYear(); } }, methods: { twoDigits(num) { return ('0' + num).slice(-2); } }, }; </script> <!-- avoid --> <template> <h1> {{ `${(new Date()).getUTCFullYear()}-${('0' + ((new Date()).getUTCMonth()+1)).slice(-2)}` }} </h1> </template> ``` [↑ back to Table of Contents](#table-of-contents) ## Keep component props primitive While Vue.js supports passing complex JavaScript objects via these attributes, you should try to **keep the component props as primitive as possible**. Try to only use [JavaScript primitives](https://developer.mozilla.org/en-US/docs/Glossary/Primitive) (strings, numbers, booleans) and functions. Avoid complex objects. ### Why? * By using an attribute for each prop separately the component has a clear and expressive API; * By using only primitives and functions as props values our component APIs are similar to the APIs of native HTML(5) elements; * By using an attribute for each prop, other developers can easily understand what is passed to the component instance; * When passing complex objects it's not apparent which properties and methods of the objects are actually being used by the custom components. This makes it hard to refactor code and can lead to code rot. ### How? Use a component attribute per props, with a primitive or function as value: ```html <!-- recommended --> <range-slider :values="[10, 20]" :min="0" :max="100" :step="5" @on-slide="updateInputs" @on-end="updateResults"> </range-slider> <!-- avoid --> <range-slider :config="complexConfigObject"></range-slider> ``` [↑ back to Table of Contents](#table-of-contents) ## Harness your component props In Vue.js your component props are your API. A robust and predictable API makes your components easy to use by other developers. Component props are passed via custom HTML attributes. The values of these attributes can be Vue.js plain strings (`:attr="value"` or `v-bind:attr="value"`) or missing entirely. You should **harness your component props** to allow for these different cases. ### Why? Harnessing your component props ensures your component will always function (defensive programming). Even when other developers later use your components in ways you haven't thought of yet. ### How? * Use defaults for props values. * Use `type` option to [validate](http://vuejs.org/v2/guide/components.html#Prop-Validation) values to an expected type.**[1\*]** * Check if props exists before using it. ```html <template> <input type="range" v-model="value" :max="max" :min="min"> </template> <script type="text/javascript"> export default { props: { max: { type: Number, // [1*] This will validate the 'max' prop to be a Number. default() { return 10; }, }, min: { type: Number, default() { return 0; }, }, value: { type: Number, default() { return 4; }, }, }, }; </script> ``` [↑ back to