Jump to content

Extension:CodeMirror

課題管理システム: #MediaWiki-extensions-CodeMirror
From mediawiki.org
This page is a translated version of the page Extension:CodeMirror and the translation is 53% complete.
Languages:
CodeEditor とは異なります。
このページでは、最新バージョンである CodeMirror 6 を扱います。 CodeMirror 5 は MediaWiki 1.46 に置き換えられる予定です。 CodeMirror 6 への移行方法については 移行ガイド を参照してください。
MediaWiki 拡張機能マニュアル
CodeMirror
リリースの状態: 安定
実装 ユーザー インターフェイス
説明 エディター上での構文強調表示を提供する
作者
メンテナー Community Tech
最新バージョン 6.0.0
互換性の方針 スナップショットが MediaWiki とともにリリースされます。 master には後方互換性がありません。
PHP 7.4+
パラメーター
  • $wgCodeMirrorV6
  • $wgCodeMirrorPrimaryPreferences
  • $wgCodeMirrorTitleCompletion
  • $wgCodeMirrorConflictingGadgets
  • $wgCodeMirrorEnabledModes
  • $wgCodeMirrorDefaultPreferences
  • $wgCodeMirrorLineNumberingNamespaces
使用するフック
ライセンス GNU 一般公衆利用許諾書 2.0 以降
ダウンロード
拡張機能をダウンロード
Git [?]:

README
ヘルプ Help:Extension:CodeMirror/ja
translatewiki.net で翻訳を利用できる場合は、CodeMirror 拡張機能の翻訳にご協力ください
問題点 未解決のタスク · バグを報告

CodeMirror 拡張機能は、CodeMirror ライブラリを使用して、ウィキテキストを含む様々なプログラミング言語とマークアップ言語の構文の強調表示に対応したスタンドアローンなエディターを提供します。 WikiEditor 、2017年版ウィキテキストエディター 、Proofread Page などの他のエディターでも使用できます。 使い方と機能の一覧については、Help:Extension:CodeMirror をご覧ください。

2024から2025年にかけて、この拡張機能は新しいメジャーバージョンの CodeMirror 6 にアップグレードされ、多くの新機能 が追加されました。

インストール

  • ダウンロードして、ファイルをextensions/フォルダー内のCodeMirrorという名前のディレクトリ内に配置します。
    開発者とコード寄稿者は、上記の代わりに以下を使用してGitからインストールします:
    cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/CodeMirror
  • 以下のコードを LocalSettings.php ファイルの末尾に追加します: 
    wfLoadExtension( 'CodeMirror' );
  • Configure as required.
  • Yes 完了 – ウィキの「Special:Version」に移動して、拡張機能が正しくインストールされたことを確認します。

設定

色のカスタマイズや CodeMirror の様々な機能については、Help:Extension:CodeMirror をご覧ください。

すべての利用者に対して既定で CodeMirror を有効にするには、LocalSettings.php に次のコードを追加します:

LocalSettings.php 
# Enables use of CodeMirror by default but still allow users to disable it
$wgDefaultUserOptions[ 'usecodemirror' ] = true;
$wgCodeMirrorV6
CodeMirror 6 への移行を制御するための一時的な機能フラグ(T259059)。
$wgCodeMirrorEnabledModes
Extension:CodeEditor との競合を制御するための一時的な機能フラグ。 See the Using CodeMirror instead of CodeEditor section below for more information.
$wgCodeMirrorConflictingGadgets
有効にすると CodeMirror が読み込まれなくなるガジェット名の配列。既定値は wikEd です。
$wgCodeMirrorPrimaryPreferences
The preferences to advertse in the in-editor preferences panel. These should have a clear visual effect or be commonly used to warrant easier access to toggling the feature. Preferences not listed here will still be available in the full preferences dialog.
$wgCodeMirrorDefaultPreferences
すべての利用者に対して既定で有効にする機能 を制御します。 true か false を用いて機能自体を有効または無効化するか、名前空間ID(整数)またはコンテンツモデル(文字列)を含む配列を指定します。 例えば、JavaScript ページまたはテンプレートのみに自動補完を限定するには、次のように指定します:
LocalSettings.php 
# Limit CodeMirror autocompletion to JavaScript pages and templates
$wgCodeMirrorDefaultPreferences[ 'autocomplete' ] = [ CONTENT_MODEL_JAVASCRIPT, NS_TEMPLATE ];
$wgCodeMirrorDefaultPreferences
機能 2017年版エディター
との互換性		 既定値
activeLine N false
autocomplete N true
autofocus Yes[1] true
bidiIsolation N false
bracketMatching Yes true
codeFolding N true
closeBrackets N true
highlightRefs Yes true
lineNumbering Yes true
lineWrapping Yes[2] true
lint N ['json','css','javascript','lua','vue']
openLinks N true
specialChars N true
whitespace N false

CodeMirror 5 との違い

新しい機能

廃止およびその他の変更点

  • ResourceLoader モジュールが変更されます。移行ガイド をご覧ください。
  • ext.CodeMirror.switch フックは非推奨となりました。 代わりに ext.CodeMirror.toggle を使用してください。
  • CSS クラス .cm-mw-mnemonic の名前は .cm-mw-html-entity に変更されました。
  • .cm-mw-template-name-mnemonic クラスは除去されました。 代わりに .cm-mw-template-ground.cm-html-entity を使用してください。
  • CSS クラス .cm-mw-apostrophes-bold および .cm-mw-apostrophes-italic は除去されました。 代わりに .cm-mw-apostrophes を使用してください。
  • <nowiki>、<pre>、または関連付けられた TagMode のないタグの行単位のスタイル設定が除去されました(T351686)。
  • ウィキテキスト内の混合言語はまだサポートされていません(T357480)。
  • ブラウザー固有の検索機能(Ctrl+F)は、CodeMirror の検索機能に置き換えられます。 これはパフォーマンスを維持するために必要です(T303664)。

移行ガイド

MediaWiki バージョン:
≧ 1.44

このガイドは MediaWiki 1.45 以降に適用されます。MediaWiki 1.46 のリリースまでにすべての移行完了を目標にしてください(リリースタイムライン )。

MediaWiki の設定

  • $wgCodeMirrorLineNumberingNamespaces は非推奨となりました。代わりに $wgCodeMirrorDefaultPreferences を設定してください。

ResourceLoader モジュール

新しい .v6 モジュール を使用しているか確認してください。 CodeMirror 6 は WikiEditor に依存しなくなったため、CodeMirror 5 の対応するモジュールと比べて、名称と動作が一部変更されています:

一部のモジュール名は簡潔にするために先頭の ext.CodeMirror を省略しています。使用する際は「…」部分を置き換えてください。

旧モジュール 新モジュール (MW 1.44) New module (MW 1.45) 新モジュール(MW 1.46以降) 説明
ext.CodeMirror ….v6.WikiEditor.init ….v6.init ….init #wpTextbox1 (通常の編集テキストエリア) でのウィキエディター用 CodeMirror 統合。
N/A ….v6.WikiEditor ….v6.WikiEditor ….WikiEditor Exports the CodeMirrorWikiEditor class
N/A ….v6.init ….v6.init ….init CodeMirror for #wpTextbox1 and other supported pages.
….lib ….v6.init ….v6.init ….lib Exports CodeMirror internals.
….addons N/A N/A N/A This packaged the bracket matching feature in CodeMirror 5. Bracket matching is default behaviour in CodeMirror 6.
….mode.mediawiki ….v6.mode.mediawiki ….v6.mode.mediawiki ….mode.mediawiki The MediaWiki language mode.
N/A ext.CodeMirror.v6 ext.CodeMirror.v6 ext.CodeMirror Exports the CodeMirror class.
….visualEditor ….visualEditor.init ….visualEditor.init ….init Integration with the 2017年版ウィキテキストエディター .
….lib.mode.php N/A N/A CodeMirror 6 will eventually provide some or all of these modes, but they will not be available as separate modules.
….lib.mode.clike
….lib.mode.htmlmixed
….lib.mode.xml
….lib.mode.javascript ….v6.mode.javascript ….v6.modes ….modes これらの言語は CodeMirror 6 でサポートされています。
….lib.mode.css ….v6.mode.css
N/A ….v6.mode.lua
N/A ….v6.mode.json
N/A ….v6.mode.vue

MediaWiki 1.46 のリリースをもって、旧モジュールは新モジュールに置き換えられ、.v6 モジュールはしばらくの間完全に除去されずにエイリアスとして残ります。

ガジェットと利用者スクリプト

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.

If your script relies on the ext.CodeMirror.switch hook to change the way it interacts with the editor, you'll need to use ext.CodeMirror.toggle instead, or alternatively listen to an event. See the JavaScript integration section for more information.

CSS

.CodeMirror 要素は廃止されました。 CodeMirror の DOM 全体を扱う場合は .cm-editor を、(検索パネルなどを含まない)内部コンテンツを扱う場合は .cm-content を使用してください。

その他の CSS クラスに関しては、廃止およびその他の変更点 を参照してください。

連携

MediaWiki 拡張機能

CodeEditor の代わりに CodeMirror を使用

MediaWiki バージョン:
≧ 1.44

MediaWiki 1.44 以降、CodeMirror はLua、JavaScript、CSS、JSON、Vue 言語の構文強調表示をサポートしています。これは、Extension:CodeEditor の代わりとして使用できます。

ただし、CodeEditor と連携しているすべての拡張機能が CodeMirror をサポートするように更新されているわけではありません。以下の拡張機能を使用している場合は、引き続き CodeEditor をウィキにインストールしておくことをお勧めします。

As of MediaWiki 1.45, for this to work, you'll need to adjust $wgCodeMirrorEnabledModes accordingly, along with the *UseCodeEditor and *UseCodeMirror for any applicable extensions you also have installed:

LocalSettings.php 
// Desired modes that should use CodeMirror (mediawiki, i.e. wikitext, is enabled by default)
$wgCodeMirrorEnabledModes['javascript'] = true;
$wgCodeMirrorEnabledModes['json'] = true;
$wgCodeMirrorEnabledModes['css'] = true;
$wgCodeMirrorEnabledModes['lua'] = true;
$wgCodeMirrorEnabledModes['vue'] = true;

// If you're also using CodeEditor, disable the same modes there:
$wgCodeEditorEnabledModes['javascript'] = false;
$wgCodeEditorEnabledModes['json'] = false;
$wgCodeEditorEnabledModes['css'] = false;
$wgCodeEditorEnabledModes['lua'] = false;
$wgCodeEditorEnabledModes['vue'] = false;

// Gadgets (for editing Gadget definition JSON pages)
$wgGadgetsDefinitionsUseCodeEditor = false;
$wgGadgetsDefinitionsUseCodeMirror = true;

// JsonConfig
$wgJsonConfigUseCodeEditor = false;
$wgJsonConfigUseCodeMirror = true;

// Scribunto (for editing Module pages that use the "lua" mode)
$wgScribuntoUseCodeEditor = false;
$wgScribuntoUseCodeMirror = true;

// TemplateStyles
$wgTemplateStylesUseCodeEditor = false;
$wgTemplateStylesUseCodeMirror = true;

// UploadWizard (for editing Campaign JSON pages)
$wgUploadWizardUseCodeEditor = false;
$wgUploadWizardUseCodeMirror = true;

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.

PHP フック

MediaWiki バージョン:
≧ 1.44

Since MediaWiki 1.44, the preferred means to integrate with CodeMirror in PHP is implementing the CodeMirrorGetModeHook interface: 

class CodeMirrorHooks implements CodeMirrorGetModeHook {
	public function onCodeMirrorGetMode(Title $title, ?string &$mode, string $model ): bool {
		// Logic to determine if CodeMirror should be used
		if ( $title->hasContentModel( 'JsonLikeContentModel' ) ) {
			$mode = 'json';
			return false;
		}

		return true;
	}
}

Register the hook in extension.json: 

"Hooks": {
	"CodeMirrorGetMode": "codemirror"
},
"HookHandlers": {
	"codemirror": {
		"class": "MediaWiki\\Extension\\MyExtension\\CodeMirrorHooks"
	}
}

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.

extension.json: 

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

JavaScript

The CodeMirror editor is not an actual textarea, but a contenteditable. Usually developers need to ensure their code works with both given that CodeMirror can be toggled off.

For detecting changes to the document, using an event or a hook is likely the simplest. For reading and making changes, jQuery.textSelection may be convenient.

For more complex integrations or those who need better performance, you can add your own extension to a new or an existing CodeMirror instance.

jQuery.textSelectionを使用

If you simply want to fetch or make changes to the document text, jQuery.textSelection is the easiest and most reliable 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' );

jQuery's .val() on #wpTextbox1 can be used,[3] but this isn't recommended and may not work in all editors, such as the 2017年版ウィキテキストエディター .

ResourceLoaderの使用

The CodeMirror extension provides a number of ResourceLoader 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 "mode".

Modes can be unpacked from the ResourceLoader modules, using an exported method with the same name as the mode. For MediaWiki wikitext, you'd use ext.CodeMirror.v6.mode.mediawiki, and for JavaScript, JSON, CSS, Vue and Lua, you'd use ext.CodeMirror.v6.modes: 

const require = await mw.loader.using( [ 'ext.CodeMirror.v6', 'ext.CodeMirror.v6.mode.mediawiki' ] );
const CodeMirror = require( 'ext.CodeMirror.v6' );
const { mediawiki } = require( 'ext.CodeMirror.v6.mode.mediawiki' );
const cm = new CodeMirror( myTextarea, mediawiki() );
cm.initialize();

If you also want WikiEditor: 

const require = await mw.loader.using( [
	'ext.wikiEditor',
	'ext.CodeMirror.v6.WikiEditor',
	'ext.CodeMirror.v6.mode.mediawiki'
] );
const textarea = document.getElementById( 'wpTextbox1' );
mw.addWikiEditor( $( textarea ) );
const CodeMirrorWikiEditor = require( 'ext.CodeMirror.v6.WikiEditor' );
const { mediawiki } = require( 'ext.CodeMirror.v6.mode.mediawiki' );
const cmWe = new CodeMirrorWikiEditor( textarea, mediawiki() );
cmWe.mode = 'mediawiki';
cmWe.initialize();

Creating a new JavaScript instance: 

const require = await mw.loader.using( [ 'ext.CodeMirror.v6', 'ext.CodeMirror.v6.modes' ] );
const CodeMirror = require( 'ext.CodeMirror.v6' );
const { javascript } = require( 'ext.CodeMirror.v6.modes' );
const cm = new CodeMirror( myTextarea, javascript() );
cm.initialize();
ResourceLoader modules
モジュール 説明
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.WikiEditor CodeMirror integration for WikiEditor. This module exports the CodeMirrorWikiEditor class.
ext.CodeMirror.v6.mode.mediawiki Exports the mediawiki mode for highlighting MediaWiki wikitext.
ext.CodeMirror.v6.modes Includes the modes javascript, json, css, vue and lua.
ext.CodeMirror.v6.init
(内部) 		The main entrypoint for action=edit requests. Not intended for external use.
ext.CodeMirror.visualEditor.init
(内部) 		CodeMirror integration with the 2017年版ウィキテキストエディター , and only for wikitext.

フックの使用

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.

フロントエンド フック
フック 説明
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).

パラメーター

  • (HTMLTextAreaElement) The current "editor", most likely #wpTextbox1.
  • (ve.ui.Surface) The VisualEditor surface CodeMirror is bound to, if applicable.
ext.CodeMirror.ready Called just after CodeMirror is initialized.

パラメータ

ext.CodeMirror.toggle Called when CodeMirror is toggled on or off.

パラメーター

  • (boolean) Whether CodeMirror is now enabled.
  • (CodeMirror) CodeMirror インスタンス。
  • (HTMLTextAreaElement) The original textarea.
ext.CodeMirror.destroy Called just after CodeMirror is destroyed and the original textarea is restored.

パラメーター

  • (HTMLTextAreaElement) The original textarea.
ext.CodeMirror.input Called when document changes are made in CodeMirror. Note that the textarea may not be updated yet.

パラメーター

ext.CodeMirror.preferences.ready Fired just before CodeMirrorPreferences has been instantiated.

パラメーター

ext.CodeMirror.preferences.apply Fired when a CodeMirror preference is enabled or initially applied.

パラメーター

ext.CodeMirror.preferences.apply Fired when a CodeMirror preference is changed or initially applied in an editing session.

パラメーター

  • (string) The name of the preference.
  • (boolean) The new value of the preference.
ext.CodeMirror.preferences.display
(内部) 		Fired when the preferences panel is constructed, just before it is displayed.

パラメーター

  • (HTMLDivElement) The preferences panel container.
ext.CodeMirror.gotoLine
(内部) 		Fired when the go-to line panel is opened or closed.
ext.CodeMirror.keymap
(内部) 		Fired when the keyboard shortcut help dialog is opened.
ext.CodeMirror.search
(内部) 		Fired when the search panel is opened or closed.

イベントの使用

The following events are bubbled to the textarea for developer convenience:

Using these events, you can integrate with CodeMirror using the same code as the original textarea: 

myTextarea.addEventListener( 'keyup', ( event ) => {
	console.log( event.key );
} );

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: 

const require = await mw.loader.using( [ 'ext.CodeMirror.v6', 'ext.CodeMirror.v6.mode.mediawiki' ] );
const CodeMirror = require( 'ext.CodeMirror.v6' );
const { mediawiki } = 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( myTextarea, mediawiki() );
cm.initialize( [ cm.defaultExtensions, myExtension ] );

Or if you need to interact with an existing CodeMirror instance: 

// Ensure CodeMirror is initialized first
mw.hook( 'ext.CodeMirror.ready' ).add( ( cm ) => {
	const { EditorView } = require( 'ext.CodeMirror.v6.lib' );
	const myExtension = EditorView.updateListener.of( ( /** @type {ViewUpdate} */ update ) => {
		if ( update.docChanged ) {
		    // do something
		    console.log( update.changes );
		}
	} );
	cm.applyExtension( 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() );
} );

関連項目

注釈

  1. ↑ Focus is always placed on the editor in the 2017 editor.
  2. ↑ 2017年版エディターでは行の折り返しを無効にすることはできません。
  3. ↑ phab:T384556
  4. ↑ This event is not fired for wikitext (T401271)
Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:CodeMirror/ja&oldid=8242299"