Příručka:Konvence pro psaní kódu/Vue
Please do not mark this page for translation yet. Tuto stránku zatím neoznačujte k překladu. Stále se připravuje nebo obsahuje neúplné označení překladu, které by mělo být opraveno před označením k překladu. |
Tato stránka je v současnosti pracovní verzí.
|
Tato stránka dokumentuje pokyny pro vývoj MediaWiki, vytvořené v průběhu času na základě dohovoru vývojářů (nebo někdy na základě prohlášení hlavního vývojáře) |
Tato stránka popisuje kódovací konvence pro Vue v MediaWiki codebase. Viz také konvence JavaScript a CSS/LESS, které se vztahují na kód v souborech Vue.
Odkazování
Jako nástroj pro kvalitu kódu používáme ESLint.
Vlastní konfigurace pro Wikimedii (eslint-config-wikimedia
) obsahuje obecná i specifická pravidla MediaWiki pro kód Vue.
Aby ESLint rozpoznával definice komponent
Pro definici vaší komponenty musíte použít funkci defineComponent()
od Vue, aby ji ESLint jako takovou poznal (viz příklad níže).
Pokud ESLint zjistí, že toto nepoužíváte, upozorní vás a řekne vám, abyste to přidali, ale dokud to neuděláte, nebude schopen interpretovat váš kód jako kód Vue.
<script>
const { defineComponent } = require( 'vue' );
const AnotherComponent = require( './AnotherComponent.vue' );
module.exports = exports = defineComponent( {
name: 'MyComponent',
components: { AnotherComponent },
...
} );
</script>
Nastavení ESLint
Pokud již ve svém .eslintrc.json
používáte přednastavení wikimedia/client
nebo wikimedia/client/es6
z eslint-config-wikimedia balíčku, pravidla lint pro Vue se automaticky použijí na soubory .vue
.
Počínaje verzí 0.23.0 eslint-config-wikimedia jsou výchozí pravidla ES5 Vue 2 a ES6 výchozí Vue 3.
Nový kód by měl být napsán pomocí Vue 3 (a následně pomocí ES6). Pravidla ES5+Vue2 jsou určena pouze pro starší kód.
Pojmenovávání
Tato sekce je v současné době pracovní verzí. Materiál ještě nemusí být úplný, informace mohou být v současné době vynechány a určité části obsahu mohou být podrobeny radikálním a rychlým změnám. Na diskusní stránce k tomu možná jsou dostupné bližší informace. |
Jednosouborové komponenty
Kdykoli je to možné, měl by být použit formát jednosouborové komponenty (.vue
) společnosti Vue.
To umožňuje, aby šablony, logika a (volitelně) styly pro danou komponentu žily společně v jednom souboru.
ResourceLoader supports on-the-fly compilation of .vue
files (see Vue.js#Using Vue in MediaWiki for more info about using Vue with ResourceLoader).
To vývojářům umožňuje psát soubory na .vue
, aniž by se museli spoléhat na jakékoli nové nástroje pro vytváření (souhrn, Webpack atd.), a přitom stále těžit z různých optimalizací, které ResourceLoader poskytuje pro front-end kód (stylování RTL pomocí CSS Janus, miniifikace JS atd. ).
Kde je to možné, kód Vue by se měl řídit stylem průvodce komunity Vue. Zejména by měla být vždy dodržována všechna doporučení v "především A: Essentiala". Jakékoli výjimky specifické pro MediaWiki budou uvedeny níže. Pokud je ESLint nastaven správně, bude vynucovat všechna pravidla z průvodce stylem Vue (priorita A, B a C) a také pravidla a výjimky specifická pro MediaWiki.
Obecná struktura
Single-file components are broken into three sections: <template>
, <script>
, and <style>
; components should follow this order, with the <style>
block being optional.
Each component file should be listed individually under the packageFiles
property in the appropriate module definition in extension.json
.
Make sure that the module definition also includes the vue
module as a dependency.
Template
- Component tags must not be self-closing - this is a departure from Vue's style guide recommendations based on current limitations in ResourceLoader. Regardless of whether a component uses slots, it should have a closing tag.
Correct: | Wrong (self-closing components): |
---|---|
<slot-based-component>
<h1>Hello world</h1>
</slot-based-component>
<props-component
:foo="bar"
:baz="quux"
@click="doSomething"
></props-component>
<basic-component></basic-component>
|
<props-component
:foo="bar"
:baz="quux"
@click="doSomething"
/>
<basic-component />
|
- Component tags must use kebab-case, as opposed to PascalCase. This is also a departure from Vue's style guide recommendations due to limitations in ResourceLoader.
Correct (kebab-case): | Wrong (PascalCase): |
---|---|
<some-component :foo="bar"></some-component>
|
<SomeComponent :foo="bar"></SomeComponent>
|
- Use the directive short-hands (
:foo
instead ofv-bind:foo
,@click
instead ofv-on:click
). - Elements with multiple attributes should break them out onto separate lines
- Component templates should only include simple expressions; for anything more complex, define a computed property or method in the
<script>
section instead. - Message strings in templates must be internationalized just like in standard JS or PHP UI development. See the documentation on internationalization in Vue for more information.
- Use
v-html
sparingly and carefully, because it can lead to XSS vulnerabilities if used incorrectly. If you must usev-html
, carefully audit the code that generates the HTML to ensure that all untrusted input is escaped.- For parsed i18n messages (
mw.message( 'foo' ).parse()
), usingv-html
is not necessary in most cases. Usev-i18n-html
instead, if possible. - Because
v-html
is discouraged, using it causes an ESLint error. If you must use it, add<!-- eslint-disable-next-line vue/no-v-html -->
on the line above the tag that usesv-html
to dismiss the ESLint warning. - Before adding this override, double-check your code to ensure your usage of
v-html
is safe.
- For parsed i18n messages (
Script
- Single-file components delivered via ResourceLoader should follow the CommonJS module format and should use ResourceLoader's PackageFiles feature. This means that each component file should include a
module.exports
statement, and should import other code usingrequire():
const { defineComponent } = require( 'vue' ); const OtherComponent = require( './OtherComponent.js' ); module.exports = exports = defineComponent( { name: 'MyComponent', components: { OtherComponent } // … etc. } );
- Component options should be specified in the order defined here: https://github.com/wikimedia/eslint-config-wikimedia/blob/master/vue-common.json. Generally this means:
name
,components
,mixins
,props
,emits
,setup
,data
,computed
properties,methods
, watchers, lifecycle hooks, and finally render functions (in the rare situations where those need to be defined manually). - Render functions should be avoided outside of special cases; HTML-style templates are preferred instead. The
vue
module provided in MediaWiki core is the full version, which includes the template compiler. - Use prop definitions and consider specifying defaults or validating data where necessary. Boolean props should default to false.
- Avoid implicit parent-child communication and the mutation of received props within a child component. Prefer the "props down / events up" approach
Options API vs. Composition API
Vue provides two APIs for writing components: the Options API and the Composition API. Either is allowed; consult the Vue documentation on choosing a component API. Note that Codex component demos are mostly built with the Composition API, so using it may make copying code samples easier. Additionally, Codex exports several composables that may be useful in feature code that uses the Composition API.
Style
- MediaWiki CSS and LESS conventions apply, styles are linted with custom Wikimedia stylelint config
- Since each component should contain a single top-level component, styles should be nested under a single selector (if using LESS)
- Conditional CSS classes should be used for dynamic styles. Object syntax is preferred for computed properties that are bound to class attributes.
- Vue transition names should follow the same pattern as CSS class names (e.g. including an extension-specific prefix)
Progressive Enhancement
TBD: define a no-JS fallback for most features you build this way.