Jump to content

Extension:CodeMirror

本頁使用了標題或全文手工轉換
From mediawiki.org
This page is a translated version of the page Extension:CodeMirror and the translation is 100% complete.
请勿与CodeEditor 混淆。
MediaWiki扩展手册
CodeMirror
发行状态: 稳定版
实现 用户界面
描述 为编辑器提供语法高亮
作者
维护者 Community Tech
最新版本 6.0.0
兼容性政策 快照跟随MediaWiki发布。 master分支不向后兼容。
PHP 8.2+
  • $wgCodeMirrorDefaultPreferencesCode
  • $wgCodeMirrorConflictingGadgets
  • $wgCodeMirrorEnabledModes
  • $wgCodeMirrorDefaultPreferences
  • $wgCodeMirrorPrimaryPreferences
许可证 GNU General Public License 2.0 or later
下載
README
帮助 Help:Extension:CodeMirror/zh
前往translatewiki.net翻譯CodeMirror扩展
問題 开启的任务 · 报告错误

CodeMirror扩展提供一個獨立的編輯器,其使用CodeMirror函式库提供多種程式語言和標記語言(包括wikitext)的语法高亮。 它可以與其他的編輯器一起使用,例如WikiEditor 2017 wikitext編輯器 校对页面 ,以及更多。 有關用法和功能清單,請參閱Help:Extension:CodeMirror

2024~2025年,此擴充功能升級到新的主要版本,CodeMirror 6,並隨之增加了許多新的功能

安裝

  • 下载文件,并解压CodeMirror文件夹到extensions/目录中。
    开发者和代码贡献人员应改从Git安装此扩展,输入:
    cd extensions/
    git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/CodeMirror
    
  • 請新增下列代码到您的LocalSettings.php 文件的底部:
    wfLoadExtension( 'CodeMirror' );
    
  • 按需求進行設定。
  • Yes 完成 – 請导航至您的wiki上的Special:Version,以验证此扩展已成功安装。

配置

有關顏色和各種CodeMirror功能的自訂,請參閱Help:Extension:CodeMirror .

若要在預設情況下為所有使用者啟用CodeMirror,請將下列內容加入到你的LocalSettings.php 中:

# 預設在維基文本中啟用CodeMirror,但仍可讓使用者停用它
$wgDefaultUserOptions[ 'usecodemirror' ] = true;

若在編輯程式碼時使用CodeMirror而非CodeEditor,則第二個使用者選項 usecodemirror-code 會生效,其預設值為 true

$wgCodeMirrorEnabledModes
控制著與Extension:CodeEditor 衝突的臨時功能旗號。 請參閱下方的用CodeMirror取代CodeEditor節以獲取更多資訊。
$wgCodeMirrorConflictingGadgets
小工具名稱的陣列,如果啟用,會阻止載入CodeMirror。預設的設定為wikEd
$wgCodeMirrorPrimaryPreferences
在編輯器內的偏好設定面板中的廣告偏好設定 。這些選項應具備明顯視覺效果或因普遍使用而值得提供更便捷的切換方式。「未」列於此處的偏好設定仍可在完整的偏好設定對話框中存取。
$wgCodeMirrorDefaultPreferences
控制著所有使用者預設啟用哪些功能 。 更多資訊請參閱下方
$wgCodeMirrorDefaultPreferencesCode
與 $wgCodeMirrorDefaultPreferences 相同,但適用於「程式碼」;也就是說,除「mediawiki」(維基文本)以外的任何 CodeMirror 模式。

默认首选项

預設偏好設定可選擇「維基文本」($wgCodeMirrorDefaultPreferences)或所有其他「模式」,例如 JavaScript、CSS、和JSON($wgCodeMirrorDefaultPreferencesCode)。 針對每一個功能,請使用truefalse來完整啟用或完全停用它、或是提供一個包含命名空間ID(整數)的陣列,其指出預設是啟用該功能的地方。

請注廳,此設定僅適用於「預設」值。使用者可在自己的CodeMirror偏好設定中覆寫其預設值。 變更設定時,該設定僅適用於維基文本(mediawiki 模式)或非維基文本(所有其他模式)。

例如:

# 將空白字元的標示範圍限制在非維基文字部分
$wgCodeMirrorDefaultPreferences[ 'whitespace' ] = false;
$wgCodeMirrorDefaultPreferencesCode[ 'whitespace' ] = true;

# 若要將自動完成功能僅限對模板和代碼有效
$wgCodeMirrorDefaultPreferences[ 'autocomplete' ] = [ NS_TEMPLATE ];
$wgCodeMirrorDefaultPreferencesCode[ 'autocomplete' ] = true;
$wgCodeMirrorDefaultPreferences
功能 2017編輯器
兼容性
默认值 預設值(代碼)[1]
activeLine N false true
autocomplete N true true
autofocus Yes[2] true true
bidiIsolation[3] N false false
bracketMatching Yes true true
closeBrackets N false true
closeTags[4] N false false
codeFolding N true true
foldAllRefs [5] N false N/A
highlightRefs [6] Yes true N/A
lineNumbering Yes true true
lineWrapping Yes[7] true true
lint N false true
openLinks N true true
specialChars N true true
trailingWhitespace N false false
whitespace N false false

與 CodeMirror 5 的差異

新功能

各個廢棄以及其他的變更

  • 資源加载器模組已變更。請參閱遷移指南
  • ext.CodeMirror.switch钩子已被廢棄。 請改用ext.CodeMirror.toggle
  • .cm-mw-mnemonic CSS類別已更名為.cm-mw-html-entity
  • .cm-mw-doubleUnderscore CSS類別已更名為.cm-mw-double-underscore
  • .cm-mw-template-name-mnemonic類別已移除。 請改用.cm-mw-template-ground.cm-html-entity
  • .cm-mw-apostrophes-bold.cm-mw-apostrophes-italic CSS類別已移除。 請改用.cm-mw-apostrophes
  • 針對<nowiki><pre>、或任何與TagMode無關的標籤的單行等級設計已移除(T351686)。
  • wikitext內的混合語言目前尚未支援(T357480)。
  • 瀏覽器(使用Ctrl+F)的原生搜尋功能已被CodeMirror內建的搜尋功能取代。 這是為了維持效能所必需的 (T303664)。

遷移指南

MediaWiki版本:
1.45

本指南適用於MediaWiki 1.45及後續版本。自MediaWiki 1.46起,CodeMirror 5將不再受支援。

MediaWiki的組態

  • $wgCodeMirrorLineNumberingNamespaces 已被廢棄。 請改為設定$wgCodeMirrorDefaultPreferences

資源加载器模組

請確保您使用的是正確的資源加载器模組。 由於 CodeMirror 6 不再依賴 WikiEditor,因此相較於 CodeMirror 5 的對應功能,存在以下命名與行為上的變更:

為簡化起見,部份模組名稱並未顯示前綴ext.CodeMirror;使用時請將『…』替換為實際參數。

舊模組 舊模組(MW 1.45) 新模組(MW 1.46以上) 描述
ext.CodeMirror ….v6.init ….init 為WikiEditor整合 CodeMirror 功能(在 #wpTextbox1 處的標準的文字輸入區域)。
N/A ….v6.WikiEditor ….WikiEditor 匯出CodeMirrorWikiEditor類別
N/A ….v6.init ….init CodeMirror用於#wpTextbox1及其它受支援頁面。
….lib ….v6.lib ….lib 匯出CodeMirror的內部元件。
….addons N/A N/A 這包裝了CodeMirror 5中的括弧匹配功能。在CodeMirror 6中,括號匹配是預設行為。
….mode.mediawiki ….v6.mode.mediawiki ….mode.mediawiki MediaWiki語言模式。
N/A ext.CodeMirror.v6 ext.CodeMirror 匯出CodeMirror類別。
….visualEditor ….visualEditor.init ….visualEditor.init 整合2017 wikitext編輯器
….lib.mode.php N/A CodeMirror 6最終將提供部份或全部這些模式,但它們不會以獨立模組的形式提供。
….lib.mode.clike
….lib.mode.htmlmixed
….lib.mode.xml
….lib.mode.javascript ….v6.modes ….modes 這些語言在CodeMirror 6中有支援。
….lib.mode.css
N/A
N/A
N/A

隨著 MediaWiki 1.46 的發佈,舊版模組將被新版模組所取代,而 .v6 模組將被完全移除。

小工具與使用者腳本

CodeMirror的全域功能已完全取消。 舉例來說,CodeMirror.fromTextArea( myTextarea )將不再有用。 取而代之的是,請先載入所需的資源加载器模組,實例化物件CodeMirror、然後呼叫方法initialize()

若您的腳本依賴勾點ext.CodeMirror.switch來改變其與編輯器的互動方式,則需改用ext.CodeMirror.toggle、或改為監聽事件。 請參閱JavaScript整合部份以獲取更多資訊。

CSS

元素.CodeMirror已不復存在。 請改用.cm-editor以應對CodeMirror DOM,或使用.cm-content以應對內部的內容(例如不包含搜尋面板)。

請參見過時功能及其他變更以了解其他的CSS類別。

整合

MediaWiki扩展

用CodeMirror取代CodeEditor

MediaWiki版本:
1.44

自 MediaWiki 1.44 起,CodeMirror 支援 Lua、JavaScript、CSS、JSON、及Vue語言的語法高亮功能。此功能可作為 Extension:CodeEditor 的替代方案。

請注意,並非所有與 CodeEditor 整合的擴充功能都已更新到能支援CodeMirror。若您正在使用這些擴充功能,建議您保留CodeEditor在維基上的安裝:

自MediaWiki 1.45以上起,為使此設定生效,您需相應調整 $wgCodeMirrorEnabledModes 變數,同時也需針對已安裝的相關擴充功能,調整 *UseCodeEditor*UseCodeMirror 變數:

// 應使用 CodeMirror 的期望模式(MediaWiki 預設啟用媒體文本模式)
$wgCodeMirrorEnabledModes['javascript'] = true;
$wgCodeMirrorEnabledModes['json'] = true;
$wgCodeMirrorEnabledModes['css'] = true;
$wgCodeMirrorEnabledModes['lua'] = true;
$wgCodeMirrorEnabledModes['vue'] = true;

// 若您同時使用 CodeEditor,請在這裏停用相同的模式:
$wgCodeEditorEnabledModes['javascript'] = false;
$wgCodeEditorEnabledModes['json'] = false;
$wgCodeEditorEnabledModes['css'] = false;
$wgCodeEditorEnabledModes['lua'] = false;
$wgCodeEditorEnabledModes['vue'] = false;

// AbuseFilter(請注意,上方無需設定相應的「模式」)
$wgAbuseFilterUseCodeEditor = false;
$wgAbuseFilterUseCodeMirror = true;

// 小工具(用於編輯小工具定義 JSON 頁面)
$wgGadgetsDefinitionsUseCodeEditor = false;
$wgGadgetsDefinitionsUseCodeMirror = true;

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

// Scribunto(用於編輯採用「lua」模式的模組頁面)
$wgScribuntoUseCodeEditor = false;
$wgScribuntoUseCodeMirror = true;

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

// 上傳精靈(用於編輯活動 JSON 頁面)
$wgUploadWizardUseCodeEditor = false;
$wgUploadWizardUseCodeMirror = true;

為MediaWiki註冊一個新標籤

若您僅需讓CodeMirror識別由擴充套件新增的標籤 ,可透過CodeMirrorTagModes擴充功能屬性 來達成。 例如,欲將標籤‎<foo>註冊為包含維基文本格式之標籤,請於extension.json中新增以下內容:

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

CodeMirror 隨後將把 ‎<foo>...‎</foo> 內的內容標示為維基文本。

註冊一個標籤使得CodeMirror將內容視為非維基文本,目前尚不支援(T357480)。 若未註冊該標籤,CodeMirror 將以與標示 ‎<nowiki>...‎</nowiki> 標籤內容相同的方式,將內容標示為非維基文本。

PHP钩子

MediaWiki版本:
1.44

自MediaWiki 1.44起,在PHP中與CodeMirror整合的首選方式是實作這個CodeMirrorGetModeHook介面:

class CodeMirrorHooks implements CodeMirrorGetModeHook {
	public function onCodeMirrorGetMode(Title $title, ?string &$mode, string $model ): bool {
		// 判斷是否應使用 CodeMirror 的邏輯
		if ( $title->hasContentModel( 'JsonLikeContentModel' ) ) {
			$mode = 'json';
			return false;
		}

		return true;
	}
}

在extension.json中註冊钩子:

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

插件模組

CodeMirrorPluginModules 是一個擴充功能屬性 ,可讓CodeMirror旁載一個模組。 此設定會在每次載入 ext.CodeMirror 模組時,無條件地載入該模組。

extension.json:

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

JavaScript

CodeMirror編輯器並非真正的文字輸入區域,而是一個可編輯內容。 開發人員通常需確保程式碼能同時支援這兩種情境,因為CodeMirror可被切換關閉。

要偵測文件的變更,使用事件鉤子可能是最簡單的方法。 若需讀取與修改變更的內容,jQuery.textSelection可能較為便利。

若需更複雜的整合方案、或追求更優異的效能表現,您可為新建立或現有的CodeMirror實例新增自訂的擴充功能

使用jQuery.textSelection

若您僅需擷取或修改文件的文字內容,jQuery.textSelection便是最簡易且最可靠的方法。 在文字輸入區使用jQuery.textSelection會向上冒泡至CodeMirror,因此您無需知道CodeMirror是否已啟用:

const $textarea = $( '#wpTextbox1' )
const content = $textarea.textSelection( 'getContents' );
// Append "Foobar" to the content.
$textarea.textSelection( 'setContents', content + '\nFoobar' );
  1. wpTextbox1上的jQuery的.val()函式「可」被使用,[8]但不建議如此操作,且可能無法在所有編輯器(例如2017 wikitext編輯器 )中正常運作。

運用資源加载器模組

CodeMirror擴充功能提供多個 资源加载器 模組,給使用者腳本、小工具、及擴充功能使用。 若要運用CodeMirror,您至少需要有ext.CodeMirror模組、搭配你所需的「模式」。

模式可從資源加载器模組中解壓縮,其使用與模式名稱相同的匯出方法。 對於 MediaWiki 維基文本,您應該會使用 ext.CodeMirror.mode.mediawiki;而對於 JavaScript、JSON、CSS、Vue、和Lua,則應該會使用 ext.CodeMirror.modes

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

若您也想要WikiEditor:

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

請建立一個新的JavaScript實例:

const require = await mw.loader.using( [ 'ext.CodeMirror', 'ext.CodeMirror.modes' ] );
const CodeMirror = require( 'ext.CodeMirror' );
const { javascript } = require( 'ext.CodeMirror.modes' );
const cm = new CodeMirror( myTextarea, javascript() );
cm.initialize();
資源加载器模組
模組 描述
ext.CodeMirror.lib 核心 CodeMirror 函式庫,你不會直接需要此函式庫,除非您需要存取上游的CodeMirror API
ext.CodeMirror MediaWiki編輯器的基礎的CodeMirror整合模組。 此模組是匯出CodeMirror類別。
ext.CodeMirror.WikiEditor WikiEditor的CodeMirror整合模組。 此模組是匯出CodeMirrorWikiEditor類別。
ext.CodeMirror.mode.mediawiki 導出用於高亮顯示MediaWiki wiki文字的 mediawiki 模式。
ext.CodeMirror.modes 包含有javascriptjsoncssvue、及lua模式。
ext.CodeMirror.init
(內部的)
action=edit 请求的主要入口点。不用于外部用途。
ext.CodeMirror.visualEditor.init
(內部的)
CodeMirror與2017 wikitext編輯器 的整合功能,僅限於維基文本格式。

使用钩子

您也可以使用前端的钩子與CodeMirror整合。這些钩子允許您在CodeMirror載入之前或之後執行程式碼,或對文件的變更做出反應。

前端的钩子
钩子 描述
ext.CodeMirror.initialize 請在 CodeMirror 初始化之前調用。此方法可用於操作DOM以配合CodeMirror的需求。(例如:若您操作WikiEditor的DOM,可能需要使用此方法)。

参数

  • (HTMLTextAreaElement) 當前的「編輯器」,最可能是#wpTextbox1.
  • (ve.ui.Surface) 若適用的話,它是CodeMirror所綁定的視覺編輯器表面。
ext.CodeMirror.ready 在CodeMirror 始化完成後立即呼叫的。

参数

ext.CodeMirror.toggle 當CodeMirror被開啟或關閉時被呼叫的。

参数

  • (boolean) CodeMirror 是否已啟用。
  • (CodeMirror) CodeMirror 實例。
  • (HTMLTextAreaElement) 原始的文字輸入區。
ext.CodeMirror.destroy 在CodeMirror被摧毀且原始文字輸入區域恢復後立即被呼叫的。

参数

  • (HTMLTextAreaElement) 原始的文字輸入區。
ext.CodeMirror.input 當 CodeMirror 中的文件內容發生變更時被呼叫的。請注意,此時文字輸入區可能尚未更新。

参数

ext.CodeMirror.preferences.ready CodeMirrorPreferences 實例化之前被觸發的。

参数

ext.CodeMirror.preferences.apply 當某個CodeMirror的偏好設定被啟用或是初始套用時,被觸發的。

参数

ext.CodeMirror.preferences.display
(內部的)
在偏好設定面板建構完成時被觸發的,就在其顯示之前。

参数

  • (HTMLDivElement) 偏好設定的面板容器。
ext.CodeMirror.gotoLine
(內部的)
當go-to line面板開啟或關閉時觸發。
ext.CodeMirror.keymap
(內部的)
當開啟鍵盤快捷鍵說明對話方塊時觸發。
ext.CodeMirror.search
(內部的)
當搜尋面板開啟或關閉時觸發。

使用事件

以下事件會為方便開發者在文字區域冒泡:

透過這些事件,您可以使用與原始文字區域相同的程式碼來與 CodeMirror 進行整合:

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

擴展 CodeMirror

您可以導入ext.CodeMirror.lib模組以存取上游的CodeMirror API。 藉此,您可在建立CodeMirrorCodeMirrorWikiEditor物件時提供你自己的擴充功能

例如,若要提供自己的擴充功能以回應CodeMirror中的變更:

const require = await mw.loader.using( [ 'ext.CodeMirror', 'ext.CodeMirror.mode.mediawiki' ] );
const CodeMirror = require( 'ext.CodeMirror' );
const { mediawiki } = require( 'ext.CodeMirror.mode.mediawiki' );
// ext.CodeMirror.lib 是 ext.CodeMirror 的-{zh-hans:依赖; zh-hant:依存;}-項,因此此時它已經載入完畢。
const { EditorView } = require( 'ext.CodeMirror.lib' );
const myExtension = EditorView.updateListener.of( ( /** @type {ViewUpdate} */ update ) => {
	if ( update.docChanged ) {
	    // 做某事
	    console.log( update.changes );
	}
} );
const cm = new CodeMirror( myTextarea, mediawiki() );
cm.initialize( [ cm.defaultExtensions, myExtension ] );

或者,若需與現有的 CodeMirror 實例進行互動:

// 請確保 CodeMirror 先完成初始化
mw.hook( 'ext.CodeMirror.ready' ).add( ( cm ) => {
	const { EditorView } = require( 'ext.CodeMirror.lib' );
	const myExtension = EditorView.updateListener.of( ( /** @type {ViewUpdate} */ update ) => {
		if ( update.docChanged ) {
		    // 做某事
		    console.log( update.changes );
		}
	} );
	cm.applyExtension( myExtension );
} );

另一種監聽變更的方法是使用 ext.CodeMirror.input 鉤點

mw.hook( 'ext.CodeMirror.input' ).add( ( update ) => {
	// 將 ChangeSet 輸出至控制台
	console.log( update.changes.toJSON() );
} );

版本歷史

  • 2024年11月 – 此擴充功能的CodeMirror 6 版本是以測試版功能的形式推出的。
  • – 經過兩年的開發與測試,「改良版語法高亮」(CodeMirror 6)已正式脫離測試階段。此次更新為標準語法高亮工具的所有使用者帶來了程式碼摺疊、自動完成、及程式碼檢查等進階功能,同時也大幅提升了維基文本的可讀性。[10]

参见

注释

  1. $wgCodeMirrorDefaultPreferencesCode
  2. 在2017編輯器中,焦點始終被安置於編輯器之上。
  3. 此功能目前尚未穩定。
  4. 僅在維基文本中生效。
  5. 僅適用於維基文本。
  6. 僅適用於維基文本。
  7. 在2017編輯器中,無法停用換行功能。
  8. phab:T384556
  9. 此事件不會針對維基文本觸發 (T401271)
  10. Tech News 2026 – Issue 17, Wikimedia Diff. Published April 20, 2026.