User manual in Chinese(2)基本外观设置

第二章 主题风格(theme and style)

作为一名开发人员,一定要明白一件事,在软件编程方面,我们能获取的文档有两种:

  1. 条理清晰,但是破碎不堪,晦涩难懂,如字典般,用哪查哪。
    如:javadoc、很多软件的官方指南的参数说明部分(包括CodeMirror的官方用户指南的多数章节)。

  2. 从应用角度出发,逻辑清晰,跟着学就能成功。这类文档,通常称之为教程。

我写的这系列文章,与上述两种文档,也有很多不同。本教程不会详细介绍所有的参数选项(想知道所有参数请查阅官方手册),也不会太过详细介绍软件的使用细节。而是着重于引发读者的思考。在展示基本用法的基础上,鼓励读者自己去尝试和探索软件的使用、去优化和改造自己的程序。

艺术家,其实只是艺术的第一个接触者,当作品被创造出来之后,这件作品到底蕴含了什么,就不是创造他的艺术家能说了算的了。
一个软件的功能是有限的,一篇教程的内容是有限的,而人的想象力和创造力是无限的。希望你能在CodeMirror学到的东西比我们能给你的更多。

一、主题风格

在CodeMirror的初始化配置里面,有这样一个选项:

theme: string
这个选项配置了编辑器所使用的主题。

1.加载主题文件

在theme文件夹下,随便选一个css文件,如rubyblue.css,加载进来。

<link rel="stylesheet" href="/CodeMirrorTest/css/rubyblue.css">

现在我们就可以把theme选项设置为rubyblue了。编辑器会显示一些特定的颜色。

var myCodeMirror = CodeMirror.fromTextArea(myTextarea,{theme:"rubyblue"});

原理是什么?打开这个css文件,可以看到.cm-s-rubyblue这样的写法。也就是说,你所配置的主题
名称,必须保证.cm-s-[name]这样的css样式已经被加载进来。只要有这样的样式你就可以配置相应的主题。样式写在哪里是你的自由,但是我们最
好像官方示例这样,一个主题一个css文件。

官方提供的主题,都在theme文件夹里面。如果你想实现自己的主题,照猫画虎就可以了。

我们也可以同时使用多个主题,毕竟css样式的class是可以同时存在的。如theme:“foo bar”

2.默认主题

如果不配置theme,会怎样?这个选项的值会是“default”。那么.cm-s-default的颜色配置在哪里?在和codemirror.js同目录的lib目录下。
名称为:codemirror.css

3.自定义样式

如何实现自定义主题呢?想要使各种元素显示我们定义的颜色。只需要像上面提到的,提供对应名称的样式就可以了。
但是,css能控制的可不只是颜色,还有宽高等其它信息。这些信息在theme下面的css文件中是没有的,因为theme只控制显示的颜色风格。
而编辑器的其它样式,在codemirror.css中定义。

a.

下面,翻译一下官方说明,告诉你哪些css样式是控制什么的:

    对codemirror.css中有关编辑器外观的样式的解释
    CodeMirror
        这是编辑器最外层的div的class。因此,这里设置整个编辑器的宽高和位置、边框等,或者为编辑器设置背景。
        在这里设置的一些东西也会被应用到它的子元素上,所以,适合在这里设置全局的字体、字号等。
        如果将高度设置为auto,将会使编辑器适应其内容。如果这样做,也推荐同时设置viewportMargin为Infinity。
    CodeMirror-gutters
        这是所有槽的最外层div,所有槽都包括在这里面。可以用它给整个槽设置背景颜色。也可以通过它给槽设置右边框。 
    CodeMirror-linenumbers
        使用这个来给“行号槽”设置宽度和背景颜色。
    CodeMirror-linenumber
        用这个来控制特定行号槽的样式。这个样式是会覆盖上面的CodeMirror-linenumbers的, 可以用它来设置对齐和文本属性.
    CodeMirror-lines
        可见的行,这个样式用来控制行与行中间的间隙。
        
    CodeMirror-focused
        当编辑器获得焦点,顶层元素就会获得这个class
    CodeMirror-selected
        选中的内容会被span包裹,并且span会带有这个class.
        
    CodeMirror-cursor
        控制光标的显示方式,光标使用绝对定位来指示位置。
    CodeMirror-matchingbracket, CodeMirror-nonmatchingbracket
        控制匹配成对的括号和没有成对的括号的样式。
b.

上面提到的关于行号和关于槽的class,需要开启行号才行。我们顺便回头学几个配置,这几个配置和我们本章的theme是同级别的配置:

CodeMirror的一些显示相关的配置项
var myCodeMirror = CodeMirror.fromTextArea(myTextarea,{
theme:"rubyblue",
lineNumbers:true,
firstLineNumber:1,
lineNumberFormatter: function(line: integer) → string,
gutters: array<string>,
fixedGutter: boolean
});

lineNumbers: boolean
    这个选项配置了是否开启显示行号。
firstLineNumber: integer
    这个选项配置了,行号从数字几开始。
lineNumberFormatter: function(line: integer) → string
    这个选项配置了一个函数,传入一个行号数字,返回格式化后的字符串。也就是说,行号不一定是数字行号,也可以是任意字符串。
gutters: array<string>
    这个选项是一个css的class名称的数组,每一个都定义了宽度和背景(由于外层的槽的宽度固定,所以这个宽度最好用百分比。
    背景是可选的),也可以把前面提到的CodeMirror-linenumbers这样式包含进来,这样就显式指定了行号样式的位置,如果不
    显式指定,行号样式是放在最右侧的。
    
    这些样式会在行号样式之前,或者取代行号样式的位置。最终效果类似于:
    设置为:gutters:["aa","bb"]
    <div class="CodeMirror-gutters" style="height: 36px;">//这是行号槽
        <div class="CodeMirror-gutter aa">//这是第一个样式
        </div><div class="CodeMirror-gutter bb">//这是第二个样式
        </div><div class="CodeMirror-gutter CodeMirror-linenumbers" style="width: 35px;"></div>这是行号样式
    </div>
fixedGutter: boolean
    当编辑器左右滚动时,行号槽固定不动还是随着内容滚动。
scrollbarStyle: string
    当默认是"native",使用浏览器的滚动条,可以设置为“null”,不显示滚动条。通过插件,可以实现其他类型的滚动条。
coverGutterNextToScrollbar: boolean
    当水平方向出现滚动条,而行号槽又是设置为固定不动,那么必然面临一个问题:一个水平条和一个垂直条的交点处,谁该显示在上面?
    默认设置是行号槽会显示在滚动条左侧,也就是设置为false。如果将选项设置为true,那么会有一个带有CodeMirror-gutter-filler的
    样式的div覆盖在交叉点。总之,无论如何滚动条都不会延伸到交叉区域。
showCursorWhenSelecting: boolean
    当一段文字被选中,光标是否显示。默认fanlse。
autofocus: boolean
    刚初始化的时候,编辑器是否具有焦点。默认为false。

虽然上面详细介绍了各种配置和样式是怎么控制行号、光标、焦点、选中项、滚动条的显示的。但是为了真正了解其实际情况。你最好还是通过浏览器查看dom元素,
来观察这些元素和样式是怎么应用和变化的。

请使用浏览器的查看元素功能,定位到编辑器节点。你会看到,编辑器由很多的div来实现,样式由div的class来控制,因此,你所熟知的css的
样式继承规则等,会帮助你更好地设计这些显示风格。

Nice! But could you keep these in a single topic to avoid producing too much noise for people subscribed to the forum?

Sure.I’am worrying about that,too.I will put other articles into the first one I’ve published and change the title of it.

I like the CodeMirror very much,it’s my honor to do something for it.