Extension:CodeMirror
- 请勿与CodeEditor混淆。
发行状态: 稳定版 |
|
|---|---|
| 实现 | 用户界面 |
| 描述 | 为编辑器提供语法高亮 |
| 作者 | |
| 维护者 | Community Tech |
| 最新版本 | 6.0.0 |
| 兼容性政策 | 快照跟随MediaWiki发布。 master分支不向后兼容。 |
| PHP | 8.2+ |
|
|
| 许可证 | 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,並隨之增加了許多新的功能。
- 有關舊版本的資訊,請參閱Extension:CodeMirror/5。
- 有關說明文件,請參閱 Help:Extension:CodeMirror。
- 有關JavaScript的文件,請參閱 wmdoc:CodeMirror。
安裝
- 下载文件,并解压
CodeMirror文件夹到extensions/目录中。
开发者和代码贡献人员应改从Git安装此扩展,输入:cd extensions/ git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/CodeMirror
- 請新增下列代码到您的LocalSettings.php文件的底部:
wfLoadExtension( 'CodeMirror' );
- 按需求進行設定。
完成 – 請导航至您的wiki上的Special:Version,以验证此扩展已成功安装。
配置
若要在預設情況下為所有使用者啟用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)。 針對每一個功能,請使用true或false來完整啟用或完全停用它、或是提供一個包含命名空間ID(整數)的陣列,其指出預設是啟用該功能的地方。
請注廳,此設定僅適用於「預設」值。使用者可在自己的CodeMirror偏好設定中覆寫其預設值。
變更設定時,該設定僅適用於維基文本(mediawiki 模式)或非維基文本(所有其他模式)。
例如:
# 將空白字元的標示範圍限制在非維基文字部分
$wgCodeMirrorDefaultPreferences[ 'whitespace' ] = false;
$wgCodeMirrorDefaultPreferencesCode[ 'whitespace' ] = true;
# 若要將自動完成功能僅限對模板和代碼有效
$wgCodeMirrorDefaultPreferences[ 'autocomplete' ] = [ NS_TEMPLATE ];
$wgCodeMirrorDefaultPreferencesCode[ 'autocomplete' ] = true;
| 功能 | 2017編輯器 兼容性 |
默认值 | 預設值(代碼)[1] |
|---|---|---|---|
activeLine |
|
| |
autocomplete |
|
| |
autofocus |
|
| |
bidiIsolation[3] |
|
| |
bracketMatching |
|
| |
closeBrackets |
|
| |
closeTags[4] |
|
| |
codeFolding |
|
| |
foldAllRefs[5] |
|
N/A | |
highlightRefs[6] |
|
N/A | |
lineNumbering |
|
| |
lineWrapping |
|
| |
lint |
|
| |
openLinks |
|
| |
specialChars |
|
| |
trailingWhitespace |
|
| |
whitespace |
|
|
與 CodeMirror 5 的差異
新功能
- 不再需要使用WikiEditor。
- 支援Scribunto、JavaScript、CSS、JSON、和Vue,可作為CodeEditor的替代。
- 效能大幅提升。
- 具有雙向文字隔離的由右至左文字的支援(T170001)。 (T358804)
- 代碼折疊。 (T30684)
- 自動完成。 (T95100)
- 程式碼格式檢查工具。 (T381577)
- 使用修改鍵+按一下即可快速開啟連結. (T303392)
- 改善搜尋面板。 (T371436)
- CodeMirror 偏好設定。 (T359498)
- 在讨论工具中的高亮顯示語法。 (T407918)
- 在唯讀頁面上高亮顯示語法。 (T301615)
- 在Special:Upload上的高亮顯示語法。 (T170246)
- 在Special:ExpandTemplates中的高亮顯示語法。 (T384148)
- 在Special:AbuseFilter中的高亮顯示語法。 (T399673)
- 在
Special:SecurePoll/translate中的高亮顯示語法。 (T397871) - 強大的JavaScript API可整合擴充功能、小工具、使用者的腳本。
各個廢棄以及其他的變更
- 資源加载器模組已變更。請參閱遷移指南。
ext.CodeMirror.switch钩子已被廢棄。 請改用ext.CodeMirror.toggle。.cm-mw-mnemonicCSS類別已更名為.cm-mw-html-entity。.cm-mw-doubleUnderscoreCSS類別已更名為.cm-mw-double-underscore。.cm-mw-template-name-mnemonic類別已移除。 請改用.cm-mw-template-ground.cm-html-entity。.cm-mw-apostrophes-bold和.cm-mw-apostrophes-italicCSS類別已移除。 請改用.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在維基上的安裝:
- Extension:VisualEditor--使用CodeEditor模組為其他與VisualEditor整合的擴充功能提供語法高亮功能(T400014):
- Extension:WikiLambda--依賴於CodeEditor的
ext.wikilambda.app模組(T400015)。
自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' );
- 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
|
包含有javascript、json、css、vue、及lua模式。
|
ext.CodeMirror.init(內部的) |
action=edit 请求的主要入口点。不用于外部用途。 |
ext.CodeMirror.visualEditor.init(內部的) |
CodeMirror與2017 wikitext編輯器的整合功能,僅限於維基文本格式。 |
使用钩子
您也可以使用前端的钩子與CodeMirror整合。這些钩子允許您在CodeMirror載入之前或之後執行程式碼,或對文件的變更做出反應。
| 钩子 | 描述 |
|---|---|
ext.CodeMirror.initialize
|
請在 CodeMirror 初始化之前調用。此方法可用於操作DOM以配合CodeMirror的需求。(例如:若您操作WikiEditor的DOM,可能需要使用此方法)。
参数
|
ext.CodeMirror.ready
|
在CodeMirror 始化完成後立即呼叫的。
参数
|
ext.CodeMirror.toggle
|
當CodeMirror被開啟或關閉時被呼叫的。
参数
|
ext.CodeMirror.destroy
|
在CodeMirror被摧毀且原始文字輸入區域恢復後立即被呼叫的。
参数
|
ext.CodeMirror.input
|
當 CodeMirror 中的文件內容發生變更時被呼叫的。請注意,此時文字輸入區可能尚未更新。
参数
|
ext.CodeMirror.preferences.ready
|
在 CodeMirrorPreferences 實例化之前被觸發的。
参数
|
ext.CodeMirror.preferences.apply
|
當某個CodeMirror的偏好設定被啟用或是初始套用時,被觸發的。
参数
|
ext.CodeMirror.preferences.display(內部的) |
在偏好設定面板建構完成時被觸發的,就在其顯示之前。
参数
|
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。
藉此,您可在建立CodeMirror或CodeMirrorWikiEditor物件時提供你自己的擴充功能。
例如,若要提供自己的擴充功能以回應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]
参见
- User:Remember the dot/Syntax highlighter
- Extension:VisualEditor
- Extension:WikiEditor
- Extension:CodeEditor
- EditorAPIs: A library that presents a common interface for wikitext editing. Support for the legacy editor, VE, 2017 source editor and CodeMirror 5/6.
- c:Category:MediaWiki extension CodeMirror
注释
| 此扩展用于一个或多个维基媒体项目。 这可能意味着扩展足够稳定、运作足够良好,可以用在这样的高流量的网站上。 请在维基媒体的CommonSettings.php和InitialiseSettings.php配置文件中查找此扩展的名称以查看哪些网站安装了该扩展。 特定wiki上的已安装的扩展的完整列表位于Special:Version页面。 |
| 此扩展在以下wiki农场/托管网站和/或软件包中提供: |
- Stable extensions/zh
- User interface extensions/zh
- EditPage::showEditForm:initial extensions/zh
- EditPage::showReadOnlyForm:initial extensions/zh
- GetPreferences extensions/zh
- SpecialPageAfterExecute extensions/zh
- UploadForm:initial extensions/zh
- GPL licensed extensions/zh
- Extensions in Wikimedia version control/zh
- All extensions/zh
- Pages using deprecated NoteTA template
- Extensions used on Wikimedia/zh
- Extensions included in Canasta/zh
- Extensions included in Fandom/zh
- Extensions included in Miraheze/zh
- Extensions included in MyWikis/zh
- Extensions included in ProWiki/zh
- Extensions included in Telepedia/zh
- Extensions included in Weird Gloop/zh
- Extensions included in wiki.gg/zh
- Syntax highlighting extensions/zh
