寫這篇博文的起源是我想把自己的博客弄的更加美觀,相信你也一樣。
首先,我要說SyntaxHighlighter插件的實現方式及應用示例,然后再說明如何將其應用到自己的博客,使博客的代碼着色更加美觀。
SyntaxHighlighter
SyntaxHighlighter 源碼下載
1) Syntaxhighlighter_3.0.83 (下載點見篇頭)
非官方原版,做了如下調整:
a) 原版的demo程序存在bug,調整了demo程序(下面的貼圖是調整后的demo)。
b) src\shCore.js未壓縮的源代碼中缺失RegExp對象,造成只能使用scripts\ shCore.js加密混淆文件,造成調試和學習上的不便。我這里將在調試環境中解密后的RegExp對象抽出來,放入src\shCore.js使插件可正常使用(但是RegExp對象的代碼依然是壓縮過的)。
c) 原版可在官網下載,請進入……
Syntaxhighlighter插件簡介
SyntaxHighlighter(原名:dp.SyntaxHighlighter)是一套在瀏覽器上支持對各種代碼進行語法着色的獨立 JavaScript 庫。官網請進入……
下載 Syntaxhighlighter_3.0.83解壓后,里面主要文件介紹如下:
jQuery-1.4.2.js |
jQuery是一個快速、簡單的JavaScript library,它簡化了HTML 文件的traversing,事件處理、動畫、Ajax 互動,從而方便了網頁制作的快速發展。jQuery是為改變你編寫JavaScript 的方式而設計的。 |
qunit.js qunit.css |
QUnit是jQuery團隊開發的JavaScript單元測試工具,使用方便,界面美觀。它由jQuery,jQuery UI 和jQuery Mobile 項目使用,並可測試任何通用的 JavaScript 代碼,包括其本身! |
shCore.js |
SyntaxHighlighter插件的核心實現文件,根據特殊的 class 配置動態生成常規形式的 html 標簽及 class 屬性值。包含兩個主要對象:XRegExp對象和SyntaxHighlighter對象。 |
shCore.css |
控制shCore.js生成的 html 文檔的布局、字體等。(具體着色由Styles文件夾中的css主題控制,或自定義主題) |
shAutoloader.js |
提供一種簡單的參數方式,實現根據待着色代碼塊中使用的 brush 來自動根據autoloader對象配置中的隱射加載 brush.js 。 |
shLegacy.js |
|
scripts文件夾 |
包含具體語言各自的語法特性:類型、關鍵字、函數、注釋、別名等等信息,用於生成對應的html 及 class 屬性值,最后通過css主題進行着色。更多語言筆刷請進入…… |
Styles文件夾 |
提供一些現成的代碼着色css主題,可直接用於項目。 注意:(請下載上方提供的代碼,打開此文件夾)這個文件夾下的樣式文件的關系:shCore.css + shThemeDefault.css = shCoreDefault.css 演示示例:theme_tests.htm 文件 |
SyntaxHighlighter 插件配置
需要明白的3種Syntaxhighlighter配置
一、 SyntaxHighlighter.config
SyntaxHighlighter.config
為當前頁面的所有待着色代碼塊配置通用設置,這些配置不會再被單個元素設置所覆蓋。
名稱 |
默認值 |
描述 |
space |
‘ ’ |
|
useScriptTags |
true |
是否支持解析 <script type=”syntaxhighlighter” /> 標簽。 |
bloggerMode |
false |
博客模式。如果在博客網上使用該插件,因為通常博主習慣用 <br /> 替換所有的新行(’\n’),這會造成SyntaxHighlighter 插件無法拆開每一行。開啟此選項內部會將 <br /> 替換為新行’\n’ 代碼為: if (sh.config.bloggerMode == true) str = str.replace(br, '\n'); |
stringBrs |
false |
如果您的軟件會在每行末尾添加 < br / > 標記,此選項允許您忽略這些標記。 代碼為: if (sh.config.stripBrs == true) str = str.replace(br, ''); |
tagName |
‘pre’ |
可以更改解析的默認Tag。 |
strings |
|
允許改變默認的提示信息。如下圖:
|
Example:
1
2
3
|
SyntaxHighlighter.config.bloggerMode =
true
;
//……
SyntaxHighlighter.all();
|
二、 SynatxHighlighter.defaults
SyntaxHighlighter.defaults
為當前頁面待着色代碼塊配置默認設置,這些默認值可根據待着色代碼塊的 class 屬性設置進行覆蓋。
名稱 |
默認值 |
描述 |
‘class-name’ |
‘’ |
將額外的css類添加到當前元素進行特殊樣式展現。這個做為 style 屬性的值,權級高,可覆蓋如樣式文件中定義的樣式。 |
‘first-line’ |
1 |
設定行號的起始數值。 |
‘pad-line-numbers’ |
false |
標識行號至少幾位數去顯示。 可接受:數值;若為true|false 則true代表至少2位,false則至少1位。 Eg:
|
‘highlight’ |
null |
標記重要行,讓它們高亮顯示。多行之間用逗號“,”分割。 |
‘title’ |
null |
設置顯示在被着色代碼塊上方的Title。 |
‘smart-tabs’ |
true |
設置是否支持智能縮進。確保你的代碼格式發布到網頁顯示后不會因空格或縮進造成變形。 |
‘tab-size’ |
4 |
自定義 Tab 的輸入寬度。 |
‘gutter’ |
true |
設置是否在代碼前面顯示行號。 |
‘toolbar’ |
true |
設置是否顯示工具欄。 |
‘quick-code’ |
true |
設置是否啟用“雙擊”快速代碼復制和粘貼。 |
‘collapse’ |
collapse |
標識是否在頁面加載時默認將代碼折疊起來,在博文中代碼篇幅較大時此設置非常有用。 |
‘auto-links’ |
true |
標識是否開啟將代碼中的超鏈接文字套上<a>標簽,即可以直接點擊鏈接 |
‘light’ |
false |
該屬性用來控制是否開啟輕量模式。開啟輕量模式等同於gutter = false + toolbar = false。 |
‘html-script’ |
false |
標識是否開啟 HTML/XML 標簽着色特性。(必須載入 xml 的筆刷 shBrushXml.js) |
Example:
1
2
3
4
|
SyntaxHighlighter.defaults[
'gutter'
] =
false
;
SyntaxHighlighter.defaults[
'smart-tabs'
] =
false
;
//……
SyntaxHighlighter.all();
|
三、 Parameters
Parameters 允許你根據自己的喜好定制單個節點(eg:<pre />)的SyntaxHighlighter解析規則。通過設置節點的 class 特性的屬性值為特殊的鍵值對實現。
通過這種方式,你可以改變 SyntaxHighlighter.defaults
中設置的默認值。
Example:
<pre class="brush: js; ruler: true; first-line: 10; highlight: [2, 4, 6]">...</pre>
更多參數實例請查看文件:syntaxhighlighter_tests.html
SyntaxHighlighter 如何使用
使用步驟
1. 頁面中引入shCore.js 和 shCore.css 核心文件。
2. 頁面中引入需要代碼着色對應語言的筆刷腳本文件(brush.js)。
a) 現成的各種筆刷腳本文件下載,請進入……
b) 如何創建自定義筆刷文件,請進入…… (模式挺簡單的,拿現成的筆刷文件改改就好)
3. 頁面中引入代碼着色主題色樣式文件(eg:shThemeDefault.css)。
4. 創建<pre />或<script />節點包裹要進行代碼着色的代碼片段,該創建節點必須含有一個特殊格式的 class 屬性,eg:<pre class="brush: js">……</pre>
5. 調用 SyntaxHighlighter.all() 開始解析<pre />或<script />節點。
<pre /> 方式(推薦方式)
優勢:使用此方式時,如果存在腳本錯誤,則會以常規的 <pre /> 解析並顯示在所有RSS閱讀器中。
問題:所有的右尖括號必須進行HTML轉義(escape),即: < 必須替換為 < 才能確保正確解析。(注意,如果此處沒有進行轉義,那么后面的html標簽都變成字符串)
運作:Syntaxhighlighter 搜尋 <pre /> 標簽,這個標簽需滿足條件:攜帶一個特殊格式的 class 特性,值的格式類似CSS,並且該值必須包含brush(筆刷)參數。
<script /> 方式
優勢:將代碼放置在CDATA節點內部,無需再進行任何轉義(PS:<pre /> 需將 < 轉義為 < ),所以這種方式允許你直接使用從別的編輯器 “復制並粘貼” 來的代碼。
問題:
1) <script /> 標簽無法在RSS閱讀器中使用,所以如果你在 blog 上使用 SyntaxHighlighter 插件,那么使用 <pre /> 方式更加有益。
2) 如果包裹的代碼塊中包含一個結束標簽(eg,</script>),甚至內置在 CDATA 塊中,大多數瀏覽器也無法正確解析 <script type="syntaxhighlighter"> 。
運作:Syntaxhighlighter 搜尋 <script type="syntaxhighlighter"> 標簽,這個標簽需滿足條件:攜帶一個特殊格式的 class 特性,值的格式類似CSS,該值必須包含brush(筆刷)參數,並且代碼塊內嵌在 <![CDATA[code]]> 中。
此處截圖展示 <pre> 轉義的問題
更多兩種方式的比較請查看文件:how_to_use_syntaxhighlighter.html
關於CDATA
CDATA 指的是不應由 XML 解析器進行解析的文本數據(Unparsed Character Data)。
1) 在 XML 元素中,"<" 和 "&" 是非法的。"<" 會產生錯誤,因為解析器會把該字符解釋為新元素的開始。"&" 也會產生錯誤,因為解析器會把該字符解釋為字符實體的開始。某些文本,比如 JavaScript 代碼,包含大量 "<" 或 "&" 字符。為了避免錯誤,可以將腳本代碼定義為 CDATA。
2) CDATA 部分中的所有內容都會被解析器忽略。
3) CDATA 部分由 "<![CDATA[" 開始,由 "]]>" 結束。
4) CDATA 部分不能包含字符串 "]]>"。也不允許嵌套的 CDATA 部分。
5) 標記 CDATA 部分結尾的 "]]>" 不能包含空格或折行。
更多關於CDATA的資料可以查看:javascript CDATA的意義 和 XML CDATA (w3school) 。
核心對象 SyntaxHighlighter 代碼實現
把 SyntaxHighlighter 代碼實現放到“后面節”,是考慮到大家在了解上面的配置和使用后再看這一節會更加有效果。(也避免了我言不達意)
SyntaxHighlighter 插件的核心代碼在 shCore.js 文件中,內部主要包含了 SyntaxHighlighter對象(和 XRegExp 對象,XRegExp在官方下載的源碼中找不到,可能官方漏了,我這邊將博客園中的 XRegExp 對象代碼拷貝到了 shCore.js 文件中)。
SyntaxHighlighter啟動前
在 SyntaxHighlighter 啟動前,我們可以選擇性對defaults 和config 進行配置,但是必須在確保在啟動前將相應的 brush.js 引入到當前頁面,否則啟動是會報找不到 brush 的錯誤(config.strings.noBrush)。
brush.js 文件做了什么呢?讓brush繼承自 SyntaxHighlighter.Highlighter() 對象並且將 brush 添加到 SyntaxHighlighter.brushes 對象中。
關鍵代碼:
Brush.prototype = new SyntaxHighlighter.Highlighter(); SyntaxHighlighter.brushes.CSharp = Brush;
SyntaxHighlighter 啟動:
1) SyntaxHighlighter.highlight(globalParams,element) highlight 可接受默認參數選項和指定節點進行着色。(element 放空,則為對所有匹配元素進行着色)
2) SyntaxHighlighter.all(params) 將啟動時機綁定到 load 事件,可接受默認參數選項,對所有匹配元素進行着色。
3) 我們在查看 demo 文件:syntaxhighlighter_tests.html 時,你會發現 012_server_side 節中使用了非封裝的上面兩個方法,而是如下調用:
$sh = $('#sh_012_server_side_output'); // 查找待着色代碼塊 var brush = new SyntaxHighlighter.brushes.JScript(); // 創建brush brush.init({ toolbar: false }); // 初始化參數選項 $sh.html(brush.getHtml(code)); // getGtml 為插件解析核心方法
或許第三種方法你不是很明白,但我相信你看了下面我整理的流程圖后就明白了。
SyntaxHighlighter 運作流程圖
具體應用見上面提供的 demo 源代碼。
最后生成的 html 標簽及其 class 特性類似下圖:
版本 3 新增的 shAutiloader.js 腳本文件
SyntaxHighlighter着色過程中,針對不同的語言需要根據適合的腳本刷子來着色,這樣造成你在頁面上不得不預先加載所有可能的用到的 brush.js 。 shAutiloader.js 正是為解決此問題而生,它會根據待着色代碼塊所使用到的筆刷配置來動態創建<script>節點以加載適合的JavaScript文件,不會造成載入多余資源的浪費。
使用方式:只需在頁面中引入 shAutoloader.js 腳本文件,將所有筆刷在 autoloader 對象中配置好,再調用SyntaxHighlighter.all(params)方法。
注意:使用shAutiloader.js必須調用 SyntaxHighlighter.all(params) 來啟用着色插件,shAutiloader.js內部重寫了SyntaxHighlighter插件的 all(params) 方法,以此確保所有被使用到的筆刷都已經動態創建好 script 節點。
API
SyntaxHighlighter.autoloader(brushes)
brushes 參數是數組,格式如下:
Array: [ 'alias1 alias2 /full/path/to/brush.js', ... ] 一維數組,元素內部用空格分隔,最后一部分為 JavaScript 文件路徑。
Array: [ [ 'alias1', 'alias2', '/full/path/to/brush.js' ], ... ] 多維數組,每一維的最后一個元素為JavaScript 文件路徑。
Example:(詳細見示例代碼:shAutoloader_tests.html)
SyntaxHighlighter.autoloader.apply(null, path( 'css /pub/sh/current/scripts/shBrushCss.js', 'actionscript3 as3 /pub/sh/current/scripts/shBrushAS3.js', 'c# c-sharp csharp /pub/sh/current/scripts/shBrushCSharp.js', //…… )); SyntaxHighlighter.all();
shLegacy.js腳本文件介紹
這個文件只是提供了快速設置:TagName,‘gutter’,‘toolbar’,‘collapse’,‘first-line’ 參數選項,需要使用: dp.SyntaxHighlighter.HighlightAll(params); 來啟動,用處不是很大,在目前3.0.83版已經沒有更新了,所以3.0.83版的一些設置這里面不支持。有興趣的朋友可以自己看下,源碼包含此文件。
SyntaxHighlighter插件內容總算被扯完了,下面說說博客園中此插件的使用。
博客園
博客園內置支持SyntaxHighlighter代碼着色,使用此內置着色特性需要將博客的默認編輯器改為TinyMCE(“管理”-“選項”中設置)。如果使用CuteEditor,CuteEditor會自動去除代碼中的空格,造成代碼格式破壞。
安裝:Windows Live Writer推薦SyntaxHighlighter代碼着色插件
(這個連接下載的是很久遠的 SyntaxHighlighter 插件版本(,但是提供了下面可視化的插件),並非上面說的 Syntaxhighlighter_3.0.83 版本(注意:目前博客園使用的新版本的js插件庫,只是可視化插件還停留在老版本),不過大體類似,實際上我還萌生了看有沒有辦法升級此插件的辦法,看來只得后面再分享了。月底了,不想這個月無一分享,急啊,所以就先整舊版的使用,分享下)
一段經歷:實際上我早在安裝好Windows Live Writer后就已經安裝了SyntaxHighlighter插件,但是一直沒有用上,因為這款插件在本地Windows Live Writer編輯器中是沒有效果的……(我以為沒有作用)沒文化,真可怕。直到近期我才發現這插件的作用是要發布到博客園后才有效果(因為他需要運行SyntaxHighlighter插件的js腳本)……下面我來說說為博客圓提供的這款可視化插件如何配置。
按照上面鏈接文章安裝后,可通過Windows Live Writer的“插入”菜單使用,第一次使用此插件時會報讀取不到配置文件,這個不影響程序使用,你只需點 Options 按鈕在彈出框中配置完點OK就會創建該配置文件(如下圖),保存在C:\Users\…\AppData\Roaming\Windows Live Writer\WindowsLiveWriter.SourceCode.config中(WindowsLiveWriter.SourceCode.config實際上是內部 PluginConfigurationData 對象的 XML序列化結果)。
根據上圖數字標識順序進行配置說明:
1. AutoLinks
publicboolAutoLinks { get; set; }
標識是否開啟將代碼中的超鏈接文字套上<a>標簽,即可以直接點擊鏈接。
2. Collapse
publicbool Collapse { get; set; }
標識是否在頁面加載時默認將代碼折疊起來,在博文中代碼篇幅較大時此設置非常有用。
3. Gutter
publicbool Gutter { get; set; }
標識是否在代碼前面顯示行號
4. HtmlScript
publicboolHtmlScript { get; set; }
標識是否開啟 HTML/XML 標簽着色特性。(必須載入 xml 的筆刷 shBrushXml.js)
5. Light
publicbool Light { get; set; }
該屬性用來控制是否開啟輕量模式。開啟輕量模式等同於,gutter: false 和 toolbar: false。
6. Ruler
publicbool Ruler { get; set; }
在代碼上方增加一行用於標注代碼所使用的列行數,博客園屏蔽了這個屬性,也就是說如果你在博客園的文章中使用這個屬性是沒有任何效果的。
效果:
7. SmartTabs
publicboolSmartTabs { get; set; }
標識是否啟動智能縮進,確保你的代碼格式發布到網頁顯示后不會因空格或縮進造成變形。
8. Toolbar
publicbool Toolbar { get; set; }
該屬性用來控制是否在代碼塊的右上角顯示浮動工具欄。
9. LoadFromClipboard
publicboolLoadFromClipboard { get; set; }
標識在打開SyntaxHighlighter插件編輯框時,是否默認把剪貼板上得內容復制到編輯框中。
10. TabSize
publicintTabSize { get; set; }
自定義 Tab 的輸入寬度。
11. ClassName
public string ClassName { get; set; }
將額外的css類添加到當前元素進行特殊樣式展現。這個做為 style 屬性的值,權級高,可覆蓋如樣式文件中定義的樣式。
12. Brush
public string Brush { get; set; }
指定程序語言,以此來決定代碼着色規則。Eg:C#、C++、CSS、JavaScript、Java、PHP、XML/HTML、VB、SQL、Python、Ruby、Delphi……(必須設置的特性值)
13. FirstLine
publicintFirstLine { get; set; }
指定行號的起始數值。
14. Highlight
public string Highlight { get; set; }
標記重要行,讓它們高亮顯示。多行之間用逗號“,”分割。