AceAjax.org Cloud9 Editor嵌入、运行与构建完全指南【免费下载链接】aceAce (Ajax.org Cloud9 Editor)项目地址: https://gitcode.com/gh_mirrors/ac/aceAce 是一款用 JavaScript 编写的独立浏览器代码编辑器目标是在浏览器中复现并超越 TextMate、Vim、Eclipse 等原生编辑器的功能、易用性与性能。本篇指南以 Ace 官方 README仓库根目录 Readme.md为主线结合本仓库源码src/ace.js、src/config.js、static.js、Makefile.dryice.js、package.json逐层讲解如何把 Ace 嵌入任意网页、如何本地运行与调试、如何按需构建打包、如何运行单元测试以及配置项与构建参数的底层实现原理。一、Ace 是什么项目定位与核心特性Ace全称 Ajax.org Cloud9 Editor是 Cloud9 IDE 的主编辑器也是 Mozilla SkywriterBespin项目的后继者。它不依赖任何后端服务可以轻松嵌入任意网页或 JavaScript 应用中其主入口文件为 src/ace.js当前仓库版本为1.44.0见 package.json。根据官方 READMEAce 的核心特性包括超过 120 种语言的语法高亮且可直接导入 TextMate / Sublime 的tmlanguage语法文件超过 20 套主题可直接导入 TextMate / Sublime 的tmtheme主题文件自动缩进与反缩进indent / outdent可选命令行Command Line支持超大文档官方记录的上限为 4,000,000 行完全可自定义的键位绑定内置 Vim 与 Emacs 模式对应 src/keyboard/vim.js、src/keyboard/emacs.js支持正则表达式的查找与替换src/search.js匹配括号高亮软 Tab 与真实 Tab 切换显示隐藏字符鼠标拖放文本自动换行Line wrapping代码折叠Code Folding多光标与多选区src/multi_select.js实时语法检查目前支持 JavaScript / CoffeeScript / CSS / XQuery通过 Web Worker 实现通过 ace-linters 为众多语言提供完整的 Language Server 客户端支持完整的剪切、复制、粘贴功能。从仓库结构看这些能力被组织为高度模块化的 AMD 模块mode/目录存放语言模式与高亮规则如 src/mode/javascript.js、src/mode/javascript_highlight_rules.jstheme/目录存放主题如 src/theme/twilight.jsext/目录存放扩展如 src/ext/statusbar.js、src/ext/settings_menu.js这为按需加载与自定义扩展提供了清晰的边界。二、快速体验先跑起来再说在动手嵌入之前最快的体验方式是官方在线 demokitchen-sink厨房水槽式全功能演示页。本仓库中对应的源码位于 demo/kitchen-sink/demo.js演示页入口为根目录的 kitchen-sink.html。此外也可以注册 Cloud9 IDE 账号在编辑自己 GitHub 项目的同时体验 Ace 的完整能力。如果只想把 Ace 当作 textarea 的替代品还可以使用 Ace Bookmarklet将书签指向 Bookmarklet 版本后在任意页面点击书签页面上的 textarea 就会被替换为 Ace 编辑器实例。仓库中 Bookmarklet 的构建逻辑由 Makefile.dryice.js 的-bm选项负责。三、嵌入 Ace五步上手官方 README 强调Ace 可以轻易嵌入任何现有网页。有两种方式引入代码使用预先打包好的 ace-builds 发行包将其中某个src*子目录复制进项目使用 requireJS 将本仓库 lib/ace 的内容以模块名ace加载。下面是最简嵌入版本直接使用单文件版本div ideditorsome text/div script srcsrc/ace.js typetext/javascript charsetutf-8/script script var editor ace.edit(editor); /script其中editor是会被转换为编辑器的 DOM 元素的 id。注意该元素必须被显式设定尺寸且定位方式必须为absolute或relative否则 Ace 无法正常工作。例如#editor { position: absolute; width: 500px; height: 400px; }从源码层面看ace.editsrc/ace.js#L35-L71的实际执行流程是如果传入的是字符串则通过document.getElementById查找元素找不到会抛出ace.edit cant find div #id错误如果元素是input/textarea会读取其value作为初始内容并将其替换为一个pre元素实现 textarea 无损升级否则读取元素的textContent作为初始内容并清空innerHTML调用createEditSession创建编辑会话见 src/ace.js#L79-L83内部会附加 UndoManager 撤销管理器用new Editor(new VirtualRenderer(el), doc, options)组合渲染器与编辑会话并挂载env环境对象与resize回调。3.1 切换主题默认情况下编辑器使用textmate主题。要更换主题先引入主题的 JavaScript 文件script srcsrc/theme-twilight.js typetext/javascript charsetutf-8/script再配置编辑器使用该主题editor.setTheme(ace/theme/twilight);本仓库中对应的主题实现位于 src/theme/twilight.jstheme/目录下共包含 90 套主题均以ace/theme/name作为模块标识。从 src/config.js 的moduleUrl实现可以看到ace/theme/twilight会被解析为themePath theme-twilight suffix即文件名中的目录分隔符被转换为连字符因此主题文件统一命名为theme-name.js。3.2 设置语言模式默认情况下编辑器只支持纯文本模式其他语言以独立模块形式提供。引入语言的模式文件script srcsrc/mode-javascript.js typetext/javascript charsetutf-8/script随后通过ace.require加载模式并设置到会话上var JavaScriptMode ace.require(ace/mode/javascript).Mode; editor.session.setMode(new JavaScriptMode());ace.require返回模块对象其中Mode类负责词汇/语法级的高亮与缩进规则实际高亮规则定义在同名的javascript_highlight_rules.js中src/mode/javascript_highlight_rules.js。editor.session即EditSessionsrc/edit_session.js它承载文档模型、折叠、标记Marker等状态。3.3 销毁编辑器当页面不再需要编辑器时需要显式销毁以释放事件监听与 DOM 引用editor.destroy(); editor.container.remove();destroy()会触发destroy事件——从 src/ace.js#L66-L68 可以看到编辑器销毁时会清理env.editor.container.env引用避免旧版本 IE 下的内存泄漏随后再手动移除容器节点。3.4 全局配置项Configuring-AceAce 的核心配置由 src/config.js 暴露的config单例管理其预置选项src/config.js#L11-L22包括配置项默认值说明packagedfalse是否运行在打包构建版本中workerPathnullWeb Worker 脚本所在路径实时语法检查用modePathnull语言模式模块路径前缀themePathnull主题模块路径前缀basePath上述路径未指定时使用的公共基础路径suffix.js模块文件后缀loadWorkerFromBlobtrue是否通过 Blob 加载 WorkersharedPopupsfalse是否共享弹出层如自动补全弹窗useStrictCSPnull严格 CSP 模式开关使用方式为ace.config.set(themePath, /vendor/ace/)或ace.config.get(key)src/config.js#L29-L47。当modePath/themePath未设置时模块 URL 由moduleUrl()依据basePath、组件名与连字符命名规则推导src/config.js#L63-L89。此外还可通过ace.config.setModuleUrl(name, url)为单个模块指定精确地址src/config.js#L95-L97或用ace.config.setLoader(fn)自定义模块加载器。四、本地运行 Ace零构建开箱即用官方 README 明确说明clone 之后 Ace 即可直接运行无需任何构建步骤。仓库根目录的 static.js 是一个用 Node.js 内置http模块实现的迷你 HTTP 服务器约 170 行启动方式node ./static.js随后在浏览器打开http://localhost:8888/kitchen-sink.html从 static.js 源码可以看到几个实用的运行细节端口与监听地址可通过环境变量覆盖PORT默认8888与IP默认0.0.0.0启动时会打印实际的访问地址static.js#L7-L8、static.js#L170服务器支持目录索引浏览自动生成带文件大小的 HTML 目录页static.js#L89-L124并做了目录穿越防护static.js#L42-L44支持OPTIONS/PUT方法默认禁止写入需显式加--allow-save参数开启浏览器端文件保存static.js#L32-L34、static.js#L51-L55静态文件响应头带有Access-Control-Allow-Origin: file://允许file://协议页面跨源读取static.js#L79-L84。如果希望直接以file:///URL 打开编辑器页面不经由 HTTP 服务器可以查阅仓库内 wiki 相关说明Running-Ace-from-file。五、构建 Ace何时需要如何操作大多数情况下你不需要自行构建ace-builds 发行仓库会持续维护最新构建产物直接复制其中某个src*子目录到项目即可。但若需要自定义打包只需安装 Node.js 与 npm然后npm install node ./Makefile.dryice.jsAce 的打包工具是 dryice由 Mozilla Skywriter 团队开发。运行node Makefile.dryice.js即开始打包该构建脚本支持以下选项-m minify build files with uglify-js -nc namespace require and define calls with ace -bm builds the bookmarklet version --target ./path specify relative path for output folder (default value is ./build)各参数含义与 Makefile.dryice.js 中的帮助文本对应见 showHelp-m用 uglify-js 压缩构建产物对应源码中compress标记Makefile.dryice.js#L130-nc将require/define调用命名空间化为ace前缀避免与页面中其他 AMD 库冲突-bm额外产出 Bookmarklet 版本--target ./path指定输出目录默认./build对应BUILD_DIR的覆盖逻辑Makefile.dryice.js#L108-L110另有未写入 README 的-sshrinkwrap将所有输出合并为单文件等标志可通过-h查看完整帮助。构建还支持若干目标类型用法为node Makefile.dryice.js typetype作用minimal默认值将必要文件输出到 build 目录normal依次构建 minimal、minimal-noconflict、minimal-min、minimal-noconflict-min 四种组合demo构建 kitchen-sink 演示应用full上述全部css抽取 CSS 样式文件nls抽取多语言NLS消息文件要生成 ace-builds 仓库中的全套文件运行node Makefile.dryice.js full --target ../ace-builds从实现细节看构建的第一步是generateAmdModules()Makefile.dryice.js#L48-L91它遍历 src 目录用 TypeScript 编译器把每个.js模块转译为 ES5 并包裹进define(function(require, exports, module){ ... })输出到lib/ace即 README 所说 requireJS 加载的lib/ace内容来源。随后buildAce根据-m/-nc/-s组合出不同发行变体buildTypesMakefile.dryice.js#L197-L254还会同步生成ace.d.ts类型声明、webpack-resolver.js与esm-resolver.js加载器方便 Webpack 与原生 ESM 环境使用。六、运行单元测试Node 与浏览器两种方式Ace 的单元测试可以在 Node.js 上直接运行。假设已经执行过npm install只需npm run test该命令对应 package.json 中的test: mocha \./src/**/*_test.js\ --exit -p --color即用 mocha 递归执行src下所有*_test.js测试文件如 src/document_test.js、src/search_test.js、src/editor_test.js 等数百个测试模块。也可以在浏览器中运行测试便于调试失败的用例http://localhost:8888/src/test/tests.html浏览器测试入口为 src/test/tests.html它通过 src/test/all.js 聚合全部测试模块测试基础设施还包括 mock DOMsrc/test/mockdom.js与 mock 渲染器src/test/mockrenderer.js使得编辑器可以在无真实浏览器布局的环境中被驱动验证。此外仓库还提供覆盖率统计npm run cover基于 c8与类型检查npm run typecheck基于 TypeScript 与 tsconfig.json。七、更多资源与参与贡献事件监听、语法高亮扩展等进阶用法见仓库文档目录 doc/README.md 与 doc/index.mdAPI 文档可参考仓库内的类型声明文件 ace.d.ts 与 types/ace-lib.d.tskitchen-sink 演示应用的完整示例代码即 demo/kitchen-sink/demo.js其中展示了多编辑器布局、ace/ext/rtl、ace/ext/diff、ace/ext/whitespace、增量搜索、令牌悬停提示TokenTooltip等扩展的接法diff 视图的独立示例见 demo/diff/index.html静态高亮示例见 demo/static-highlighter/client.html遇到问题可以到项目 discussions 页面提问。Ace 是社区项目官方鼓励并支持一切形式的贡献。源码以 BSD License 发布见 LICENSE该许可非常宽松对开源与非开源项目都友好——你可以 fork 后任意改进也可以按需为编辑器添加自己喜爱的语言高亮与键位绑定。若你认为改动对 Ace 或社区有益欢迎提交 Pull Request贡献规范详见 CONTRIBUTING.md。【免费下载链接】aceAce (Ajax.org Cloud9 Editor)项目地址: https://gitcode.com/gh_mirrors/ac/ace创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考