Manual:Coding conventions/Vue/nl

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.

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 of v-bind:foo, @click instead of v-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 use v-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()), using v-html is not necessary in most cases. Use v-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 uses v-html to dismiss the ESLint warning.
  • Before adding this override, double-check your code to ensure your usage of v-html is safe.

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 using require():

  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.