Googler: SyntaxHighlighter 1.5.1 中文文档

　
概览
SyntaxHighlighter 概况

介绍

SyntaxHighlighter 背后的想法是，在不依赖任何服务器端脚本的情况下，允许在页面上插入着色的代码片段。

它为谁设计？

主要的目的是在于博客。
然而，我曾经看见一些源码站点使用它，主要用来显示源代码。

它不为谁设计？

SyntaxHighlighter 不是为那些寻找有能力编辑高亮代码的。
SyntaxHighlighter 不允许你编辑源代码，它现在不允许，将来也不打算允许。

性能

SyntaxHighlighter 使用正则表达式解析文本。
它并不是非常快，实际上，它是很缓慢的。
如果你尝试高亮显示几行代码，它将不会出现问题。
尝试高亮显示 10KB 左右的文本将会失败，因为 JavaScript 会执行一个漫长的时间。

HighlightAll 函数
dp.SyntaxHighlighter.HighlightAll()。

dp.SyntaxHighlighter.HighlightAll()

这是一个全局性的函数，它将找到网页上的所有代码块并转换为高亮显示的代码块。

参数

function dp.SyntaxHighlighter.HighlightAll(name, [showGutter], [showControls], [collapseAll], [firstLine], [showColumns])

name	必须	<pre /> 和 <textarea /> 元素使用的名字
showGutter	可选	打开或关闭全部已处理代码块的边沟
showControls	可选	打开或关闭全部已处理 <pre > 元素的控制
collapseAll	可选	打开或关闭全部已处理 <pre > 元素的折叠；如果 showControls 参数为 false，该值将被忽略
firstLine	可选	允许从线数开始的地方指定第一行；如果你想举例说明代码块位于相关的文件，这是很有用的
showColumns	可选	在第一行显示行列

任何值传送给 HighlightAll 调用将会覆写相应的配置选项。

剪贴板
复制到剪贴板。

复制到剪贴板

版本 1.5 建立了“复制到剪贴板”功能，可以用于所有支持 Flash 的浏览器。
它使用了 1x1 Flash 视频来复制代码到用户的剪贴板。

启用该功能，你必须设置 ClipboardSwf 变量为本地的 clipboard.swf 文件。
这些操作必须在调用 HighlightAll 函数之前完成。

编程语言
支持的编程语言列表。

支持的编程语言

这里是一个支持的编程语言及它们的别名的列表。

编程语言	别名
C++	cpp, c, c++
C#	c#, c-sharp, csharp
CSS	css
Delphi	delphi, pascal
Java	java
Java Script	js, jscript, javascript
PHP	php
Python	py, python
Ruby	rb, ruby, rails, ror
SQL	sql
VB	vb, vb.net
XML/HTML	xml, html, xhtml, xslt

查阅用法页面以了解怎样使用别名。

特征
特征摘要

SyntaxHighlighter 特征

　　01. 100% 客户端脚本，与服务器无关
　　02. 多种编程语言的支持
　　03. 简单使用和部署，只需要复制文件和连接它们到你的模板
　　04. 多浏览器支持
　　05. 非常轻量，压缩过的核心库只有 11KB，可添加你需要的任何 Brushes

Brushes
Brushes。

它们是什么？

Brushes，是我编制的为自己的编程语言调用高亮显示脚本的条款。
SyntaxHighlighter 使用模块化的方法，由核心库 shCore.js 和许多像 shBrushXml.js、shBrushCss.js 等的组成。

它们是怎样工作的？

每个 Brush 描述了一套特殊语言的规则。
规则基于关键字、正则表达式和 CSS 样式。
大多数语言都是用同样的语法并且以同样的方式进行解析，只要你提供一些基本的规则，如解析字符串、注释等。

你可以自定义编写一个完整的 Brush 并实现你自己的解析。
例如 shBrushXml.js。
它提供了对 XML/HTML 代码的格式化，这不同于 C# 或 Java 的样式。

用法
怎样使用 SyntaxHighlighter。

放置代码

放置你的代码到页面上并被包围在 <pre /> 标签中。
设置 name 属性为 code，而 class 属性设置为你希望使用的编程语言的别名。

注意: 一个重要的事情要特别注意是开头的三角括号 <。它必须全部被替换为与 HTML 等价的 <。操作失败的话，它不会打破页面，而会打破源代码的显示。

一个替代 <pre /> 的是使用 <textarea /> 标签。
它不会出现上面 < 字符的问题。
最主要的问题是它看起来效果没有 <pre /> 标签好，因为 JavaScript 一些时候不能工作（例如在 RSS 聚合中）。

扩展配置

这里给出一种方法来传递一些配置选项给代码块。
它由冒号分隔参数。

让它工作起来

最后，要让所有东西适当的渲染在页面上，你必须给该页面添加 JavaScript 代码。

对于最理想的效果，放置这些代码在你页面的最后。
检查 HighlightAll 函数以获得更多关于功能方面的详情。

<pre /> 和 <textarea />
关于 <pre /> 和 <textarea /> 的技术详情。

问题描述

使用 <pre /> 最基本的问题是无法向里面简单地复制和粘贴代码。
特别是把这些应用在 XML/HTML。

<pre /> 的问题是，浏览器会解析它里面的 HTML 代码，而在 <textarea /> 中的代码却不会被解析。
例如：

<pre><b>Hello</b></pre>

将会渲染 Hello，就像：

<textarea><b>Hello</b></textarea>

将会渲染：

<b>Hello</b>

如果你尝试使用 innerHTML 属性从 <pre /> 中取得 HTML，它将不会像你最初提供的 HTML 文件。
然而使用 <textarea />，属性值将返回你原先提供的内容。

结论

它让我想到了最后一点。
使用 <textarea />，你可以复制和粘贴源代码而不需要任何装饰修改。

使用 <pre />，你必须确认你的源代码不会被认为是 HTML，意思是你必须替换每个开头的三角括号 < 为 HTML 编码版的 <。这足够让 <pre /> 标签良好工作。

Blogger 模式
Blogger 模式

Blogger 有一个恶劣的习惯，它会替换所有新行为 <br /> 标签，这让它不能提交代码为片段。

按照“Blogger 模式”准备的 1.5.1 版本环境，启用时需要在调用 HighlightAll() 函数之前调用 BloggerMode() 函数，如下面的例子：

dp.SyntaxHighlighter.BloggerMode();
dp.SyntaxHighlighter.HighlightAll('code');

备选方案
SyntaxHighlighter 备选方案。

客户端

　　http://dean.edwards.name/my/examples/star-light/

服务器端

　　http://qbnz.com/highlighter

痕迹
SyntaxHighlighter 在 Web 上的使用痕迹。

　　Yahoo Developer Network
　　Aptana

配置
代码块的配置选项。

配置选项

这些选项允许你单独设置文本选项。

nogutter	将不显示边沟
nocontrols	将不在顶部显示控制按钮
collapse	将去除默认的块
firstline[value]	将以 value 作为开始行计数，默认 value 是1
showcolumns	将在首行显示行列数

这些选项将一起通过别名传递，并以冒号（:）为分隔符。

官方网站：http://code.google.com/p/syntaxhighlighter/
　