Ace editor中文文档

介绍

Ace是一个用JavaScript编写的可嵌入代码编辑器。它与Sublime，Vim和TextMate等本地编辑器的功能和性能相匹配。它可以轻松地嵌入任何网页和JavaScript应用程序中。

官网地址：Ace - The High Performance Code Editor for the Web
Github: GitHub - ajaxorg/ace: Ace (Ajax.org Cloud9 Editor)
vue2版：GitHub - chairuosen/vue2-ace-editor
vue3版：GitHub - CarterLi/vue3-ace-editor

快速开始

简单使用

<div id="editor" style="height: 500px; width: 500px">some text</div>
<script src="src/ace.js" type="text/javascript" charset="utf-8"></script>
<script>
    var editor = ace.edit("editor");
</script>

设置主题和语言模式

要更改主题，请为编辑器配置要使用的主题路径。主题文件将按需加载：

editor.setTheme("ace/theme/twilight");

默认情况下，编辑器为纯文本模式。但是，所有其他语言模式都可以作为单独的模块使用。语言模式也将按需加载：

editor.session.setMode("ace/mode/javascript");

编辑器状态

Ace将所有编辑器状态（选择，滚动位置等）保留在editor.session中, 这对于制作可切换式编辑器非常有用：

var EditSession = require("ace/edit_session").EditSession
var js = new EditSession("some js code")
var css = new EditSession(["some", "css", "code here"])
// 要将文档加载到编辑器中，只需这样调用
editor.setSession(js)

在项目中配置Ace

// 将代码模式配置到ace选项
ace.edit(element, {
    mode: "ace/mode/javascript",
    selectionStyle: "text"
})

// 使用setOptions方法一次设置多个选项
editor.setOptions({
    autoScrollEditorIntoView: true,
    copyWithEmptySelection: true,
});

// 单独设置setOptions方法
editor.setOption("mergeUndoDeltas", "always");

// 一些选项也直接设置，例如：
editor.setTheme(...)

// 获取选项设置值
editor.getOption("optionName");

// 核心Ace组件包括（editor, session, renderer, mouseHandler）
setOption(optionName, optionValue)
setOptions({
    optionName : optionValue
})
getOption(optionName)
getOptions()

设置和获取内容：`

editor.setValue("the new text here"); // 或 session.setValue
editor.getValue(); // 或 session.getValue

获取选定的文本：

editor.session.getTextRange(editor.getSelectionRange());

在光标处插入：

editor.insert("Something cool");

获取当前光标所在的行和列：

editor.selection.getCursor();

转到某一行：

editor.gotoLine(lineNumber);

获取总行数：

editor.session.getLength();

设置默认标签大小：

editor.getSession().setTabSize(4);

使用软标签：

editor.getSession().setUseSoftTabs(true);

设置字体大小：

document.getElementById('editor').style.fontSize='12px';

切换自动换行：

editor.getSession().setUseWrapMode(true);

设置行高亮显示：

editor.setHighlightActiveLine(false);

设置打印边距可见性：

editor.setShowPrintMargin(false);

设置编辑器为只读：

editor.setReadOnly(true);  // false为可编辑

窗口自适应

编辑器仅在resize事件触发时时调整自身大小。要想以其他方式调整编辑器div的大小，并且需要调整编辑器大小，请使用以下命令：

editor.resize()

在代码中搜索

主要的ACE编辑器搜索功能在 search.js.中定义。以下选项可用于搜索参数：

• needle: 要查找的字符串或正则表达式
• backwards: 是否从当前光标所在的位置向后搜索。默认为“false”
• wrap: 当搜索到达结尾时，是否将搜索返回到开头。默认为“false
• caseSensitive: 搜索是否应该区分大小写。默认为“false”
• wholeWord: 搜索是否只匹配整个单词。默认为“false”
• range: 搜索匹配范围，要搜索整个文档则设置为空
• regExp: 搜索是否为正则表达式。默认为“false”
• start: 开始搜索的起始范围或光标位置
• skipCurrent: 是否在搜索中包含当前行。默认为“false”

下面是一个如何在编辑器对象上设置搜索的示例：

editor.find('needle',{
  backwards: false,
  wrap: false,
  caseSensitive: false,
  wholeWord: false,
  regExp: false
});
editor.findNext();
editor.findPrevious();

这是执行替换的方法：

editor.find('foo');
editor.replace('bar');

这是全部替换：

editor.replaceAll('bar');

editor.replaceAll使用前需要先调用editor.find('needle', ...)

事件监听

onchange:

editor.getSession().on('change', callback);

selection变化:

editor.getSession().selection.on('changeSelection', callback);

cursor变化:

editor.getSession().selection.on('changeCursor', callback);

添加新的命令和绑定

将指定键绑定并分配给自定义功能：

editor.commands.addCommand({
    name: 'myCommand',
    bindKey: {win: 'Ctrl-M',  mac: 'Command-M'},
    exec: function(editor) {
        //...
    }
});

主要配置项

以下是目前所支持的主要选项的列表。除非另有说明，否则选项值皆为布尔值，可以通过editor.setOption来设置。

- editor选项

选项名	值类型	默认值	可选值	备注
selectionStyle	String	text	line|text	选中样式
highlightActiveLine	Boolean	true	-	高亮当前行
highlightSelectedWord	Boolean	true	-	高亮选中文本
readOnly	Boolean	false	-	是否只读
cursorStyle	String	ace	ace|slim|smooth|wide	光标样式
mergeUndoDeltas	String|Boolean	false	always	合并撤销
behavioursEnabled	Boolean	true	-	启用行为
wrapBehavioursEnabled	Boolean	true	-	启用换行
autoScrollEditorIntoView	Boolean	false	-	启用滚动
copyWithEmptySelection	Boolean	true	-	复制空格
useSoftTabs	Boolean	false	-	使用软标签
navigateWithinSoftTabs	Boolean	false	-	软标签跳转
enableMultiselect	Boolean	false	-	选中多处

- renderer选项

选项名	值类型	默认值	可选值	备注
hScrollBarAlwaysVisible	Boolean	false	-	纵向滚动条始终可见
vScrollBarAlwaysVisible	Boolean	false	-	横向滚动条始终可见
highlightGutterLine	Boolean	true	-	高亮边线
animatedScroll	Boolean	false	-	滚动动画
showInvisibles	Boolean	false	-	显示不可见字符
showPrintMargin	Boolean	true	-	显示打印边距
printMarginColumn	Number	80	-	设置页边距
printMargin	Boolean|Number	false	-	显示并设置页边距
fadeFoldWidgets	Boolean	false	-	淡入折叠部件
showFoldWidgets	Boolean	true	-	显示折叠部件
showLineNumbers	Boolean	true	-	显示行号
showGutter	Boolean	true	-	显示行号区域
displayIndentGuides	Boolean	true	-	显示参考线
fontSize	Number|String	inherit	-	设置字号
fontFamily	String	inherit		设置字体
maxLines	Number	-	-	至多行数
minLines	Number	-	-	至少行数
scrollPastEnd	Boolean|Number	0	-	滚动位置
fixedWidthGutter	Boolean	false	-	固定行号区域宽度
theme	String	-	-	主题引用路径，例如"ace/theme/textmate"

- mouseHandler选项

选项名	值类型	默认值	可选值	备注
scrollSpeed	Number	-	-	滚动速度
dragDelay	Number	-	-	拖拽延时
dragEnabled	Boolean	true	-	是否启用拖动
focusTimout	Number	-	-	聚焦超时
tooltipFollowsMouse	Boolean	false	-	鼠标提示

- session选项

选项名	值类型	默认值	可选值	备注
firstLineNumber	Number	1	-	起始行号
overwrite	Boolean	-	-	重做
newLineMode	String	auto	auto|unix|windows	新开行模式
useWorker	Boolean	-	-	使用辅助对象
useSoftTabs	Boolean	-	-	使用软标签
tabSize	Number	-	-	标签大小
wrap	Boolean	-	-	换行
foldStyle	String	-	markbegin|markbeginend|manual	折叠样式
mode	String	-	-	代码匹配模式，例如“ace/mode/text"

- 扩展选项

选项名	值类型	默认值	可选值	备注
enableBasicAutocompletion	Boolean	-	-	启用基本自动完成
enableLiveAutocompletion	Boolean	-	-	启用实时自动完成
enableSnippets	Boolean	-	-	启用代码段
enableEmmet	Boolean	-	-	启用Emmet
useElasticTabstops	Boolean	-	-	使用弹性制表位

本文翻译自Ace Editor官网文档