User:Remember the dot/Syntax highlighter/zh

Languages:

English • català • Deutsch • español • français • Ido • українська • 中文

我制作了这个高亮语法的脚本。和wikEd、AceWikiEditor和CodeMirror等语法高亮脚本不同，这款脚本：

在输入时即时自动高亮更新；
不会影响撤销和还原按键；
不会干扰拼写检查；
和大多编辑框相关脚本兼容。

安装

请在安装脚本前，先阅读下面的“已知问题”章节。

致wiki上已安装该脚本的终端用户

若你wiki的小工具中有语法高亮选项，则在参数设置里启用即可。

致wiki上未安装该脚本的终端用户

如果wiki上没有安装小工具，请在你的common.js页加入以下代码：

//syntax highlighter
mw.loader.load('//www.mediawiki.org/w/index.php?title=MediaWiki:Gadget-DotsSyntaxHighlighter.js&action=raw&ctype=text/javascript');

举个例子，若中文维基百科未提供语法高亮小工具，你应当把代码加在

https://zh.wikipedia.org/wiki/User:Your_Username/common.js

致维基媒体站台管理员

在贵维基创建MediaWiki:Gadget-DotsSyntaxHighlighter.js页面，并加入下列代码：

mw.loader.load('//www.mediawiki.org/w/index.php?title=MediaWiki:Gadget-DotsSyntaxHighlighter.js&action=raw&ctype=text/javascript');

接着前往MediaWiki:Gadgets-definition新增一行

*DotsSyntaxHighlighter[ResourceLoader]|DotsSyntaxHighlighter.js

然后创建MediaWiki:Gadget-DotsSyntaxHighlighter页面，并输入

[[mw:User:Remember the dot/Syntax highlighter|语法高亮]]：高亮编辑框中的维基语法。

致非维基媒体网站管理员

在贵wiki创建页面MediaWiki:Gadget-DotsSyntaxHighlighter.js，将User:Remember the dot/Syntax highlighter.js的源代码复制进去。接着在MediaWiki:Gadgets-definition新起一行写上

*DotsSyntaxHighlighter[ResourceLoader]|DotsSyntaxHighlighter.js

并创建页面MediaWiki:Gadget-DotsSyntaxHighlighter输入下列文字

[https://www.mediawiki.org/wiki/User:Remember_the_dot/Syntax_highlighter 语法高亮]：高亮编辑框中的维基语法。

MediaWiki 1.22 or later is required.

已知问题

兼容性

高亮工具在最新版Firefox上运行效果最佳。
高亮工具在最新版Chrome、Safari和Opera上基本能够运行，但对zh:泰文和藏文等文字未必能正确运行。
高亮工具不支持Internet Explorer（错误太严重）。若使用Internet Explorer，该脚本会拒绝执行。
该脚本和某些编辑框相关脚本不兼容。

解析

考量到性能，该高亮工具要求所有标签符合XML规范。比如以开始的标签必须用关闭，要写 而非 。
考量到性能，高亮语法不处理'''撇号接斜体''与''斜体撇号'''——它们会视作无效语法。我推荐用'撇号接斜体与斜体撇号'表示。
由在段首放置一个空格产生的<pre>标签不会高亮。这是因为该高亮工具还没有智能到可以判断这个空格是否是用于模板中的一个普通的空格。
__NOTOC__等行为开关不会高亮。
由{{fullurl:}}与模板生成的外部链接不会高亮。所见效果为[{{fullurl:My page}} 外部链接]而非[{{fullurl:My page}} 外部链接].

杂项

高亮工具在长页面中效果不佳，若延时超过50ms会自动禁用。If this happens, a message appears explaining what happened and suggesting how to work around it or increase the timeout.
高亮工具在上传文件时不会运行。
高亮工具可能会盖掉您的编辑框用户样式。

自定义

配色

修改或禁用语法高亮配色的方法很简单。以下语法可以自定义颜色：

defaultColor	用于没有识别出定义了特殊颜色的语法元素
boldOrItalicColor	`'''bold'''` `''italic''`
wikilinkColor	`[[wikilink]]`
externalLinkColor	`[http:// named external link]`, `[http://numbered-external-link.com]`, `http://bare-external-link.com`
headingColor	`==Heading==`, `;Small heading`
listOrIndentColor	`* unordered list`, `# ordered list`, `: indent`
signatureColor	`~~~~`
tableColor	`{\| table \|}`
templateColor	`{{template}}`
parameterColor	`{{{template parameter}}}`
hrColor	`----`
tagColor	`<tag>...</tag>`, `<tag/>`
commentColor	`<!-- comment -->`
entityColor	`&entity;`

比如将维基链接和外部链接改为青色与橙色，可将下列代码加入您的用户页（若你通过小工具安装高亮工具，则不用加入前两行）：

//syntax highlighter
mw.loader.load('//www.mediawiki.org/w/index.php?title=MediaWiki:Gadget-DotsSyntaxHighlighter.js&action=raw&ctype=text/javascript');

syntaxHighlighterConfig = {
    externalLinkColor: "#FFCC66", //orange
    wikilinkColor: "#E6FFFF", //cyan
}

若要将某条高亮语法禁用，请将颜色设为""。如禁用外部链接高亮就是：

//syntax highlighter
mw.loader.load('//www.mediawiki.org/w/index.php?title=MediaWiki:Gadget-DotsSyntaxHighlighter.js&action=raw&ctype=text/javascript');

syntaxHighlighterConfig = {
    externalLinkColor: "",
}

To not highlight any syntax except those you explicitly want, set defaultColor to "" and set the color of each syntax you want to highlight. If you just want the usual color, set the color to "normal". For example, to only highlight tags:

//syntax highlighter
mw.loader.load('//www.mediawiki.org/w/index.php?title=MediaWiki:Gadget-DotsSyntaxHighlighter.js&action=raw&ctype=text/javascript');

syntaxHighlighterConfig = {
    defaultColor: "",
    tagColor: "normal",
}

Timeout

You can specify a timeout that replaces the default 20ms timeout. For example, if you're OK with sluggishness as you type and you want to disable highlighting only if it takes more than 30ms, put the following in your common.js:

//syntax highlighter
mw.loader.load('//www.mediawiki.org/w/index.php?title=MediaWiki:Gadget-DotsSyntaxHighlighter.js&action=raw&ctype=text/javascript');

syntaxHighlighterConfig = {
    timeout: 30,
}

If you installed the highlighter as a gadget, omit the first two lines.

Non-wikitext tags

Several tags, such as <math> and <source>, do not use wikitext and consequently, no syntax is highlighted inside of these tags. You can customize the list of source-like tags by setting sourceTags to an array of tag names. For example, to disable syntax highlighting within the hypothetical <foo> tag in addition to the defaults, put the following in your common.js:

//syntax highlighter
mw.loader.load('//www.mediawiki.org/w/index.php?title=MediaWiki:Gadget-DotsSyntaxHighlighter.js&action=raw&ctype=text/javascript');

syntaxHighlighterConfig = {
    sourceTags: ["math", "syntaxhighlight", "source", "timeline", "hiero", "foo"],
}

Other tags, such as <pre> and <nowiki>, do not use wikitext but do process character entities (  for example). The list of nowiki-like tags is controlled by the nowikiTags property. For example, to highlight only character entities within the <abbr> tag, put the following in your common.js:

//syntax highlighter
mw.loader.load('//www.mediawiki.org/w/index.php?title=MediaWiki:Gadget-DotsSyntaxHighlighter.js&action=raw&ctype=text/javascript');

syntaxHighlighterConfig = {
    nowikiTags: ["nowiki", "pre", "abbr"],
}

In both examples, if you installed the highlighter as a gadget, omit the first two lines.

Site defaults

All properties that can be specified in the syntaxHighlighterConfig variable can also be specified in the syntaxHighlighterSiteConfig variable. syntaxHighlighterSiteConfig is intended for site defaults and syntaxHighlighterConfig for user preferences. Properties of syntaxHighlighterConfig take precendence over properties of syntaxHighlighterSiteConfig, and properties of syntaxHighlighterSiteConfig take precedence over builtin defaults.

For example, if your site does not have any MediaWiki extensions installed, you might want to remove support for source-like tags. To do so, add the following to the end of MediaWiki:Gadget-DotsSyntaxHighlighter‎:

syntaxHighlighterSiteConfig = {
    sourceTags: [],
}

Reporting bugs

Note: Remember to check whether the bug you want to report is already a known issue.

When reporting bugs to me, please include:

A detailed description of the problem.
A link to a page where the bug is visible, or a sample of wikitext that triggers the problem.
Your browser's User-Agent information.
The MediaWiki skin you use.
A list of gadgets you have enabled.
A list of any custom JavaScript or CSS you have enabled.
A list of any browser extensions you have enabled.

Source code

To reduce download time and because the ResourceLoader does not automatically minify scripts imported from other wikis, MediaWiki:Gadget-DotsSyntaxHighlighter.js itself is kept in minified form. The actual source code is available at User:Remember the dot/Syntax highlighter.js.

Overview of approach

This script creates a background div, named wpTextbox0, that is inserted behind wpTextbox1, the editing textbox. wpTextbox0 and wpTextbox1 are synchronized in style, and the background of wpTextbox1 is made transparent so that wpTextbox0 shows through. Then, blocks of text are added to wpTextbox0 as span elements. The text on the blocks is transparent, but the backgrounds of the blocks are colored. By using the same text in wpTextbox0 as wpTextbox1, any positioning anomalies from dynamically composed characters are eliminated. Because wpTextbox0 and wpTextbox1 are (theoretically) perfectly synchronized, the colored backgrounds appear to the user as though they have been added directly to wpTextbox1.

The text in wpTextbox0 is not actually added to the textContents of the span elements. Instead, it is added to the :before and :after pseudo-elements of each span using a dynamically generated CSS stylesheet. This avoids problems when trying to use the browser's find-in-page feature, because if textContent were used instead of CSS content, the browser would perceive both the real text in wpTextbox1 and the transparent text in wpTextbox0 to be on the page.