pablohpsilva / vuejs-component-style-guide Goto Github PK
View Code? Open in Web Editor NEWVue.js Component Style Guide
Home Page: https://pablohpsilva.github.io/vuejs-component-style-guide
Vue.js Component Style Guide
Home Page: https://pablohpsilva.github.io/vuejs-component-style-guide
I really appreciate the time put for creating this guide. But I do not agree too much with the order proposed for <template>
before <script>
.
<template>
and <style>
next each other simplifies to think about structure and style together, without having to scroll up and down all the time while writing the styles.Anyway, I know it's just my personal opinion, but I'd like to see more people contributing with the discussion about advantages and disadvantages of each approach.
This section stipulates this:
assigning this to a variable named component the variable tells developers it's bound to the component instance wherever it's used.
The code example attached does not define any variable named component. It's confusing.
Sample code in the Keep component props primitive section contains several typos:
<range-slider
:values="[10, 20]"
min="0" <!-- Should be :min="..." for evaluating as JS expression to Number -->
max="100" <!-- Should be :max="..." for evaluating as JS expression to Number -->
step="5" <!-- Should be :step="..." for evaluating as JS expression to Number -->
:on-slide="updateInputs" <!-- Should be @on-slide="..." -->
:on-end="updateResults"> <!-- Should be @on-end="..." -->
</range-slider>
See also Literal vs. Dynamic
This question comes regularly to head for any web component interface.
We learned that a component should be self sufficient and reusable.
The problem is:
It's always complicated to find the right balance.
I wonder if there are key points/ideas that can help bring better web component interfaces.
I think the search field could be a component and assume that it is reusable.
Just so you get an idea of what I have in mind:
var searchField = {
// One prop for the url to call on Field keypress.enter or search button clicked.
props: {
request: String
},
data() {
return {
// The input value
searchValue: ''
};
},
methods: {
search() {
// Request the server with `${this.request}?q=${this.searchValue}`
}
}
};
It could also be emitting a search
event to inform the parent of any search trigger, instead of having a prop.
This component could allow sorting (date, specific data, ...) or even different layouts.
It will have to be strongly coupled to the Result list component. Since it filters the result list.
Should Filter toolbar and Result list components be as one?
Otherwise I'd be creating a component that only works properly with only one of my component library.
This is just a v-for
of anything actually.
So basically it shouldn't require a component.
But note that the list could be paginated, infinite scrolled, etc.
So maybe there should be some kind of list component?
Something like:
var list = {
props: {
layout: String,
validator(value) {
return value === 'paging' || value === 'infinite' || value === 'scroll';
},
default: 'scroll'
}
};
Note the above is just an example!
Feel free to compare the idea to any other situation.
I would like to hear about other's experience on separating components, building pages.
I hope we can find some best practices or key points on that matter.
A section showing best practice application structure. I'll setup a pull request if you think its a good idea 😄
.
| ── build/ # exported app files
| |--- ...
| -- src/
| | -- app.js # app entry file
| |-- components/ # Vue components
| │ | ---- ...
| | --- assets/ # module assets (processed by webpack)
| | --- ...
| -- index.html # index.html template
--- package.json # build scripts and dependencies
https://github.com/pablohpsilva/vuejs-component-style-guide#why-6
Again, grouping makes the component easier to read (name; extends; props, data and computed; components; watch and methods; lifecycle methods, etc.);
export default {
// Do not forget this little guy
name: 'RangeSlider',
// share common functionality with component mixins
mixins: [],
// compose new components
extends: {},
// component properties/variables
props: {
bar: {}, // Alphabetized
foo: {},
fooBar: {},
},
// variables
data() {},
computed: {},
// when component uses other components
components: {},
// methods
watch: {},
methods: {},
// component Lifecycle hooks
beforeCreate() {},
mounted() {},
};
I suggest components
be placed after extends
and before props
,
because it is intensively related to the<template>
on top, and nothing else.
like: https://github.com/vuejs/vue-hackernews-2.0/blob/master/src/views/ItemList.vue
I suffer from scrolling too much, and think it is not relational(rational).
Any thoughts?
Cheers!
Options is a riot term. In Vue it's props
. Options usually refers to the component's definition options.
Can you tell more about this topic? I am confused how to implement this instead of using const self = this
Have you considered creating a basic example application which uses all these various "rules" and "guides"
// methods
watch: {}.
methods: {}
My question is, watch
supposed to be a watcher instead of methods
.
It would be better change to
// watch and methods
watch: {},
methods: {}
While reading the paragraph about avoiding this.$refs
I thought it wasn't clear enough that you mean "avoid it to access subcomponents".
this.$refs
can also be used to access any DOM element's native API and in this case it is pretty useful and can't be done otherwise.
Would you prefer a PR ?
I developed this template https://github.com/InCuca/vue-standalone-component/ using my experience with Polymer components: paper, iron, etc. In this template I tried to create a standalone component using https://github.com/vue-styleguidist/vue-styleguidist, the next step is add karma tests for a full self-contained component strucuture.
What do you think about linking some of the community made templates in the docs (there are more in github)?
Thank you for the guide, it will definitely help.
In the Why of Harness your component options states Use type conversion to cast option values to expected type
. As Vue doesn't support props conversions, I must assume the conversion is expected to be done by a computed property or when used. It would be interesting to put some more words and example of best practice about it.
https://github.com/pablohpsilva/vuejs-component-style-guide#how-6
I'd update this example to to follow your naming scheme name: 'RangerWrapper'
, just to be consistent so it's not 1 word.
位置:Component event names
Events should either end in verbs in the infinitive form (e.g. client-api-load) or nouns (e.g drive-upload-success) (source);
事件命名应该以动词(如 client-api-load) 或是 形容词(如 drive-upload-success)结尾。
形容词 应为 名词。
I hope you're kiddin with this recommendation. Nowadays most IDEs got nice defaults for <script>
and, hey, HTML5 went towards simplification, not exausting developers by endless useless xmlns
and other stuff. For example Webstorm insists that you'll use type="text/babel"
for script tag to correctly interpret ES6 (skipping defaults). But it only means that this IDE is buggy and we'll need to force their devs to fix this bug. There are many IDEs on the market, and you have a freedom to choose the right one.
Anyway, thank you for sharing this doc. Our team has internal document on component styling for Vue.js, part of it is comparable with your proposal, but definitely you have a worth things that we missed.
I also should say that it would be nice to take 1.0 into account.
Hello.
It is great to have found your style guide.
While learning Vue I found it is flexible; allowing multiple ways to accomplish the same functionality. The flexibility also presents a challenge when trying to determine which approach to take.
Your approach of using Why/How to describe a uniform set of patterns is excellent. Thank you.
Having read your explanations for the directory structure in your recent post regarding the vue-material-boilerplate, I'd like to suggest adding a version of it to this style guide.
Thanks again. I found your style guide yesterday while looking for tips on a good directory structure and then today saw your post. Both helped answer my questions.
谨慎使用 this.$refs标题下第一段第二排:在使用的的时候,多了一个的
如果一个组件需要访问其父组件的上下文,那么该组件将不能再其它上下文中复用。
“再”写错了。
I would say this section is opinionated outside of the scope of Vue components, into a field of CSS which is controversial. It advises BEM and OOCSS which are methodologies which some people choose not to subscribe to knowingly.
Also exemplifies a kind of nesting one should probably avoid for a few reasons: MyCompoennt li {}
Also advises to use both <style scoped>
along with css scoping, without explaining any substantial benefit.
https://github.com/pablohpsilva/vuejs-component-style-guide#use-component-name-as-style-scope
I am rising this ticket to discuss about a best practice for the below, and if results of interest add it as a style guide.
A collection of components can be registered globally or locally as required. Both would have the same output but there are different implications.
Is easier to use, set it once and use as required. It will bloat the code, as the entire library get installed. Seem good approach for prototyping, tests, etc.
import Vue from 'vue'
import MyLibrary from 'my-library'
Vue.install(MyLibrary)
export default {
template: '<my-lib-button></my-lib-button>'
}
You only import what you use making it possible to take advantage of tree-shaking.
import Button from 'my-library/lib/button'
export default {
components: { 'MyButton': Button },
template: '<my-button></my-button>'
}
this url from the description is broken
https://pablohpsilva.github.io/vuejs-component-style-guide
When using the dom as the template there are limitations and one is particullary annoying. As the browser will lowercase the entire tag, events listeners declared as @myEvent
would be saved as myevent
and thus ignored when the component emmits myEvent
. The same happens with props names, but in my tests seems Vue does the conversion.
As best practice the events should be named always as kebab case, $emit('my-event')
.
Very good the guide.
I would like to know your opinions about /deep/ selector
.
It turns out that the father needs a change in the child only in the visual. I do not know if this violates FIRST.
This feature is implemented in 12.2.0 (vue-loader) May 2017
Issue: vuejs/vue-loader#661
I like this feature because it avoids increasing the code in the child components.
For example, create a props
in the child just to increase the space (margin/padding) in style inline
and then one more props
to change other styles. It does not sound good to me.
/deep/ selector example:
<template>
<icon name="phone" />
</template>
<style scoped>
.link:hover /deep/ .icon svg {
fill: white;
}
</style>
Particularly this sentence: "app- namespaced: if very generic and otherwise 1 word, so that it can easily be reused in other projects."
Very generic components should have "app" as a namespace? Or should they have your app's name as a namespace ("myapp-")? Or is it using app as a namespace because in the example it is descriptive ( app-header for the header of the app)
Couldn't very generic components be easily used elsewhere? It sounds like it's saying to app-namespace things if they're very generic and otherwise make them one word, but this sentence could be read in 2 different ways.
Am I supposed to literally add app-
in front of all components that are 1 word AND generic and not to any other ones?
I'm happy to try and clarify this if I can make it make sense to myself :)
#use-script-inside-component
anchor is not found in this line
「 put script inside a <script> component」
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.