From ff86c952ef96fa477c8964722114cfb2a5366466 Mon Sep 17 00:00:00 2001 From: Jasper Moelker Date: Mon, 8 Jul 2019 21:09:34 +0200 Subject: [PATCH 1/7] Update link to "valid custom element name" spec The old reference no longer exists. The same change was made in the "upstream" Riot Style Guide repository: https://github.com/voorhoede/riotjs-style-guide/pull/65/commits/c60d7863e8a095965025974f1414f44317f2ff4d --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bb685a8..7a7ffe1 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ Each component name must be: Vue component names must also be: -* **Custom element spec compliant**: [include a hyphen](https://www.w3.org/TR/custom-elements/#concepts), don't use reserved names. +* **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? From 442f5fa9878c86eb95ca8bbf622cb3c7e311b948 Mon Sep 17 00:00:00 2001 From: Alireza Arabshahi Date: Thu, 21 Jul 2022 21:46:39 +0430 Subject: [PATCH 2/7] add persian translation (part 1) --- README-FA.md | 735 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 735 insertions(+) create mode 100644 README-FA.md diff --git a/README-FA.md b/README-FA.md new file mode 100644 index 0000000..bc022e2 --- /dev/null +++ b/README-FA.md @@ -0,0 +1,735 @@ +# Vue.js راهنمای سبک نگارش کامپوننت در + +

+ +

+ +### ترجمه ها + +- [فارسی](https://pablohpsilva.github.io/vuejs-component-style-guide/#/) +- [پرتغالی برزیلی](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/#/japanese) +- [کره ای](https://pablohpsilva.github.io/vuejs-component-style-guide/#/korean) +- [روسی](https://pablohpsilva.github.io/vuejs-component-style-guide/#/russian) + +## هدف + +این راهنما یک راه متحد الشکل برای ساختار دادن به کد [Vue.js](http://vuejs.org/) شما فراهم می کند. موارد زیر را ممکن می سازد: + +- برای توسعه دهندگان و اعضای تیم فهمیدن و پیدا کردن کد ها آسان تر است. +- برای محیط های یکپارچه توسعه (IDEs) تفسیر کد و فراهم کردن پشتیبانی آسان تر است. +- استفاده و یا استفاده مجدد از ابزار های build که قبلا استفاده می کردید آسان تر است. +- نهان سازی (cache) و ارائه بسته های کد به طور جداگانه آسان تر است. + +این راهنما از مخزن [RiotJS Style Guide](https://github.com/voorhoede/riotjs-style-guide) که توسط [De Voorhoede](https://github.com/voorhoede) نوشته شده است الهام گرفته شده است. + +## فهرست مطالب + +- [توسعه مبتی بر ماژول](#module-based-development) +- [نام های کامپوننت Vue](#vue-component-names) +- [تکه کد های کامپوننت را ساده نگه دارید](#keep-component-expressions-simple) +- [پراپ های کامپوننت را ساده نگه دارید](#keep-component-props-primitive) +- [از پراپ های کامپوننت استفاده بهینه کنید](#harness-your-component-props) +- [کلمه کلیدی `this` را به کامپوننت نسبت دهید](#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 modules_ طراحی شده است . + +### چرا? + +ماژول های کوچک برای یادگیری و فهمیدن و نگهداری و استفاده مجدد و رفع مشکل راحت تر هستند. هم برای خود شما و هم برای توسعه دهندگان دیگر. + +### با چه روشی? + +Each Vue component (like any module) must be [در ابتدا](https://addyosmani.com/first/): _داشتن یک هدف مشخص_ ([تک وظیفه‌ای](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. + +[↑ برگشت به فهرست مطالب](#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. + +### چرا؟ + +- The name is used to communicate about the component. So it must be short, meaningful and pronounceable. + +### با چه روشی? + +```html + + + + + + + + + + + + + +``` + +[↑ برگشت به فهرست مطالب](#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**. + +### چرا؟ + +- 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. + +### با چه روشی? + +If it gets too complex or hard to read **move it to methods or computed properties**! + +```html + + + + + + +``` + +[↑ برگشت به فهرست مطالب](#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. + +### چرا؟ + +- 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. + +### با چه روشی? + +Use a component attribute per props, with a primitive or function as value: + +```html + + + + + + +``` + +[↑ برگشت به فهرست مطالب](#table-of-contents) + +## از پراپ های کامپوننت استفاده بهینه کنید + +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. + +### چرا؟ + +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. + +### با چه روشی? + +- 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 + + +``` + +[↑ برگشت به فهرست مطالب](#table-of-contents) + +## Assign `this` to `component` + +Within the context of a Vue.js component element, `this` is bound to the component instance. +Therefore when you need to reference it in a different context, ensure `this` is available as `component`. + +In other words: Do **NOT** code things like `var self = this;` anymore if you're using **ES6**. You're safe using Vue components. + +### چرا؟ + +- Using ES6, there's no need to save `this` to a variable; +- In general, when using arrow functions the lexical scope is kept +- If you're **NOT** using ES6 and, therefore, not using `Arrow Functions`, you'd have to add `this` to a variable. That's the only exception. + +### با چه روشی? + +```html + + + + +``` + +[↑ برگشت به فهرست مطالب](#table-of-contents) + +## Component structure + +Make it easy to reason and follow a sequence of thoughts. See the How. + +### چرا؟ + +- Having the component export a clear and grouped object, makes the code easy to read and easier for developers to have a code standard. +- Alphabetizing the properties, data, computed, watches, and methods makes them easy to find. +- Again, grouping makes the component easier to read (name; extends; props, data and computed; components; watch and methods; lifecycle methods, etc.); +- Use the `name` attribute. Using [vue devtools](https://chrome.google.com/webstore/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd?hl=en) and that attribute will make your development/testing easier; +- Use a CSS naming Methodology, like [BEM](https://medium.com/tldr-tech/bem-blocks-elements-and-modifiers-6b3b0af9e3ea#.bhnomd7gw), or [rscss](https://github.com/rstacruz/rscss) - [details?](#use-component-name-as-style-scope); +- Use the template-script-style .vue file organization, as recomended by Evan You, Vue.js creator. + +### با چه روشی? + +Component structure: + +```html + + + + + +``` + +[↑ برگشت به فهرست مطالب](#table-of-contents) + +## Component event names + +Vue.js provides all Vue handler functions and expressions are strictly bound to the ViewModel. Each component events should follow a good naming style that will avoid issues during the development. See the **Why** below. + +### چرا؟ + +- Developers are free to use native likes event names and it can cause confusion down the line; +- The freedom of naming events can lead to a [DOM templates incompatibility](https://vuejs.org/v2/guide/components.html#DOM-Template-Parsing-Caveats); + +### با چه روشی? + +- Event names should be kebab-cased; +- A unique event name should be fired for unique actions in your component that will be of interest to the outside world, like: upload-success, upload-error or even dropzone-upload-success, dropzone-upload-error (if you see the need for having a scoped prefix); +- Events should either end in verbs in the infinitive form (e.g. client-api-load) or nouns (e.g drive-upload-success) ([source](https://github.com/GoogleWebComponents/style-guide#events)); + +[↑ برگشت به فهرست مطالب](#table-of-contents) + +## Avoid `this.$parent` + +Vue.js supports nested components which have access to their parent context. Accessing context outside your vue component violates the [FIRST](https://addyosmani.com/first/) rule of [component based development](#module-based-development). Therefore you should **avoid using `this.$parent`**. + +### چرا؟ + +- A vue component, like any component, must work in isolation. If a component needs to access its parent, this rule is broken. +- If a component needs access to its parent, it can no longer be reused in a different context. + +### با چه روشی? + +- Pass values from the parent to the child component using attribute/properties. +- Pass methods defined on the parent component to the child component using callbacks in attribute expressions. +- Emit events from child components and catch it on parent component. + +[↑ برگشت به فهرست مطالب](#table-of-contents) + +## Use `this.$refs` with caution + +Vue.js supports components to have access to other components and basic HTML elements context via `ref` attribute. That attribute will provide an accessible way through `this.$refs` to a component or DOM element context. In most cases, the need to access **other components** context via `this.$refs` could be avoided. This is why you should be careful when using it to avoid wrong component APIs. + +### چرا؟ + +- A vue component, like any component, **must work in isolation**. If a component does not support all the access needed, it was badly designed/implemented. +- Properties and events should be sufficient to most of your components. + +### با چه روشی? + +- Create a good component API. +- Always focus on the component purpose out of the box. +- Never write specific code. If you need to write specific code inside a generic component, it means its API isn't generic enough or maybe you need a new component to manage other cases. +- Check all the props to see if something is missing. If it is, create an issue or enhance the component yourself. +- Check all the events. In most cases developers forget that Child-Parent communication (events) is needed, that's why they only remember the Parent-Child communication (using props). +- **Props down, events up!** Upgrade your component when requested with a good API and isolation as goals. +- Using `this.$refs` on components should be used when props and events are exhausted and having it makes sense (see the example below). +- Using `this.$refs` to access DOM elements (instead of doing `jQuery`, `document.getElement*`, `document.queryElement`) is just fine, when the element can't be manipulated with data bindings or for a directive. + +```html + + +``` + +```html + + +

Basic Modal

+ + + + + + + + +``` + +```html + + + + +``` + +[↑ برگشت به فهرست مطالب](#table-of-contents) + +## Use component name as style scope + +Vue.js component elements are custom elements which can very well be used as style scope root. +Alternatively the component name can be used as CSS class namespace. + +### چرا؟ + +- Scoping styles to a component element improves predictability as its prevents styles leaking outside the component element. +- Using the same name for the module directory, the Vue.js component and the style root makes it easy for developers to understand they belong together. + +### با چه روشی? + +Use the component name as a namespace prefix based on BEM and OOCSS **and** use the `scoped` attribute on your style class. +The use of `scoped` will tell your Vue compiler to add a signature on every class that your ` +``` + +[↑ برگشت به فهرست مطالب](#table-of-contents) + +## Document your component API + +A Vue.js component instance is created by using the component element inside your application. The instance is configured through its custom attributes. For the component to be used by other developers, these custom attributes - the component's API - should be documented in a `README.md` file. + +### چرا؟ + +- Documentation provides developers with a high level overview to a component, without the need to go through all its code. This makes a component more accessible and easier to use. +- A component's API is the set of custom attributes through which its configured. Therefore these are especially of interest to other developers which only want to consume (and not develop) the component. +- Documentation formalises the API and tells developers which functionality to keep backwards compatible when modifying the component's code. +- `README.md` is the de facto standard filename for documentation to be read first. Code repository hosting services (Github, Bitbucket, Gitlab etc) display the contents of the the README's, directly when browsing through source directories. This applies to our module directories as well. + +### با چه روشی? + +Add a `README.md` file to the component's module directory: + +``` +range-slider/ +├── range-slider.vue +├── range-slider.less +└── README.md +``` + +Within the README file, describe the functionality and the usage of the module. For a vue component its most useful to describe the custom attributes it supports as those are its API: + +# Range slider + +## Functionality + +The range slider lets the user to set a numeric range by dragging a handle on a slider rail for both the start and end value. + +This module uses the [noUiSlider](http://refreshless.com/nouislider/) for cross browser and touch support. + +## Usage + +`` supports the following custom component attributes: + +| attribute | type | description | +| ---------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `min` | Number | number where range starts (lower limit). | +| `max` | Number | Number where range ends (upper limit). | +| `values` | Number[] _optional_ | Array containing start and end value. E.g. `values="[10, 20]"`. Defaults to `[opts.min, opts.max]`. | +| `step` | Number _optional_ | Number to increment / decrement values by. Defaults to 1. | +| `on-slide` | Function _optional_ | Function called with `(values, HANDLE)` while a user drags the start (`HANDLE == 0`) or end (`HANDLE == 1`) handle. E.g. `on-slide={ updateInputs }`, with `component.updateInputs = (values, HANDLE) => { const value = values[HANDLE]; }`. | +| `on-end` | Function _optional_ | Function called with `(values, HANDLE)` when user stops dragging a handle. | + +For customising the slider appearance see the [Styling section in the noUiSlider docs](http://refreshless.com/nouislider/more/#section-styling). + +[↑ برگشت به فهرست مطالب](#table-of-contents) + +## Add a component demo + +Add a `index.html` file with demos of the component with different configurations, showing how the component can be used. + +### چرا؟ + +- A component demo proves the component works in isolation. +- A component demo gives developers a preview before having to dig into the documentation or code. +- Demos can illustrate all the possible configurations and variations a component can be used in. + +[↑ برگشت به فهرست مطالب](#table-of-contents) + +## Lint your component files + +Linters improve code consistency and help trace syntax errors. .vue files can be linted adding the `eslint-plugin-html` in your project. If you choose, you can start a project with ESLint enabled by default using `vue-cli`; + +### چرا؟ + +- Linting component files ensures all developers use the same code style. +- Linting component files helps you trace syntax errors before it's too late. + +### با چه روشی? + +To allow linters to extract the scripts from your `*.vue` files, put script inside a ` +``` + +[↑ برگشت به فهرست مطالب](#table-of-contents) + +--- + +## Wanna help? + +Fork it and Pull Request what you think it should be good to have or just create an [Issue](https://github.com/pablohpsilva/vuejs-component-style-guide/issues/new). + + + +## نویسندگان ترجمه + +- [Brazilian Portuguese](README-PTBR.md): Pablo Henrique Silva [github:pablohpsilva](https://github.com/pablohpsilva), [توییتر: @PabloHPSilva](https://twitter.com/PabloHPSilva) +- [روسی](https://pablohpsilva.github.io/vuejs-component-style-guide/#/russian): Mikhail Kuznetcov [github:shershen08](https://github.com/shershen08), [توییتر: @legkoletat](https://twitter.com/legkoletat) +- [فارسی](README-FA.md): علیرضا عربشاهی [github:AlirezaArabshahi](https://github.com/AlirezaArabshahi), [توییتر: @iialireza7](https://twitter.com/iialireza7) From 66762ac3b79df39f8b3f95a63464934da8c48d53 Mon Sep 17 00:00:00 2001 From: Alireza Arabshahi Date: Sun, 24 Jul 2022 22:19:46 +0430 Subject: [PATCH 3/7] add persian translation (part 2) --- README-FA.md | 50 +++++++++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/README-FA.md b/README-FA.md index bc022e2..b01aaf9 100644 --- a/README-FA.md +++ b/README-FA.md @@ -52,33 +52,33 @@ ### چرا? -ماژول های کوچک برای یادگیری و فهمیدن و نگهداری و استفاده مجدد و رفع مشکل راحت تر هستند. هم برای خود شما و هم برای توسعه دهندگان دیگر. +ماژول های کوچک برای یادگیری، فهمیدن، نگهداری، استفاده مجدد و رفع مشکلات چه برای خود شما و چه برای توسعه دهندگان دیگر راحت تر هستند. ### با چه روشی? -Each Vue component (like any module) must be [در ابتدا](https://addyosmani.com/first/): _داشتن یک هدف مشخص_ ([تک وظیفه‌ای](http://en.wikipedia.org/wiki/Single_responsibility_principle)), _Independent_, _Reusable_, _Small_ and _Testable_. +هر کامپوننت Vue (مثل یک ماژول) باید [در ابتدا](https://addyosmani.com/first/): _یک هدف مشخص_ ([تک وظیفه‌ای](http://en.wikipedia.org/wiki/Single_responsibility_principle)), _مستقل_, _قابل استفاده مجدد_, _کوچک_ و _تست پذیر_ باشد. -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. +اگر کامپوننت شما کار های زیادی انجام می دهد و یا خیلی بزرگ شده است آن را به کامپوننا های کوچکتر تقسیم کتید به طوری که هر کدام فقط یه کار را انجام دهند و بر حسب تجربه تلاش کنید که فایل هر کامپوننت کمتر از 100 خط کد باشد. +همچنین مطمئن شوید کامپوننت شما به صورت مجزا کار می کند برای مثال یک دمو مستقل برای آن قرار دهید. [↑ برگشت به فهرست مطالب](#table-of-contents) -## Vue Component Names +## [نام های کامپوننت Vue -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. +- **معنی دار**: نه بیش از حد دقیق و نه بیش از حد خلاصه شده و انتزاعی باشد. +- **کوتاه**: 2 یا 3 کلمه. +- **قابل تلفظ**: ما می خواهیم درباره آن ها حرف بزنیم. -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. +- **مطابق با تعریف عنصر سفارشی**: [شامل خط فاصله](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name), از نام های رزرو شده استفاده نکنید. +- **`app-` namespaced**: یا خیلی عمومی یا یک کلمه باشد که بتوان به راحتی از آن در پروژه های دیگر استفاده مجدد کرد. ### چرا؟ -- The name is used to communicate about the component. So it must be short, meaningful and pronounceable. +- از نام برای ارتباط برقرار کردن با کامپوننت استفاده می شود. پس باید کوتاه، با معنی و قابل تلفظ باشد. ### با چه روشی? @@ -100,7 +100,7 @@ Vue component names must also be: [↑ برگشت به فهرست مطالب](#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**. @@ -258,7 +258,7 @@ In other words: Do **NOT** code things like `var self = this;` anymore if you're } - + - +