CodeMirror中文说明文档

文档大纲

本文档并未完全翻译完成,我需要你的帮助。前往GitHub编辑

配置

CodeMirror 构造函数和 fromTextArea 函数都有配置对象参数(可选)。 没有该参数的其他函数会从 CodeMirror.defaults 属性中获取默认配置,默认配置是可修改的。

虽然所有函数都不校验配置的正确性,但如果配置错误,将会引发奇怪的异常。

所有支持的配置如下:

value: string|CodeMirror.Doc
初始内容。参数:字符串或 Document 对象。
mode: string|object
语言 Mode。
字符串:Mode 名或 Mode 的 MIME 类型。
"null":不处理代码高亮。
对象:必须含有 name 属性,可含有配置参数(如:{name: "javascript", json: true})。
Mode 的 Demo 页面提供了所支持的配置参数。
可以调用 CodeMirror.modesCodeMirror.mimeModes 来查看已成功引入的 Mode, CodeMirror.modes 返回 Mode 的构造函数,CodeMirror.mimeModes 返回 Mode 的 MIME 类型。
lineSeparator: string|null
行分割符。
字符串:文档和输出值都用该字符串分割。
"null":文档使用 CRLFs 分割(CRs+LFs),输出值使用 LF 分割 (如使用 getValue 获取值时)。
theme: string
主题样式。
"default":默认值,在 codemirror.css 中定义。
字符串:主题名,可同时使用多个主题,如 "foo bar" 表示同时使用 cm-s-foocm-s-bar
需引入含有 .cm-s-[name] 的 CSS 文件(参考 theme 目录)。
indentUnit: integer
每个缩进块由几个空格组成。默认为2。
smartIndent: boolean
应使用 Mode 提供的上下文自动缩进,还是仅保持前一行的缩进。默认为 true,使用上下文自动缩进。
tabSize: integer
Tab 的宽度。默认为 4 个英文字符。
indentWithTabs: boolean
是否将 N*tabSize 个空格替换为 N 个 Tab 来作为缩进块。默认为 false。
electricChars: boolean
在输入时,如果检测到当前的缩进有误(如果 Mode 实现了该功能),是否重新缩进该行。默认为 true。
specialChars: RegExp
正则表达式,把匹配到的字符替换为特殊占位符,一般用于不可打印字符。
默认为 /[\u0000-\u001f\u007f-\u009f\u00ad\u061c\u200b-\u200f\u2028\u2029\ufeff\ufff9-\ufffc]/
specialCharPlaceholder: function(char) → Element
specialChars 匹配到的字符,替换成 DOM 元素来占位。 默认为红色的圆点()。
direction: "ltr" | "rtl"
段落的书写方向。默认为 "ltr",从左到右。
CodeMirror 使用 Unicode 双向算法,但无法检测基础方向。
基础方向应与用户的意图保持一致,所以应让多语种用户自行切换基础方向。
rtlMoveVisually: boolean
在从右往左书写的语言中(阿拉伯语,希伯来语),光标的移动方向是虚拟的(按左键,光标向左移动)还是逻辑的(按左键,光标向前一个字符移动,在从右往左书写的语言中是向右移动)。 在 Windows 中默认为 false,在其他操作系统中默认为 true
keyMap: string
快捷键表。 默认为 "default",这是 codemirror.js 唯一定义的快捷键表。 参考 keymap 目录,和 快捷键 章节。
extraKeys: object
keyMap 基础上增加额外的快捷键。可以是 null 或有效的快捷键
configureMouse: fn(cm: CodeMirror, repeat: "single" | "double" | "triple", event: Event) → Object
控制鼠标选择和拖拽的行为。按下鼠标左键时会调用该函数,返回值可包含以下属性:
unit: "char" | "word" | "line" | "rectangle" | fn(CodeMirror, Pos) → {from: Pos, to: Pos}
选区的单位。可能是上述定义中的任意一个值,或一个参数为位置对象并返回该处的范围的函数。
默认情况下: 双击是 "word", 连点三下是 "line", 按下 Alt 并点击是 "rectangle"(Chrome OS 中是 meta-shift-clicks), 其他情况下是 "single"
extend: bool
应该扩大选区还是新建选区。默认按下 Shift 并点击时扩大(true)。
addNew: bool
应该新建选区还是替换选区。默认在 Mac OS 中按下 Command 并点击时新建(true),在其他操作系统中按下 Control 并点击时新建(true)。
moveOnDrag: bool
应该复试选区内容还是移动选区内容。默认在 Mac OS 中按下 Alt 并拖拽时复制(true),在其他操作系统中按下 Control 并拖拽时复制(true)。
lineWrapping: boolean
内容超过编辑器的宽时,应该滚动显示还是换行显示。默认为滚动(false)。
lineNumbers: boolean
是否在编辑器的左侧显示行号。
firstLineNumber: integer
行号应从几开始计数。默认为 1。
lineNumberFormatter: function(line: integer) → string
行号格式化函数。把行号数字转换为要显示字符串。
gutters: array<string | {className: string, style: ?string}>
用来添加侧边栏(除了行号侧边栏)。
参数是 CSS 样式名数组,或由 CSS 样式名及其样式组成的数组,两种都必须定义侧边栏的 width
可以为侧边栏定义背景,或引入 CodeMirror-linenumbers 样式来调整行号侧边栏的位置(默认为所有侧边栏的右侧)。
这里的 CSS 样式名也被作为 setGutterMarker 函数的参数。
fixedGutter: boolean
侧边栏应跟随内容水平滚动(false),还是在水平滚动中保持固定(true,默认)。
scrollbarStyle: string
选择一个滚动条的实现。
默认为 "native" 使用系统滚动条,"null" 时隐藏滚动条。
参考滚动条插件
coverGutterNextToScrollbar: boolean
fixedGutter 为 true 时,水平滚动条左边的侧边栏可见。 当该参数为 true 时,会使用样式名为 CodeMirror-gutter-filler 的 DOM 元素覆盖水平滚动条左边的部分侧边栏。
inputStyle: string
选择编辑器处理输入和获得焦点的方式。核心库提供 "textarea""contenteditable" 两种模式。
移动浏览器默认使用 "contenteditable",桌面浏览器默认使用 "textarea"
"contenteditable" 对 IME 和屏幕阅读器的支持比较好,未来会成为桌面浏览器的默认值。
readOnly: boolean|string
是否只读。特殊值 "nocursor" 可以禁止编辑器获得焦点。
showCursorWhenSelecting: boolean
选择时是否显示光标。默认为 false。
lineWiseCopyCut: boolean
默认为 true,在没有选区时,复制或粘贴光标行的所有内容。
pasteLinesPerSelection: boolean
默认为 true,从其他地方(非编辑器中)复制内容并粘贴到编辑器中时,如果复制内容的行数与编辑器的选区数一致,将会为每个选区分配一行内容。
selectionsMayTouch: boolean
默认为 false,两个选区在接触时合并。为 true 时,两个选区重叠时合并。
undoDepth: integer
最多可撤销次数,默认为 200。
historyEventDelay: integer
停止输入或删除多久后,创建新的历史事件。默认为 1250 微秒。
tabindex: integer
编辑器的 tab index,默认为无。
autofocus: boolean
是否自动获取焦点,默认为 false。
使用 fromTextArea 函数初始化编辑器时,如果 Textarea 已经获得焦点, 或 Textarea 有 autofocus 属性且其他元素未获得焦点时,该值为 true。
phrases: ?object
有些插件基于 phrase 函数实现翻译功能。
null :phrase 函数返回源句。
对象:含有与源句一致的键时,phrase 函数返回对应值,否则返回源句。

下面是不常用的配置,只有遇到非常具体的问题时才会用到,第一次阅读该手册时可以选择跳过。

dragDrop: boolean
是否启用拖拽,默认为 true。
allowDropFileTypes: array<string>
规定哪些文件可以拖进编辑器(默认为 null),参数是由 MIME 类型组成的数组。 编辑器会用浏览器返回的 Filetype 来确定其合法性。
cursorBlinkRate: number
光标闪烁的间隔,默认为 530 微秒,0 表示禁用闪烁,负数表示隐藏光标。
cursorScrollMargin: number
在滚动显示的文档中,光标应与可视范围的顶部或底部保持多长的距离,默认为 0(像素)。
cursorHeight: number
光标的高度,默认为 1(即行高)。
当使用比较矮的字体时,降低光标的高度(比如 0.85)可以实现更好的视觉效果。
resetSelectionOnContextMenu: boolean
在选区外点击鼠标右键时(会唤出菜单),是否把光标移动到该处。默认为 true。
workTime, workDelay: number
处理高亮工作的伪后台线程在运行 workTime 微秒后休眠 workDelay 微秒,默认为200 和 300。
pollInterval: number
间隔多久拉一次 Textarea 的值,默认为 100(微秒)。
一般情况下,输入值都可以通过输入事件来获取,但在 IME 和部分浏览器中无法捕获输入事件,所以需要从 Textarea 中拉取数据。
flattenSpans: boolean
默认为 true,把拥有相同 class 且相邻的元素合并。
这样做可以使 DOM 树变得清晰,性能也会得到提升,但在特殊情况下(比如圆角),合并会使文档的外观发生变化。
addModeClass: boolean
为 true 时,每个 Token 都会被加上以 "cm-m-" 前缀开头的 CSS 样式,代表该 Token 是由哪个 inner Mode 提供的, 比如 cm-m-xml 表示该 Token 来自 XML Mode。 默认为 false。
maxHighlightLength: number
默认为 10000(行),最多渲染行数,将剩余行渲染为普通文本来保证响应速度。
Infinity 时,渲染所有行。
viewportMargin: integer
渲染可视范围前后的多少行。
该配置会影响滚动和更新等函数的工作量,一般建议使用默认值 10。
Infinity 时,渲染所有行,可以使用浏览器的搜索功能,但在渲染大文档时会影响编辑器的性能。
spellcheck: boolean
是否启用拼写检查。
autocorrect: boolean
是否启用自动校正。
autocapitalize: boolean
是否自动转换为大写。