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
是否自动转换爲大写。