Codex/pt-br
 | Veja a documentação oficial para obter mais detalhes sobre o Codex, incluindo como usá-lo fora do MediaWiki. |
|
Codex
 Sistema de design para a Wikimedia com diretrizes e um conjunto de ferramentas (tokens de design, componentes e, ícones) para a criação de interfaces de usuário
|
Codex é o sistema de design da Wikimedia. It provides a unified set of tools, guidelines, and components to help developers and designers build consistent, accessible, and localized user-interfaces across Wikimedia projects.
Codex enables contributors to use standardized UI components built with Vue.js and plain CSS—such as buttons, menus, dialogs, and icons—that are designed for usability, accessibility, and compatibility. It ensures a consistent look and behavior for our products, so that they align with the visual style and functionality standards of Wikimedia. It supports both developers and designers in creating user-friendly and maintainable interfaces.
Codex is the recommended user-interface design system, and has been bundled with MediaWiki since MediaWiki 1.39. It is also available as a set of npm packages. The system is collaboratively developed by the Wikimedia Foundation, Wikimedia Deutschland, and volunteer contributors.
O código-fonte do Codex está hospedado no gerrit, e seu desenvolvimento é rastreado no phabricator. Junte-se no grupo de conversa do telegram.
Uso básico
O Codex fornece uma variedade de componentes de visual, extensão, o userscript pode incorporar em suas próprias interfaces de usuário: botões, caixas de seleção, interruptores, diálogos, etc. Many of these components can be extensively customized.
CodexExample MediaWiki extension
The Codex Steering Committee maintains the CodexExample MediaWiki extension that demonstrates how to use design tokens, components, and icons from Codex.
This extension can be installed (it sets up a dedicated special page called Special:CodexExample with live demos), or you can study its source code for inspiration.
See the project README.md page for more information on installation and use.
Usage with JavaScript
Codex components are built using the Vue.js JavaScript framework.
If you are developing a Vue application in MediaWiki, then it's easy to load Codex components from ResourceLoader using require().
You can load all of Codex at once, or just a limited subset of components.
Loading the entire library (recommended for use in userscripts)
"ext.myExtension.foo": {
"dependencies": [ "@wikimedia/codex" ]
"packageFiles": [
"init.js",
"MyComponent.vue"
]
}
<!-- MyComponent.vue -->
<template>
<cdx-button @click="doSomething">Click me!</cdx-button>
</template>
<script>
const { CdxButton } = require( '@wikimedia/codex' );
module.exports = exports = {
name: "MyComponent",
components: {
CdxButton
},
methods: {
doSomething() {
//...
}
}
}
</script>
Loading a subset of Codex components (recommended for skins and extensions)
To only load a limited set of components, you can declare your dependencies in the following way below:
"ext.myExtension.foo": {
"class": "MediaWiki\\ResourceLoader\\CodexModule",
"packageFiles": [
"init.js",
"MyComponent.vue"
],
"codexComponents": [
"CdxButton",
"CdxCard",
"CdxDialog"
]
}
This will generate a virtual file, codex.js, in your resources directory with the exports you need.
You can then require the components you requested from that virtual file:
// In resources/ext.myExtension.foo/MyComponent.vue
const { CdxButton, CdxTextInput } = require( '../codex.js' );
See the CodexExample repository for more in-depth example of how to use Codex in a MediaWiki extension.
Uso sem JavaScript (componentes Codex somente CSS)
| Versão do MediaWiki: | ≥ 1.42 |
Many Codex components also support "CSS-only" usage. These components should appear visually identical to their JS-enabled counterparts, but they will offer more limited behavior.
Loading component styles
You can load the styles of a limited subset of Codex CSS components in the same way as you would for JS components, above.
If you only need the styles, you can add the "codexStyleOnly": "true" option when you define your module.
"ext.myExtension.foo": {
"class": "MediaWiki\\ResourceLoader\\CodexModule",
"styles": "ext.myExtension.foo/styles.less",
"codexStyleOnly": "true",
"codexComponents": [
"CdxButton",
"CdxCard",
"CdxCheckbox",
"CdxProgressBar"
]
}
Providing component markup
To use CSS-only Codex components, just ensure that the appropriate styles are loaded and then add the necessary markup to your page. For now, you'll have to do this by hand. You can find example markup in the "CSS-only usage" section on a component's documentation page (here is the markup for the Button component).
<div>
<button class="cdx-button cdx-button--action-default">
Default button
</button>
</div>
<div>
<button class="cdx-button cdx-button--action-progressive">
Progressive button
</button>
</div>
<div>
<button class="cdx-button cdx-button--action-destructive">
Destructive button
</button>
</div>
Using Codex in PHP
Codex PHP is a library for building CSS-only UI components using Codex, the Wikimedia design system, please see the Codex PHP documentation.
Installation
Install the Codex PHP library via Composer:
composer require wikimedia/codex
Example usage
Here’s an example of creating an Accordion component in PHP:
$accordion = $codex
->accordion()
->setTitle( "Accordion Example" )
->setDescription( "Este é um exemplo de accordion." )
->setContentHtml(
$codex
->htmlSnippet()
->setContent( "<p>Este é o conteúdo do accordion.</p>" )
->build()
)
->setOpen( false )
->setAttributes( [
"class" => "foo",
"bar" => "baz",
] )
->build()
->getHtml();
echo $accordion;
Advanced usage
Using a limited subset of components
The @wikimedia/codex ResourceLoader module provides the entire Codex library – all components, styles, etc.
If you are developing a skin or an extension and you care about performance, you should consider using Codex's code-splitting feature.
ResourceLoader allows you to specify a list of Codex components and load only the JS/CSS for those components plus their dependencies.
Registering many modules is highly discouraged, even if they are not loaded by default. The addition of each module adds 44 bytes[1] to every initial page load, so about 40 GiB of extra transfer to Wikimedia servers per day.
To use this feature, define a custom ResourceLoader module (this is typically done in skin.json or extension.json) and specify a list of codexComponents:
"ext.myExtension.blockform": {
"class": "MediaWiki\\ResourceLoader\\CodexModule",
"codexComponents": [
"CdxButton",
"CdxCard",
"CdxDialog",
"CdxIcon",
"CdxRadio",
"CdxTextInput",
"useModelWrapper"
],
"packageFiles": [
"init.js",
"BlockForm.vue"
],
"messages": [
"block-target",
"ipb-submit"
]
}
This will generate a virtual file, codex.js, in your resources directory with the exports you need.
Você pode então exigir os componentes e elementos que podem ser compostos solicitados desse arquivo virtual:
// In resources/ext.myExtension/BlockForm.vue
const { CdxButton, CdxTextInput } = require( '../codex.js' );
If you only need CSS-only components and don't wish to load the component JavaScript, you can add "codexStyleOnly": true to the module definition.
Similarly, if you only need the JavaScript files and not styles, you can add "codexScriptOnly": "true".
You should only do this if you're putting the styles in another, style-only module as described above.
Using Codex icons
Por motivos de desempenho, não existe um módulo ResourceLoader de codex-icons
{
"name": "icons.json",
"callback": "MediaWiki\\ResourceLoader\\CodexModule::getIcons",
"callbackParam": [
// Liste os ícones que seu módulo precisa aqui, por exemplo:
"cdxIconArrowNext",
"cdxIconBold",
"cdxIconTrash"
]
}
See also:
Usando tokens de design diretamente
Design tokens can be imported into Less stylesheets as variables. This may be useful if you are developing your own components or styles, and want them to integrate with Codex.
Codex design tokens should be imported from the mediawiki.skin.variables.less file.
@import 'mediawiki.skin.variables.less';
.my-feature {
background-color: @background-color-base;
color: @color-base;
}
For a full list of Codex's design tokens, broken down by category, see Codex documentation#Design tokens.
Codex LESS mixins
Algumas funções do Codex são implementadas usando mixins do Less. Por exemplo, o Componente Link é um mixin do Less em vez de um componente Vue, e o uso de ícones em componentes somente CSS requer o uso do mixin (veja também abaixo a documentação para usando componentes somente CSS).
Usar mixins Less Codex no MediaWiki e extensões funciona de forma muito semelhante a usar tokens de design: basta importar mediawiki.skin.variables.less, o que disponibiliza todos os mixins do Codex, bem como os tokens de design.
@import 'mediawiki.skin.variables.less';
.my-feature {
a {
.cdx-mixin-link-base();
}
}
Using Codex in userscripts
It is possible to use Codex in userscripts. However, there are some limitations that will require certain workarounds. Here are a few considerations to keep in mind when using Vue and Codex in userscripts:
- No
.vuesingle-file component support; you must define components in plain.jsfiles - Everything needs to live in one file; userscripts don't provide a good way to load custom modules
- Define component templates using ES6 template literals
- Prefer global component registration for Codex components
Loading Vue/Codex
You'll need to load Vue and Codex from ResourceLoader.
The best way to do this is via mw.loader.using; the rest of your userscript code should live in a callback or promise chain.
mw.loader.using( '@wikimedia/codex' ).then( function( require ) {
const Vue = require( 'vue' );
const Codex = require( '@wikimedia/codex' );
} );
Use Vue.createMwApp
Once you've loaded Vue and Codex, you must define a Vue app and mount it somewhere on the page.
The exact location will vary depending on what you are trying to do.
You can use MediaWiki's custom createMwApp method for this.
mw.loader.using( '@wikimedia/codex' ).then( function( require ) {
//... requer o Vue e o Codex
// Crie um elemento para montar o aplicativo Vue
const mountPoint = document.body.appendChild( document.createElement( 'div' ) );
// Crie um aplicativo Vue e monte-o com o elemento de destino
Vue.createMwApp( {
// dados, adereços computados, métodos, etc. Vá aqui
} ).mount( mountPoint );
} );
Real examples
The link below shows a complete example of a userscript which adds a portlet link to all Wiki pages that triggers a custom Codex Dialog component to launch when clicked. Feel free to copy this script to your own user page to use as a starting point.
Here is another script using Codex :
Release cycle
A new version of Codex is released every other Tuesday. When a new release is created, a patch is also submitted to MediaWiki core to use that new release. Since this is done on Tuesdays, the update to core will be deployed the following week (the next time the deployment train runs).
Using a custom version of Codex for development or testing
MediaWiki uses the latest release of Codex. If you need to use a different version for development or testing purposes, for example to test how an unmerged patch in Codex interacts with MediaWiki, you can point MediaWiki to your own version of Codex as follows:
- Clone the Codex repository (if you haven't already), and check out the change you want to test.
- Run
npm installandnpm run build-allin the root directory of the Codex repository. - Point
$wgCodexDevelopmentDirto the root directory of the Codex repository. For example, if you cloned the Codex repository in the parent directory of the MediaWiki directory, add$wgCodexDevelopmentDir = MW_INSTALL_PATH . '../codex';toLocalSettings.php - Test that it works by running
mw.loader.load( '@wikimedia/codex' )in the browser console. This should trigger a warning saying "You are using a local development version of Codex", and should not trigger any errors.
Once you have this set up, you can make additional changes to your Codex clone, but you have to run npm run build-all each time to make those changes take effect in MediaWiki.
To disable development mode and go back to using the latest release of Codex, comment out the line in LocalSettings.php that sets $wgCodexDevelopmentDir.