CodeMirror中文说明文档

文档大纲

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

事件

CodeMirror 的大部分对象都会生成各种事件,来让客户端代码应对不同的情况。
需要用 onoff 函数来绑定或取消事件。
CodeMirror.signal(target, name, args...) 函数可以用来自定义事件,target 非 DOM 元素。

编辑器实例有以下事件,instance 参数为编辑器实例:

"change" (instance: CodeMirror, changeObj: object)
编辑器的内容发生改变时触发。
changeObj{from, to, text, removed, origin}
fromto:从哪里修改到哪里(修改前的坐标,比如 {ch:0, line:18} 表示从 19 行的行首开始修改)。
text:替换文本字符串数组(按行拆分的)。
removed:原文本字符串数组。
该事件在 operation 函数结束之前,更新 DOM 之前触发。
"changes" (instance: CodeMirror, changes: array<object>)
"change" 事件类似,但会把一个 operation 中的所有修改打包成数组。
该事件在 operation 完成后触发,应用 operation 中的修改时会生成新的 operation。
"beforeChange" (instance: CodeMirror, changeObj: object)
在应用修改前触发,可用来调整修改内容或取消修改。
changeObj
fromtotext:与 "change" 一样。
cancel():取消修改(undo 和 redo 产生的事件除外)。
update(from, to, text):调整修改内容(undo 和 redo 产生的事件除外),该函数的三个参数都是可选的。
注意!不能在 "beforeChange" 事件的处理函数中做任何影响编辑器内容的操作, 因为该事件是由编辑器底层产生的,这样做可能会使编辑器崩溃。
"cursorActivity" (instance: CodeMirror)
移动光标或选区时触发,修改编辑器内容时触发。
"keyHandled" (instance: CodeMirror, name: string, event: Event)
按键表中的按键被按下时触发。
name:捕获的按键名(如 "Ctrl-X")。
event:DOM 的 keydownkeypress 事件。
"inputRead" (instance: CodeMirror, changeObj: object)
读取到输入时触发(输入或粘贴)。
"electricInput" (instance: CodeMirror, line: integer)
当输入字符与 Mode 的 electric 匹配时触发。
"beforeSelectionChange" (instance: CodeMirror, obj: {ranges, origin, update})
移动选区前触发。
obj.ranges:由 {anchor, head} 组成的数组。
obj.origin:字符串,可选的。
obj.update:调整移动的位置。
"beforeChange" 相同,不能在该事件处理函数中修改编辑器的状态。
"viewportChange" (instance: CodeMirror, from: number, to: number)
编辑器的可视区域改变时触发(滚动、编辑等)。
fromto 是新的可视区域的开始和结束位置。
"swapDoc" (instance: CodeMirror, oldDoc: Doc)
使用 swapDoc 函数更换编辑器的内容对象时触发。
"gutterClick" (instance: CodeMirror, line: integer, gutter: string, clickEvent: Event)
点击编辑器的侧边栏时触发。
line:行号(从 0 开始)。
gutter:点击的侧边栏的 CSS 样式名。
clickEventmousedown 事件。
"gutterContextMenu" (instance: CodeMirror, line: integer, gutter: string, contextMenu: Event: Event)
在编辑器的侧边栏上点击鼠标右键时触发(菜单键)。
line:行号(从 0 开始)。
gutter:点击的侧边栏的 CSS 样式名。
contextMenucontextmenu 事件,可以使用 preventDefault 来终止对该事件的响应。
"focus" (instance: CodeMirror, event: Event)
编辑器获得焦点时触发。
"blur" (instance: CodeMirror, event: Event)
编辑器失去焦点时触发。
"scroll" (instance: CodeMirror)
滚动编辑器内容时触发。
"refresh" (instance: CodeMirror)
编辑器刷新调整大小后触发。 主要用来清除依赖于编辑器或字符数的变量。
"optionChange" (instance: CodeMirror, option: string)
setOption 函数被调用后触发。
"scrollCursorIntoView" (instance: CodeMirror, event: Event)
编辑器尝试把可视范围滚动到光标处时触发。
借助该事件可以让其他内容跟随编辑器滚动。
"update" (instance: CodeMirror)
更新 DOM 时触发。
"renderLine" (instance: CodeMirror, line: LineHandle, element: Element)
把一行的内容渲染为 DOM 时触发。
更具体的,构造 DOM 元素后,添加到文档之前时触发。
可以在该事件的处理函数中修改 DOM 元素的样式或为其绑定事件,但不能修改编辑器的状态。
"mousedown", "dblclick", "touchstart", "contextmenu", "keydown", "keypress", "keyup", "cut", "copy", "paste", "dragstart", "dragenter", "dragover", "dragleave", "drop" (instance: CodeMirror, event: Event)
这些 DOM 事件触发时触发。
可以使用 preventDefault 来终止对这些事件的响应。

内容对象(CodeMirror.Doc)有以下事件:

"change" (doc: CodeMirror.Doc, changeObj: object)
修改内容时触发。changeObj 参数与编辑器实例的 "change" 事件的参数一致。
"beforeChange" (doc: CodeMirror.Doc, change: object)
参考编辑器实例的 "beforeChange" 事件。
"cursorActivity" (doc: CodeMirror.Doc)
移动光标或改变选区时触发。
"beforeSelectionChange" (doc: CodeMirror.Doc, selection: {head, anchor})
参考编辑器实例的 "beforeSelectionChange" 事件。

行对象(例如 getLineHandle 函数的返回值)有以下事件:

"delete" ()
删除行对象时触发。
一般用来确定某行的侧边栏标记何时被删除。
"change" (line: LineHandle, changeObj: object)
修改某行的内容时触发(行对象并未被删除)。
changeObj 参数与编辑器实例的 "change" 事件的参数一致。

文本标记对象(CodeMirror.TextMarkermarkText 函数和 setBookmark 函数的返回值)有以下事件:

"beforeCursorEnter" ()
光标进入标记范围时触发。
不能在该事件的处理函数中修改编辑器的状态,但可以删除触发该事件的标记。
"clear" (from: {line, ch}, to: {line, ch})
删除标记时触发。
如果启用了 clearOnEnter ,在光标进入标记范围时触发。
调用文本标记对象的 clear() 函数触发。
注意:通过输入来删除标记时不会触发该事件,因为撤销操作可以使标记还原。
fromto 是标记的起止位置。
"hide" ()
通过输入删除标记的最后一个字符时触发。
"unhide" ()
通过输入删除标记后,又通过撤销还原标记时触发。

行内小部件对象(CodeMirror.LineWidgetaddLineWidget 函数的返回值)有以下事件:

"redraw" ()
增加新的小部件时触发。
滚出可视区域后又滚回可视区域时触发。
更新编辑器配置时触发。
所在行要求重绘时触发。