通用代碼高亮插件(SyntaxHighlighter)


寫這篇博文的起源是我想把自己的博客弄的更加美觀,相信你也一樣。

         首先,我要說SyntaxHighlighter插件的實現方式及應用示例,然后再說明如何將其應用到自己的博客,使博客的代碼着色更加美觀。

 

源碼: 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),即: < 必須替換為 &lt; 才能確保正確解析。(注意,如果此處沒有進行轉義,那么后面的html標簽都變成字符串)

運作:Syntaxhighlighter 搜尋 <pre /> 標簽,這個標簽需滿足條件:攜帶一個特殊格式的 class 特性,值的格式類似CSS,並且該值必須包含brush(筆刷)參數。

 

<script /> 方式

優勢:將代碼放置在CDATA節點內部,無需再進行任何轉義(PS:<pre /> 需將 < 轉義為 &lt; ),所以這種方式允許你直接使用從別的編輯器 “復制並粘貼” 來的代碼。

問題:

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; }

標記重要行,讓它們高亮顯示。多行之間用逗號“,”分割。


免責聲明!

本站轉載的文章為個人學習借鑒使用,本站對版權不負任何法律責任。如果侵犯了您的隱私權益,請聯系本站郵箱yoyou2525@163.com刪除。



 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM