通用代碼高亮插件（SyntaxHighlighter）

時間 2019-11-12

標籤通用代碼插件 syntaxhighlighter 简体版

原文原文鏈接

博客美化：通用代碼高亮插件（SyntaxHighlighter）

=============C#.Net 篇目錄==============javascript

寫這篇博文的起源是我想把本身的博客弄的更加美觀，相信你也同樣。css

首先，我要說SyntaxHighlighter插件的實現方式及應用示例，而後再說明如何將其應用到本身的博客，使博客的代碼着色更加美觀。html

源碼: SyntaxHighlighter 示例源碼下載java

SyntaxHighlighterjquery

SyntaxHighlighter 源碼下載c#

1) Syntaxhighlighter_3.0.83 （下載點見篇頭）數組

非官方原版，作了以下調整：瀏覽器

a) 原版的demo程序存在bug，調整了demo程序（下面的貼圖是調整後的demo）。app

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配置

1、 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：

 
         SyntaxHighlighter.config.bloggerMode =  
         true 
         ; 
        
         //…… 
        
         SyntaxHighlighter.all();

2、 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：

 
         SyntaxHighlighter.defaults[ 
         'gutter' 
         ] =  
         false 
         ; 
        
 
         SyntaxHighlighter.defaults[ 
         'smart-tabs' 
         ] =  
         false 
         ; 
        
 
         //…… 
        
 
         SyntaxHighlighter.all(); 
        

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