Jump to content

Codex

问题追踪器： #codex
From mediawiki.org
This page is a translated version of the page Codex and the translation is 57% complete.
Languages:
维基媒体基金会的项目
Codex
维基媒体设计系统，具有用于创建用户界面的指南和一组工具（设计标签、组件和图标）
群組： Codex Steering Committee
成员： Derek Torsani, Roan Kattouw, Jan Drewniak
积压工作： #codex
更新： CHANGELOG.md

Codex是维基媒体基金会的设计体系。 它提供一个统一的工具集、指引和组件来帮助开发者和设计师在任意Wikimedia项目构建一致、可访问、本地化 的用户界面

Codex使贡献者能够使用基于Vue.js 和纯CSS 构建的标准化用户界面组件——例如按钮、菜单、对话框和图标——这些组件专为可用性、可访问性和兼容性而设计。 它确保我们的产品具有一致的视觉效果和交互行为，使其符合维基媒体基金会的视觉风格和功能标准。 它能够帮助开发者和设计师共同创建用户友好且易于维护的界面。

Codex是推荐的UI设计系统，并且自从MediaWiki 1.39 与MediaWiki一起打包。 它也作为一套NPM包发行。 该系统是由Wikimedia Foundation 、Wikimedia德国、和志愿贡献者共同开发

Codex的源码托管在Gerrit上，可在Phabricator追踪其开发进程。 你可以查看全更新日志并加入我们的贡献者Telegram群组来参与其中。

基本用法

Codex提供了多种“组件”，皮肤、扩展和用户脚本的作者可以将这些组件嵌入到他们自己的用户界面中：按钮、复选框、切换开关、对话框等。 这些组件许多都能被扩展性定制。

 阅览完整的Codex组件列表（连同文档和交互式演示）

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

For improved page load performance, limit loading to a subset of Codex components for skins and extensions . See #Using a limited subset of components

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">點擊這裡！</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.

不使用JavaScript（仅限CSS的Codex组件）的用法

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">
		默认按钮
	</button>
</div>
<div>
	<button class="cdx-button cdx-button--action-progressive">
		积极操作按钮
	</button>
</div>
<div>
	<button class="cdx-button cdx-button--action-destructive">
		破坏性操作按钮
	</button>
</div>

Using Codex in PHP

Codex PHP is still under development and is not yet recommended for wide-spread use in MediaWiki core (T399523). Breaking changes may be introduced until a stable version is released.

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( "折叠面板实例" )
			->setDescription( "这是一个折叠面板的例子。" )
			->setContentHtml(
				$codex
					->htmlSnippet()
					->setContent( "<p>这是折叠面板的内容。</p>" )
					->build()
			)
			->setOpen( false )
			->setAttributes( [
				"class" => "foo",
				"bar" => "baz",
			] )
			->build()
			->getHtml();

echo $accordion;

Advanced usage

Using a limited subset of components

Prioritize page load performance by using ResourceLoader to load only the necessary Codex components whenever possible.

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.
—ResourceLoader

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. 接下来你可以导入你从那个虚拟文件请求的组件和可组合物件。 

// 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.

使用Codex图标

出于性能原因，没有一个名为codex-icons的包含所有Codex图标的ResourceLoader 模块 这样的模块会非常大且浪费，因为大多数Codex用户只需要200多个图标中的一小撮。 相反，ResourceLoader提供了一个嵌入模块自己想要的图标的方法，就像上面描述的代码分块方法那样。 

{
    "name": "icons.json",
    "callback": "MediaWiki\\ResourceLoader\\CodexModule::getIcons",
    "callbackParam": [
        // 在此列出你的模块所需的图标，比如：
        "cdxIconArrowNext",
        "cdxIconBold",
        "cdxIconTrash"
    ]
}

参阅：

直接使用设计标签

设计令牌可以导入到Less 样式表作为变量。 如果你想要开发你自己的组件或者样式，并且想让他们与Codex集成，这会很有用。

Codex设计令牌应当导入自文件mediawiki.skin.variables.less。 

@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

Some Codex functionality is implemented using LESS mixins. For example, the Link component is a LESS mixin rather than a Vue component, and using icons in CSS-only components requires using a LESS mixin (see also the documentation for using CSS-only components).

Using Codex LESS mixins in MediaWiki and extensions works very similarly to using design tokens: simply import mediawiki.skin.variables.less, which makes all Codex mixins available, as well as the design tokens. 

@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 .vue single-file component support; you must define components in plain .js files
  • 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 ) {
	//... require Vue and Codex as above
	// create an element to mount the Vue app
	const mountPoint = document.body.appendChild( document.createElement( 'div' ) );
	// create a Vue app and mount it to the target element
	Vue.createMwApp( {
		// data, computed props, methods, etc. go here
	} ).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.

https://en.wikipedia.org/wiki/User:EGardner_(WMF)/codex-hello-world.js

Here is another script using Codex :

https://en.wikipedia.org/wiki/User:JSherman_(WMF)/revertrisk.js

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:

  1. Clone the Codex repository (if you haven't already), and check out the change you want to test.
  2. Run npm install and npm run build-all in the root directory of the Codex repository.
  3. Point $wgCodexDevelopmentDir to 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'; to LocalSettings.php
  4. 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.

注释

  1. ↑ phab:T183720#9447986
Retrieved from "https://www.mediawiki.org/w/index.php?title=Codex/zh&oldid=8075742"