Extension:CodeMirror/zh

This documentation refers to CodeMirror 6 – the new version of CodeMirror. It is slated to replace CodeMirror 5 by MediaWiki version 1.44 (release timeline ). See the migration guide on migrating clients to CodeMirror 6, and Extension:CodeMirror/5 for CodeMirror 5 documentation.

CodeMirror currently does not support syntax highlighting of Scribunto, JavaScript, CSS and JSON pages, but will in the future (T373711). In the meantime, use Extension:代码编辑器 instead.

MediaWiki扩展手册

CodeMirror 发行状态： 稳定版
实现	用户界面
描述	Provides syntax highlighting in editors
作者	Pavel Astakhov MusikAnimal Bhsd
维护者	Community Tech
最新版本	6.0.0
兼容性政策	快照跟随MediaWiki发布。 master分支不向后兼容。
PHP	7.4+
许可协议	GNU通用公眾授權條款2.0或更新版本
下載	下載扩展 Git [?]: 下载Git master 浏览存储库 (Phabricator · GitHub) 提交历史 存储库貢獻者 (GitHub) 代码复核 README
参数 $wgCodeMirrorOpenLinksNamespaces $wgCodeMirrorV6 $wgCodeMirrorAutocompleteNamespaces $wgCodeMirrorTitleCompletion $wgCodeMirrorConflictingGadgets $wgCodeMirrorCodeFoldingNamespaces $wgCodeMirrorDefaultPreferences $wgCodeMirrorLineNumberingNamespaces
使用的函数钩 EditPage::showEditForm:initial EditPage::showReadOnlyForm:initial GetBetaFeaturePreferences GetPreferences ResourceLoaderGetConfigVars UploadForm:initial
季度下載量	267 (Ranked 16th)
正在使用的公开wiki数	6,549 (Ranked 62nd)
前往translatewiki.net翻譯CodeMirror扩展
問題	开启的任务 · 报告错误

The CodeMirror extension provides syntax highlighting in MediaWiki wikitext editors using the CodeMirror library. For usage and a list of features, see Help:Extension:CodeMirror .

In 2024, the extension was upgraded to the new major version, CodeMirror 6, and with it many new features were added. See the differences from CodeMirror 5 for a detailed list of the changes.

Usage

For usage of this extension, see Help:Extension:CodeMirror .

For the JavaScript documentation, see docs.wikimedia.org/CodeMirror.

Installation

• 下载文件，并将解压后的CodeMirror文件夹移动到extensions/目录中。
  开发者和代码贡献人员应从Git安装扩展，输入：cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/CodeMirror
• 将下列代码放置在您的LocalSettings.php 的底部：

  wfLoadExtension( 'CodeMirror' );
  

• Configure as required.
•  完成 – 在您的wiki上导航至Special:Version，以验证已成功安装扩展。

Configuration

For customization of colors and CodeMirror's various features, see Help:Extension:CodeMirror .

$wgCodeMirrorLineNumberingNamespaces

Restrict line numbering to specific namespaces. Defaults to null, which enables it for all namespaces. Set to [] to disable everywhere.

$wgCodeMirrorCodeFoldingNamespaces

Restrict code folding to specific namespaces. Defaults to null, which enables it for all namespaces. Set to [] to disable everywhere.

$wgCodeMirrorAutocompleteNamespaces

Restrict autocompletion to specific namespaces. Defaults to null, which enables it for all namespaces. Set to [] to disable everywhere.

$wgCodeMirrorOpenLinksNamespaces

Restrict opening of links with modifier + click to specific namespaces. Defaults to null, which enables it for all namespaces. Set to [] to disable everywhere.

$wgCodeMirrorV6

Temporary feature flag to control the migration to CodeMirror 6 (T259059).

$wgCodeMirrorConflictingGadgets

An array of gadget names that, if enabled, will prevent CodeMirror from loading. Defaults to wikEd.

$wgDefaultUserOptions['usecodemirror']

When using CodeMirror version 6, set to 1 to enable by default, set to 0 to only enable if the user selects it in their preferences

$wgCodeMirrorDefaultPreferences

Control which features are enabled by default for all users. Note that some features are not available in the 2017 wikitext編輯器 . See the table below for more information.

$wgCodeMirrorDefaultPreferences

Feature	2017 editor compatibility	Default value
activeLine	N	false
bidiIsolation	N	false
bracketMatching		true
lineNumbering		true
lineWrapping		true
specialChars	N	true
codeFolding	N	true
autocomplete	N	true
openLinks	N	true

Differences from CodeMirror 5

Change log

New features

• No longer requires the use of WikiEditor .
• Significant performance improvements.
• Right-to-left support (T170001) with bidi isolation (T358804).
• Code folding (T30684).
• Autocompletion (T95100).
• Quickly open links with modifier key + click (T303392).
• Improved search panel (T371436).
• CodeMirror preferences (T359498).
• Syntax highlighting on read-only pages (T301615).
• Syntax highlighting of definition lists (T170042).
• Bracket matching for CJK full-width brackets (T362992).
• Ctrl+⇧ Shift+X (or ⌘ Cmd+⇧ Shift+X on Mac) changes the directionality of the text (T170001).

Bug fixes

• Highlighting table captions with attributes (T324374).
• Highlighting indented tables (T108454).
• No longer incorrectly highlights protocol-like words (T309880).
• Improved treatment of lists at the start of a line (T184272).
• Added support for jQuery.textSelection's "encapsulate" method (T211205).
• Syncing text editor font preference in editors other than the 2017 editor (T245568).
• No longer loads the CodeMirror 资源加载器 module unnecessarily on pages where it isn't used (T359206).
• Link titles can be both emboldened and italicized.
• Closing HTML tags that highlighted as an error also highlight the closing bracket.

Deprecations and other changes

• The ResourceLoader modules are changing. See the migration guide .
• The .cm-mw-mnemonic CSS class has been renamed to .cm-mw-html-entity.
• The .cm-mw-template-name-mnemonic class has been removed. Use .cm-mw-template-ground.cm-html-entity instead.
• The .cm-mw-apostrophes-bold and .cm-mw-apostrophes-italic CSS classes have been removed. Use .cm-mw-apostrophes instead.
• Line-level styling for <nowiki>, <pre>, or any tag without an associated TagMode has been removed (T351686).
• Mixed languages within wikitext are not yet supported (T357480). The only known usage of this with CodeMirror 5 is 扩展:Php标签 .
• The browser's native search functionality (using Ctrl+F) has been replaced with search functionality built into CodeMirror. This is necessary to maintain performance (T303664).

Migration guide

MediaWiki版本：

≥ 1.43

This guide applies to MediaWiki 1.43 and later. All integrations should aim to be migrated by the release of MediaWiki 1.44 (release timeline ).

ResourceLoader modules

Ensure you're using the new .v6 modules . Because CodeMirror 6 no longer relies on WikiEditor, there are some naming and behaviourial changes from the CodeMirror 5 counterparts:

Old module	New module (MW 1.43)	New module (MW 1.44+)	Description
ext.CodeMirror	ext.CodeMirror.v6.WikiEditor.init	ext.CodeMirror.init	CodeMirror integration for WikiEditor on #wpTextbox1 (the normal editing textarea) and only for wikitext.
N/A	ext.CodeMirror.v6.WikiEditor	ext.CodeMirror.WikiEditor	Exports the CodeMirrorWikiEditor class
N/A	ext.CodeMirror.v6.init	ext.CodeMirror.init	CodeMirror for #wpTextbox1 and only for wikitext.
ext.CodeMirror.lib	ext.CodeMirror.v6.lib	ext.CodeMirror.lib	Exports CodeMirror internals.
ext.CodeMirror.addons	N/A	N/A	This packaged the bracket matching feature in CodeMirror 5. Bracket matching is default behaviour in CodeMirror 6.
ext.CodeMirror.mode.mediawiki	ext.CodeMirror.v6.mode.mediawiki	ext.CodeMirror.mode.mediawiki	The MediaWiki language mode.
N/A	ext.CodeMirror.v6	ext.CodeMirror	Exports the CodeMirror class.
ext.CodeMirror.visualEditor	ext.CodeMirror.visualEditor.init	ext.CodeMirror.init	Integration with the 2017 wikitext編輯器 .
ext.CodeMirror.lib.mode.php	N/A	N/A	CodeMirror 6 will not provide these modules. They are rarely used and have no corresponding content model in MediaWiki. If you want support for these languages, you'll need to install the packages and bundle the code yourself.
ext.CodeMirror.lib.mode.clike
ext.CodeMirror.lib.mode.htmlmixed
ext.CodeMirror.lib.mode.xml
ext.CodeMirror.lib.mode.javascript	TBD	ext.CodeMirror.lib.mode.javascript	These languages are planned to be supported in CodeMirror 6.
ext.CodeMirror.lib.mode.css		ext.CodeMirror.lib.mode.css
N/A		ext.CodeMirror.lib.mode.lua
N/A		ext.CodeMirror.lib.mode.json
N/A		ext.CodeMirror.lib.mode.vue

With the release of MediaWiki 1.44, the old modules will be replaced with the news ones, and for some time the .v6 modules will be aliased before being removed entirely.

Gadgets and user scripts

The CodeMirror global has been removed entirely. For example, CodeMirror.fromTextArea( myTextarea ) will no longer work. Instead, first load the desired ResourceLoader modules , instantiate a CodeMirror object, and call the initialize() method.

CSS

The .CodeMirror element no longer exists. Use .cm-editor instead for the entire CodeMirror DOM, or .cm-content for the inner content (doesn't include the search panel, for example).

See deprecations and other changes to other CSS classes.

Integration

MediaWiki Extensions

Registering a new tag for MediaWiki

If you simply want CodeMirror to recognize a tag that is added by an extension, you can do so using the CodeMirrorTagModes extension attribute . For example, to register the tag ‎<foo> as something containing wikitext, you would add the following to extension.json:

{
	"attributes": {
		"CodeMirror": {
			"TagModes": [
				"foo": "mediawiki"
			]
		}
	}
}

CodeMirror will then highlight the content inside ‎<foo>...‎</foo> as wikitext.

Registering a tag so that CodeMirror treats the contents as something other than wikitext is currently not supported (T357480). If a tag is not registered, CodeMirror will highlight the contents as non-wikitext in the same way it highlights the contents of a ‎<nowiki>...‎</nowiki> tag.

Registering content models

CodeMirror's integration with WikiEditor currently works only with wikitext, but will eventually support other content types.

For the time being, if you need wikitext syntax highlighting on the main textarea (#wpTextbox1) for a content model other than wikitext, you can use the CodeMirrorContentModels extension attribute . For example, Extension:Proofread Page registers the proofread-page content type:

{
	"attributes": {
		"CodeMirror": {
			"ContentModels": [
				"proofread-page"
			]
		}
	}
}

PluginModules

CodeMirrorPluginModules is an extension attribute that allows side-loading a module with CodeMirror. This unconditionally loads the module whenever the ext.CodeMirror.v6 module is loaded. If your plugin is only used in specific circumstances, consider having it check whether it is needed, and dynamically load the core code from a different module. This will avoid unnecessarily consuming end user bandwidth.

extension.json:

{
	"attributes": {
		"CodeMirror": {
			"PluginModules": [
				"ext.MyExtension.CodeMirror"
			]
		}
	}
}

ext.MyExtension.CodeMirror.js:

// Only load in the template namespace
if ( mw.config.get( 'wgNamespaceNumber' ) === 10 ) {
	return mw.loader.using( 'ext.MyExtension.CodeMirror.core' );
}
return Promise.resolve();

JavaScript

Using jQuery.textSelection

If you simply want to fetch or make changes to the contents of a textarea, jQuery.textSelection is the easiest means to do so. Usage of jQuery.textSelection on the textarea is bubbled up to CodeMirror, so you don't need to have any knowledge of whether CodeMirror is enabled:

const $textarea = $( '#wpTextbox1' )
const content = $textarea.textSelection( 'getContents' );
// Append "Foobar" to the content.
$textarea.textSelection( 'setContents', content + '\nFoobar' );

Using ResourceLoader

The CodeMirror extension provides a number of 资源加载器 modules for use by user scripts, gadgets, and extensions. To make use of CodeMirror, you'll need at minimum the ext.CodeMirror.v6 module, along with the desired language. For MediaWiki wikitext, you'd use ext.CodeMirror.v6.mode.mediawiki.

Here is an example of how to apply wikitext syntax highlighting to any arbitrary textarea, using the default set of features:

mw.loader.using( [ 'ext.CodeMirror.v6', 'ext.CodeMirror.v6.mode.mediawiki' ] ).then( ( require ) => {
	const CodeMirror = require( 'ext.CodeMirror.v6' );
	const mediawikiLang = require( 'ext.CodeMirror.v6.mode.mediawiki' );
	const cm = new CodeMirror( $( 'textarea' ) );
	cm.initialize( [ cm.defaultExtensions, mediawikiLang() ] );
} );

If you also want WikiEditor:

mw.loader.using( [
	'ext.wikiEditor',
	'ext.CodeMirror.v6.WikiEditor',
	'ext.CodeMirror.v6.mode.mediawiki'
] ).then( ( require ) => {
	mw.addWikiEditor( $( 'textarea' ) );
    const CodeMirrorWikiEditor = require( 'ext.CodeMirror.v6.WikiEditor' );
	const mediawikiLang = require( 'ext.CodeMirror.v6.mode.mediawiki' );
	const cmWe = new CodeMirrorWikiEditor( $( 'textarea' ) );
	cmWe.initialize( [ cmWe.defaultExtensions, mediawikiLang() ] );
	cmWe.addCodeMirrorToWikiEditor();
} );

ResourceLoader modules

Module	Description
ext.CodeMirror.v6.lib	The core CodeMirror library. You shouldn't need to require this directly unless you need access to the upstream CodeMirror API.
ext.CodeMirror.v6	The basic CodeMirror integration for MediaWiki editors. This module exports the CodeMirror class.
ext.CodeMirror.v6.mode.mediawiki	The MediaWiki language mode. Use this in conjunction with the ext.CodeMirror.v6 module.
ext.CodeMirror.v6.init （內部）	action=edit 请求的主要入口点。不用于外部用途。
ext.CodeMirror.v6.WikiEditor	CodeMirror integration for WikiEditor. This module exports the CodeMirrorWikiEditor class.
ext.CodeMirror.visualEditor.init	CodeMirror integration with the 2017 wikitext編輯器 , and only for wikitext.

Using hooks

You can also integrate with CodeMirror by using frontend hooks. These allow you to run code just before or after CodeMirror has loaded, or react to changes to the document.

Frontend hooks

Hook	Description
ext.CodeMirror.initialize	Called just before CodeMirror is initialized. This can be used to manipulate the DOM to suit CodeMirror (i.e. if you manipulate WikiEditor's DOM, you may need this). Parameters (jQuery) The current "editor", most likely #wpTextbox1.
ext.CodeMirror.ready	Called just after CodeMirror is initialized. Parameters (jQuery) The CodeMirror .cm-editor element. (CodeMirror) The CodeMirror instance.
ext.CodeMirror.destroy	Called just after CodeMirror is destroyed and the original textarea is restored. Parameters (jQuery) The original textarea.
ext.CodeMirror.switch	Called after CodeMirror has been enabled or disabled in WikiEditor. Parameters (boolean) Whether the CodeMirror editor is now shown. (jQuery) The current "editor", either the normal #wpTextbox1 or the .cm-editor element.
ext.CodeMirror.input	Called when document changes are made in CodeMirror. Note that the textarea may not be updated yet. Parameters (ViewUpdate) The ViewUpdate object.
ext.CodeMirror.preferences.ready	Fired just before CodeMirrorPreferences has been instantiated. Paramaters (CodeMirrorPreferences) The CodeMirrorPreferences instance.
ext.CodeMirror.preferences.change	Fired when a CodeMirror preference is changed. Paramaters (string) The name of the preference, which is also the corresponding key in the extensionRegistry and compartmentRegistry. (boolean) The new value of the preference.
ext.CodeMirror.preferences.display (internal)	Fired when the preferences panel is constructed, just before it is displayed. Parameters (HTMLDivElement) The preferences panel container.

Extending CodeMirror

You can import the ext.CodeMirror.v6.lib module to get access to the upstream CodeMirror API. With this you can provide your own Extension when instantiating a CodeMirror or CodeMirrorWikiEditor instance.

For example, to provide your own Extension that reacts to changes made in CodeMirror:

mw.loader.using( [ 'ext.CodeMirror.v6', 'ext.CodeMirror.v6.mode.mediawiki' ] ).then( ( require ) => {
	const CodeMirror = require( 'ext.CodeMirror.v6' );
	const mediawikiLang = require( 'ext.CodeMirror.v6.mode.mediawiki' );
	// ext.CodeMirror.v6.lib is a dependency of ext.CodeMirror.v6, so it's already loaded at this point.
	const { EditorView } = require( 'ext.CodeMirror.v6.lib' );
	const myExtension = EditorView.updateListener.of( ( /** @type {ViewUpdate} */ update ) => {
		if ( update.docChanged ) {
		    // do something
		    console.log( update.changes );
		}
	} );
	const cm = new CodeMirror( $( 'textarea' ) );
    cm.initialize( [ cm.defaultExtensions, mediawikiLang(), myExtension ] );
} );

Another means of listening to changes is using the ext.CodeMirror.input hook :

mw.hook( 'ext.CodeMirror.input' ).add( ( update ) => {
	// Print the ChangeSet to the console
	console.log( update.changes.toJSON() );
} );

Registering an extension in CodeMirror preferences

If you want users to be able to toggle on and off an extension that you provide, you must register it with CodeMirrorPreferences. To guard against race conditions, use the ext.CodeMirror.ready hook:

mw.hook( 'ext.CodeMirror.ready' ).add( ( $textarea, cm ) => {
	cm.preferences.registerExtension( 'myExtension'. myExtension, cm.view );
} );

See also

• User:Remember the dot/Syntax highlighter
• Extension:VisualEditor
• Extension:WikiEditor
• Extension:代码编辑器
• c:Category:MediaWiki extension CodeMirror