手把手教你實現在Monaco Editor中使用VSCode主題

語言: CN / TW / HK

背景

筆者開源了一個小項目code-run,類似codepen的一個工具,其中代碼編輯器使用的是微軟的Monaco Editor,這個庫是直接從VSCode的源碼中生成的,只不過是做了一點修改讓它支持在瀏覽器中運行,但是功能基本是和VSCode一樣強大的,所以在筆者看來Monaco Editor等於VSCode的編輯器核心。

另外筆者是一個顏控,不管做什麼項目,都熱衷於配套一些好看的皮膚、主題,所以Moncao Editor僅僅內置了三種主題是遠遠滿足不了筆者需求的,況且還都很醜,於是結合Monaco EditorVSCode的關係就很自然的想到,能不能直接複用VSCode的主題,接下來就給大家介紹一下筆者的探索之路。

ps.想直接瞭解如何實現的可以跳轉到【具體實現】小節。

基本使用

先看一下Monaco Editor的基本使用,首先安裝:

bash npm install monaco-editor

然後引入:

```js import * as monaco from 'monaco-editor'

// 創建一個js編輯器 const editor = monaco.editor.create(document.getElementById('container'), { value: ['function x() {', '\tconsole.log("Hello world!");', '}'].join('\n'), language: 'javascript', theme: 'vs' }) ```

這樣就可以在container元素上創建一個js語言的編輯器,並且使用了內置的vs-dark主題。如果遇到報錯或者語法提示不生效,那麼可能需要配置一下worker文件的路徑,可以參考官方示例browser-esm-webpack

自定義主題

Monaco Editor支持自定義主題,方法如下:

js // 定義主題 monaco.editor.defineTheme(themeName, themeData) // 使用定義的主題 monaco.editor.setTheme(themeName)

themeName是要自定義的主題名稱,比如OneDarkProthemeData是一個對象,即主題數據,基本結構如下:

js { base: 'vs',// 要繼承的基礎主題,即內置的三個:vs、vs-dark、hc-black inherit: false,// 是否繼承 rules: [// 高亮規則,即給代碼裏不同token類型的代碼設置不同的顯示樣式 { token: '', foreground: '000000', background: 'fffffe' } ], colors: {// 非代碼部分的其他部分的顏色,比如背景、滾動條等 [editorBackground]: '#FFFFFE' } }

rules裏面就是用來給代碼進行高亮的,常見的tokenstring(字符串)、comment(註釋)、keyword(關鍵詞)等等,完整的請移步themes.ts,這些token是怎麼確定的呢,Monaco Editor內置了一個語法着色器Monarch,本質是通過正則表達式來匹配,然後給匹配到的內容命名為一個token

可以直接在編輯器中查看代碼某塊對應的token,按F1或鼠標右鍵點擊Command Palette,然後再找到並點擊Developer: Inspect Tokens,接下來鼠標點哪一塊代碼,就會顯示對應的信息,包括token類型,當前應用的顏色等。

踩坑

最開始的想法很簡單,直接找到VSCode的主題文件,然後通過自定義主題來使用。

獲取VSCode主題文件

有兩種方法,如果某個主題已經在你的VSCode裏安裝並正在使用的話,那麼可以按F1Command/Control + Shift + P或鼠標右鍵點擊Command Palette/命令面板,接着找到並點擊Developer:Generate Color Theme From Current Setting/開發人員:使用當前設置生成顏色主題,然後VSCode就會生成一份json數據,保存即可。

如果某個主題沒有安裝的話,那麼可以去vscode主題商店搜索該主題,進入主題詳情頁面後點擊右側的Download Extension按鈕即可下載該主題,下載完成後找到剛才下載的文件,文件應該是以.vsix結尾的,直接把該後綴改成.zip,然後解壓縮,最後打開裏面的/extension/themes/文件夾,裏面的.json文件即主題文件,打開該文件複製json數據即可。

VSCode主題轉換成Monaco Editor主題格式

上一步過後你應該可以發現VSCode主題的格式是這樣的:

json { "$schema": "vscode://schemas/color-theme", "type": "dark", "colors": { "activityBar.background": "#282c34" }, "tokenColors": [ { "scope": "variable.other.generic-type.haskell", "settings": { "foreground": "#C678DD" } }, { "scope": [ "punctuation.section.embedded.begin.php", "punctuation.section.embedded.end.php" ], "settings": { "foreground": "#BE5046" } } ] }

Monaco Editor的主題格式有一點區別,那是不是可以寫一個轉換方法把它轉換成下面這樣呢:

js { base: 'vs', inherit: false, rules: [ { token: 'variable.other.generic-type.haskell', foreground: '#C678DD' }, { token: 'punctuation.section.embedded.begin.php', foreground: '#BE5046' }, { token: 'punctuation.section.embedded.end.php', foreground: '#BE5046' } ], colors: { "activityBar.background": "#282c34" } }

當然可以,這也不難,但是最後當你使用這個自定義的主題後會發現,沒有效果,為什麼呢,去Monarch看一下對應語言的解析配置後就會發現,壓根就沒有VSCode主題裏定義的這些token,有效果才奇怪,那怎麼辦呢,自己擴展這個解析的配置嗎,筆者最開始就是這麼做的,寫正則表達式嘛,應該也不是很難,為此,筆者還把Monarch文檔完整翻譯了一遍Monarch中文,但是當筆者在VSCode裏看到如下效果時:

image-20210918142132745.png

果斷放棄,這顯然是要進行語義分析才行,否則誰知道abc是個變量。

其實在VSCode里語法高亮使用的是TextMate,而在Monaco Editor裏使用的是Monarch,兩者壓根不是一個東西,為什麼Monaco Editor不使用TextMate,而是要開發一個新的東西呢,原因是VSCode使用的是vscode-textmate來解析TextMate語法,這個庫依賴一個Oniguruma正則表達式庫,而這個正則表達式庫是使用C語言開發的,當然不支持在瀏覽器上運行。

退而求其次

既然VSCode的主題不能直接使用,那麼就只能能用多少用多少,因為Monaco Editor內置的主題token就只有那麼多,那麼把它所有的token顏色換成VSCode的主題顏色不就行了嗎,雖然語義高亮沒有,但是總比默認主題好看。實現也很簡單,首先colors部分的基本可以直接使用,而token部分可以通過上面介紹的方法Developer: Inspect TokensVSCode裏找到對應代碼塊的顏色,複製到Monaco Editor主題的對應token上即可,比如筆者轉換後的OneDarkPro的實際效果如下:

image-20210918143406409.png

VSCode裏的效果如下:

image-20210918143427581.png

只可粗看,不要細究。

這個事情也有人已經做了,可以參考這個倉庫monaco-themes,裏面幫你轉換了一些常見的主題,可以拿來直接使用。

新的曙光

就在筆者已經放棄在Monaco Editor中直接使用VSCode主題的想法後,無意間發現codesandboxleetcode兩個網站中的編輯器主題效果和VSCode中基本一致,而且可以明顯的看到在leetcode中切換主題請求的文件:

image-20210918161935357.png

基本和VSCode主題格式是一樣的,這就説明在Monaco Editor中使用VSCode主題是可以實現的,那麼問題就變成了怎麼實現。

實現

不得不説,這方面資料真的很少,相關文章基本沒有,百度搜索結果裏只有一兩個相關的鏈接,不過也足以解決問題了,相關鏈接詳見文章尾部。

主要使用的是monaco-editor-textmate這個工具(所以除了百度谷歌之外,github也是一個很重要的搜索引擎啊),先安裝:

bash npm i monaco-editor-textmate

npm應該會同時幫你再安裝monaco-textmateonigasmmonaco-editor這幾個包,monaco-editor自不必説,我們自己都裝了,其他兩個可以自行檢查一下,如果沒有的話需要自行安裝。

工具介紹

簡單介紹一下這幾個包。

onigasm

這個庫就是用來解決上述瀏覽器不支持C語言編寫的Oniguruma的問題,解決方法是把Oniguruma編譯為WebAssemblyWebAssembly是一種中間格式,可以把非js代碼編譯成.wasm格式的文件,然後瀏覽器就可以加載並運行它了,WebAssembly已經是WEB的標準之一了,隨着時間的推移,相信兼容性也不是問題。

monaco-textmate

這個庫是在VSCode使用的vscode-textmate庫的基礎上修改的, 以便讓它在瀏覽器上使用。主要作用是解析TextMate語法,這個庫依賴前面的onigasm

monaco-editor-textmate

這個庫的主要作用是幫我們把monaco-editormonaco-textmate關聯起來,內部首先會加載對應語言的TextMate語法文件,然後調用monaco.languages.setTokensProvider方法來自定義語言的token解析器。

看一下它的使用示例:

js import { loadWASM } from 'onigasm' import { Registry } from 'monaco-textmate' import { wireTmGrammars } from 'monaco-editor-textmate' export async function liftOff() { await loadWASM(`path/to/onigasm.wasm`) const registry = new Registry({ getGrammarDefinition: async (scopeName) => { return { format: 'json', content: await (await fetch(`static/grammars/css.tmGrammar.json`)).text() } } }) const grammars = new Map() grammars.set('css', 'source.css') grammars.set('html', 'text.html.basic') grammars.set('typescript', 'source.ts') monaco.editor.defineTheme('vs-code-theme-converted', {}); var editor = monaco.editor.create(document.getElementById('container'), { value: [ 'html, body {', ' margin: 0;', '}' ].join('\n'), language: 'css', theme: 'vs-code-theme-converted' }) await wireTmGrammars(monaco, registry, grammars, editor) }

具體實現

看完前面的使用示例後,接下來我們詳細看一下如何使用。

加載onigasm

首先我們要做的是加載onigasmwasm文件,這個文件需要首先被加載,且加載一次就可以了,所以我們在編輯器初始化前進行加載:

js import { loadWASM } from 'onigasm' const init = async () => { await loadWASM(`${base}/onigasm/onigasm.wasm`) // 創建編輯器... } init()

onigasm.wasm文件可以在/node_modules/onigasm/lib/目錄下找到,然後複製到項目的/public/onigasm/目錄下,這樣可以通過http進行請求。

創建作用域映射

接下來創建語言id到作用域名稱的映射:

js const grammars = new Map() grammars.set('css', 'source.css')

其他語言的作用域名稱可以在各種語言的語法列表這裏找到,比如想知道css的作用域名稱,我們進入css目錄,然後打開package.json文件,可以看到其中有一個grammars字段:

js "grammars": [ { "language": "css", "scopeName": "source.css", "path": "./syntaxes/css.tmLanguage.json", "tokenTypes": { "meta.function.url string.quoted": "other" } } ]

language就是語言idscopeName就是作用域名稱。常見的如下:

js const scopeNameMap = { html: 'text.html.basic', pug: 'text.pug', css: 'source.css', less: 'source.css.less', scss: 'source.css.scss', typescript: 'source.ts', javascript: 'source.js', javascriptreact: 'source.js.jsx', coffeescript: 'source.coffee' }

註冊語法映射

再接着註冊TextMate的語法映射關係,這樣可以通過作用域名稱來加載並創建對應的語法:

```js import { Registry } from 'monaco-textmate'

// 創建一個註冊表,可以從作用域名稱來加載對應的語法文件 const registry = new Registry({ getGrammarDefinition: async (scopeName) => { return { format: 'json',// 語法文件格式,有json、plist content: await (await fetch(${base}grammars/css.tmLanguage.json)).text() } } }) ```

語法文件和前面的作用域名稱一樣,也是在各種語言的語法列表這裏找,同樣以css語言為例,還是看它的package.jsongrammars字段:

js "grammars": [ { "language": "css", "scopeName": "source.css", "path": "./syntaxes/css.tmLanguage.json", "tokenTypes": { "meta.function.url string.quoted": "other" } } ]

path字段就是對應的語法文件的路徑,我們把這些json文件複製到項目的/public/grammars/目錄下,這樣就可以通過fetch來請求到。

定義主題

前面介紹過,Monaco Editor的主題格式和VSCode的格式是有點不一樣的,所以需要進行轉換,轉換可以自己實現,也可以直接使用monaco-vscode-textmate-theme-converter這個工具,它可以同時轉換多個本地文件:

```js // convertTheme.js const converter = require('monaco-vscode-textmate-theme-converter') const path = require('path')

const run = async () => { try { await converter.convertThemeFromDir( path.resolve(__dirname, './vscodeThemes'), path.resolve(__dirname, '../public/themes') ); } catch (error) { console.log(error) } } run() ```

運行node ./convertTheme.js命令後,就會把你放在vscodeThemes目錄下所有VSCode的主題文件轉換成Monaco Editor的主題文件並輸出到public/themes目錄下,然後我們在代碼裏直接通過fetch來請求主題文件並使用defineTheme方法定義主題即可:

js // 請求OneDarkPro主題文件 const themeData = await ( await fetch(`${base}themes/OneDarkPro.json`) ).json() // 定義主題 monaco.editor.defineTheme('OneDarkPro', themeData)

設置token解析器

經過前面這些準備工作,最後一步要做的是設置Monaco Editortoken解析器,默認使用的是內置的Monarch,我們要換成TextMate的解析器,也就是monaco-editor-textmate做的事情:

```js import { wireTmGrammars } from 'monaco-editor-textmate' import * as monaco from 'monaco-editor'

let editor = monaco.editor.create(document.getElementById('container'), { value: [ 'html, body {', ' margin: 0;', '}' ].join('\n'), language: 'css', theme: 'OneDarkPro' })

await wireTmGrammars(monaco, registry, grammars, editor) ```

問題1

上一步後應該可以看到VSCode的主題在Monaco Editor上生效了,但是多試幾次可能會發現偶爾會失效,原因是Monaco Editor內置的語言是延遲加載的,並且加載完後也會同樣註冊一個token解析器,所以會把我們的給覆蓋掉,詳見issuesetTokensProvider unable to override existing tokenizer

一種解決方法是去除內置的語言,這可以使用monaco-editor-webpack-plugin

安裝:

bash npm install monaco-editor-webpack-plugin -D

Vue項目配置如下:

```js // vue.config.js const MonacoWebpackPlugin = require('monaco-editor-webpack-plugin')

module.exports = { configureWebpack: { plugins: [ new MonacoWebpackPlugin({ languages: [] }) ] } } ```

languages選項用來指定要包含的語言,我們直接設為空,啥也不要。

然後修改Monaco Editor的引入方式為:

js import * as monaco from 'monaco-editor/esm/vs/editor/editor.api'

最後需要手動註冊我們需要的語言,因為所有內置語言都被去除了嘛,比如我們要使用js語言的話:

js monaco.languages.register({id: 'javascript'})

這種方法雖然可以完美解決該問題,但是很大的一個副作用是語法提示不生效了,因為只有包含了內置的htmlcsstypescript時才會去加載對應的worker文件,沒有語法提示筆者也是無法接受的,所以最後筆者使用了一種比較lowhack方式:

```js // 插件配置 new MonacoWebpackPlugin({ languages: ['css', 'html', 'javascript', 'less', 'pug', 'scss', 'typescript', 'coffee'] })

// 註釋掉語言註冊語句 // monaco.languages.register({id: 'javascript'})

// 當worker文件被加載了後再wire let hasGetAllWorkUrl = false window.MonacoEnvironment = { getWorkerUrl: function (moduleId, label) { hasGetAllWorkUrl = true if (label === 'json') { return './monaco/json.worker.bundle.js' } if (label === 'css' || label === 'scss' || label === 'less') { return './monaco/css.worker.bundle.js' } if (label === 'html' || label === 'handlebars' || label === 'razor') { return './monaco/html.worker.bundle.js' } if (label === 'typescript' || label === 'javascript') { return './monaco/ts.worker.bundle.js' } return './monaco/editor.worker.bundle.js' }, } // 循環檢測 let loop = () => { if (hasGetAllWorkUrl) { Promise.resolve().then(async () => { await wireTmGrammars(monaco, registry, grammars, editor) }) } else { setTimeout(() => { loop() }, 100) } } loop() ```

問題2

筆者遇到的另外一個問題是,轉換後有些主題的默認顏色並未設置,所以都是黑色,很醜:

image-20210924105525593.png

這個問題的解決方法是可以給主題的rules數組添加一個空的token,用來作為沒有匹配到的默認token

js { "rules": [ { "foreground": "#abb2bf", "token": "" } ] }

foreground的色值可以取colors選項裏的editor.foreground的值,要手動修改每個色值比較麻煩,可以在之前的轉換主題的步驟裏順便進行,會在下一個問題裏一起解決。

問題3

monaco-vscode-textmate-theme-converter這個包本質算是nodejs環境下的工具,所以想在純前端環境下使用不太方便,另外它對於非標準json格式的VSCode主題轉換時會報錯,因為很多主題格式是.jsonc,內容是帶有很多註釋的,所以都需要自己先進行檢查並修改,不是很方便,基於這兩個問題,筆者fork了它的代碼,然後修改並分成了兩個包,分別對應nodejs瀏覽器環境,詳見https://github.com/wanglin2/monaco-vscode-textmate-theme-converter

所以我們可以替換掉monaco-vscode-textmate-theme-converter,改成安裝筆者的:

bash npm i vscode-theme-to-monaco-theme-node -D

使用方式基本是一樣的:

```js // 只要修改引入為筆者的包即可 const converter = require('vscode-theme-to-monaco-theme-node') const path = require('path')

const run = async () => { try { await converter.convertThemeFromDir( path.resolve(__dirname, './vscodeThemes'), path.resolve(__dirname, '../public/themes') ); } catch (error) { console.log(error) } } run() ```

現在就可以直接轉換.jsonc文件,而且輸出統一為.json文件,另外內部會自動添加一個空的token作為沒有匹配到的默認token,效果如下:

image.png

最佳實踐

VSCode主題除了代碼主題外,一般還包含編輯器其他部分的主題,比如標題欄、狀態欄、側邊欄、按鈕等等,所以我們也可以在頁面應用這些樣式,達到整個頁面的主題也能隨編輯器代碼主題一起切換的效果,這樣能讓頁面整體更加協調,具體的實現上,我們可以使用CSS變量,先把頁面所有涉及到的顏色都定義成CSS變量,然後在切換主題時根據主題的colors選項裏的指定字段來更新變量即可,具體使用哪個字段來對應頁面的哪個部分可以根據實際情況來確定,VSCode主題的所有可配置項可以在theme-color這裏找到。效果如下:

2021-09-27-10-46-47.gif

總結

本文完整詳細的介紹了筆者對於Monaco Editor編輯器主題的探索,希望能給有主題定製需求的小夥伴們一點幫助,完整的代碼請參考本項目源碼:code-run

參考鏈接

文章:monaco使用vscode相關語法高亮在瀏覽器上顯示

文章:codesandbox是如何解決主題的問題

文章:閒談Monaco Editor-自定義語言之Monarch

討論:如何在Monaco Editor中使用VSC主題?

討論:使用WebAssembly來支持TextMate語法