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


#1

第二章 主题风格(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的
样式继承规则等,会帮助你更好地设计这些显示风格。


#2

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


#3

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.