Manual:Coding conventions/Vue/nl
Please do not mark this page for translation yet. Deze pagina a.u.b. niet markeren voor vertaling! Het is nog een concept, er wordt nog aangewerkt. De pagina moet klaar zijn voordat het vertalen zinvol is. |
Deze pagina is op het moment een concept.
|
Deze pagina beschrijft een MediaWiki richtlijn voor de ontwikkeling, die akkoord is verklaard na onderling overleg tussen de ontwikkelaars (met soms wat akkoordverklaringen door de leider van een ontwikkelteam) |
Deze pagina beschrijft de coderingsconventies voor Vue in de MediaWiki codebase. Zie ook de JavaScript en CSS/LESS conventies die van toepassing zijn op dergelijke code binnen Vue-bestanden.
Linting (Rollend)
We gebruiken ESLint als ons hulpmiddel voor codekwaliteit.
De custom config voor Wikimedia (eslint-config-wikimedia
) bevat zowel algemene als MediaWiki-specifieke regels voor Vue-code.
Het maken van ESLint om de definities van componenten te herkennen
U moet de functie defineComponent()
van Vue voor uw componentendefinitie gebruiken om als zodanig door ESLint te worden herkent (zie voorbeeld hieronder).
Als ESLint ziet dat dit niet gedaan is, waarschuwt het u en zegt het u het toe te voegen, maar het zal uw code niet kunnen interpreteren als Vue-code totdat u dat doet.
<script>
const { defineComponent } = require( 'vue' );
const AnotherComponent = require( './AnotherComponent.vue' );
module.exports = exports = defineComponent( {
name: 'MyComponent',
components: { AnotherComponent },
...
} );
</script>
Het opzetten van ESLint
Als u al de wikimedia/client
of wikimedia/client/es6
vooraf instellingen van het eslint-config-wikimedia package in uw .eslintrc.json
gebruikt, worden lint regels voor Vue automatisch toegepast op .vue
bestanden.
Vanaf versie 0.23.0 van eslint-config-wikimedia, de standaardregels van ES5 zijn Vue 2, en de standaardregels van ES6 zijn Vue 3.
Nieuwe code moet worden geschreven met Vue 3 (en dus met gebruik van ES6); de ES5+Vue2 regels zijn alleen bedoeld voor legacy code.
Naamgeving
Deze sectie is op het moment een concept. Het materiaal kan nog onvolledig zijn, er kan informatie ontbreken en delen van de inhoud kunnen nog snel en ook ingrijpend wijzigen. Meer informatie kan beschikbaar zijn op de overlegpagina. |
Componenten met één bestand
Vue's component met een bestand formaat (.vue
) moet waar mogelijk worden gebruikt.
Dit stelt sjablonen, logica en (optioneel) stijlen voor een bepaald onderdeel in staat om samen in één bestand te kunnen zijn.
ResourceLoader ondersteunt on-the-fly compilatie van .vue
bestanden (zie Vue.js#Using Vue in MediaWiki voor meer info over het gebruik van Vue met ResourceLoader).
Dit stelt ontwikkelaars in staat om .vue
-bestanden te schrijven zonder afhankelijk te zijn van nieuwe build-hulpmiddelen (Rollup, Webpack, enz.), terwijl ze nog steeds profiteren van de verschillende optimalisaties die ResourceLoader biedt voor front-endcode (RTL-styling via CSS Janus, JS-minificatie, enz.).
Waar mogelijk moet de Vue-code de Vue-gemeenschaps stijlgids volgen. In het bijzonder moeten alle aanbevelingen in "Priority A: Essential" te allen tijde worden gevolgd. Alle uitzonderingen voor MediaWiki worden hieronder genoemd. Als ESLint correct is ingesteld, zal het alle regels uit de Vue-stijlgids (prioriteit A, B en C) afdwingen, evenals MediaWiki-specifieke regels en uitzonderingen.
Algemene structuur
Componenten met één bestand zijn onderverdeeld in drie secties: <template>
, <script>
en <style>
; Componenten moeten deze volgorde volgen, waarbij het blok van <style>
optioneel is.
Elk componentbestand moet afzonderlijk worden vermeld onder de eigenschap packageFiles
in de juiste moduledefinitie in extension.json
.
Zorg ervoor dat de moduledefinitie ook de vue
module als afhankelijkheid omvat.
Sjabloon
- Component tags mogen niet zelfsluitend zijn - Dit is een afwijking op de Vue's stijlgids aanbevelingen op basis van de huidige beperkingen in ResourceLoader. Ongeacht of een onderdeel slots gebruikt, moet het een sluit-tag hebben.
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.