这是一个可以嵌入到你的插件的代码编辑组件,已有的所有火狐开发者工具都使用了它,在其底层,该编辑组件是开源编辑器CodeMirror的简化封装。

基本用法

使用该编辑器的最简单方法是导入模块,建立一个编辑器项目实例,然后使用其appendTo 方法加载该实例到一个DOM节点。

let Editor = require("devtools/sourceeditor/editor");
let editor = new Editor();
editor.appendTo(parentNode);

上述的代码创造了一个新的编辑器实例,并且通过父节点对象将其附加到DOM节点引用。(注意:父节点应该是一个可以当作父节点的元素。)当创作一个新的实例,你可以将配置对象作为可选参数传递。

let editor = new Editor({
  value: "// hello",
  mode: Editor.modes.js,
  lineNumbers: true
});

这个配置对象能够拥有和CodeMirror配置对象相同的的属性。且它们唯一不同是在“模式”属性方面。当前,它支持下面这些语法高亮模式:

  • Editor.modes.text for plain text.
  • Editor.modes.js for JavaScript (including ES6)
  • Editor.modes.css for CSS
  • Editor.modes.html for HTML (including embedded CSS and JS)
  • Editor.modes.vs and Editor.modes.fs for WebGL shaders (x-vertex and x-fragment respectively)

API

由于我们的编辑器是 CodeMirror的简化封装,因此它会按原样公开一些CodeMirror方法。更多的信息请参考CodeMirror文档页面。而本页接下来的内容则是以您熟悉CodeMirror及其概念为前提来书写的。 以下方法和CodeMirror所提供的方法完全相同:

  • focus()
  • hasFocus() → boolean
  • lineCount() → integer
  • somethingSelected() → boolean
  • getCursor(?start: string) → {line, ch}
  • setSelection(anchor: {line, ch}, ?head: {line, ch})
  • getSelection() → string
  • replaceSelection(replacement: string, ?collapse: string)
  • extendSelection(from: {line, ch}, ?to: {line, ch})
  • undo()
  • redo()
  • clearHistory()
  • openDialog(template: element, callback: function, ?options:object)
  • refresh()
  • setOption(option: string, value: any)
  • getOption(option: string) → any

而下面这些方法要么在CodeMirror中不存在,要么行为不一样。

Description Status
appendTo(el: element, ?env: iframe) → promise
Appends the current Editor instance to the element specified by el. You can also provide your own iframe to host the editor as an optional second parameter (otherwise, Editor will create a new iframe).
Stable
getMode() object
Returns the current active syntax mode. See above for the list of all supported modes.
Stable
setMode(mode: object)
Sets the syntax mode. See above for the list of all supported modes.
Stable
getText(?line: number) → string
Returns the current editor's content. If line argument is provided, the method returns only that line.
Stable
setText(value: string)
Replaces the text content of the editor with the provided value.
Stable
replaceText(value: string, ?from:{ch, line}, ?to:{ch, line})
Replaces the editor's content within the specified from/to range with the provided value. If neither from nor to arguments are provided, then this method works exactly like setText. If only from object is provided, inserts text at that point, overwriting as many characters as needed.
Stable
insertText(value: string, at: {ch, line})
Inserts text at the specified at position, shifting existing contents as necessary.
Stable
dropSelection()
Deselects the current editor content.
Stable
getFirstVisibleLine() → number
Returns the line number of the first visible line.
Stable
setFirstVisibleLine(line: number)
Scrolls the editor's contents such that the given line is the first visible line at the top of the editor.
Stable
setCursor(pos: {line, ch}, align: string)
Sets the cursor to the specified {line, ch} position with an additional option to align the line at the "top", "center" or "bottom" of the editor with "top" being the default value.
Stable
alignLine(line: number, align: string)
Aligns the provided line to either "top", "center" or "bottom" of the editor view with a maximum margin of three lines from top or bottom.
Unstable
hasMarker(line: number, gutterName: string, markerClass: string) → boolean
Returns whether a marker of a specified class exists in a line's gutter.
Stable
addMarker(line: number, gutterName: string, markerClass: string)
Adds a marker with a specified class to a line's gutter. If another marker exists on that line, the new marker class is added to its class list.
Stable
removeMarker(line: number, gutterName: string, markerClass: string)
Removes a marker of a specified class from a line's gutter.
Stable
removeAllMarkers(gutterName: string)
Removes all gutter markers in the gutter with the given name.
Stable
setMarkerListeners(line: number, gutterName: string, markerClass: string, events: object, data: object)
Handles attaching a set of events listeners on a marker. They should be passed as an object literal with keys as event names and values as function listeners. The line number, marker node and optional data will be passed as arguments to the function listener. You don't need to worry about removing these event listeners. They're automatically orphaned when clearing markers.
Unstable
hasLineClass(line: number, className: string) → boolean
Returns whether a line is decorated using the specified class name.
Stable
addLineClass(line: number, className: string)
Sets a CSS class name for the given line, including the text and gutter.
Stable
removeLineClass(line: number, className: string)
Removes a CSS class name for the given line.
Stable
markText(from: {line,ch}, to: {line,ch}, className: string) → { anchor: element, clear: function }
Marks a range of text inside the two {line, ch} bounds. Since the range may be modified, for example, when typing text, this method returns a function that can be used to remove the mark.
Stable
getPosition(index: number|list) → {line, ch}|list
Calculates and returns one or more {line, ch} objects for a zero-based index who's value is relative to the start of the editor's text. If only one argument is given, this method returns a single {line, ch} object. Otherwise it returns an array.
Stable
getOffset(pos: {line, ch}|list) → number|list
The reverse of getPosition. Similarly to getPosition this method returns a single value only if one argument was given, and an array otherwise.
Stable
getPositionFromCoords(coord: {left, top}) → {line, ch}
Returns a {line, ch} object that corresponds to the left and top coordinates.
Stable
getCoordsFromPosition(pos: {line, ch}) → {left, top}
The reverse of getPositionFromCoords. Similarly, returns a {left, top} object that corresponds to the specified line and character number.
Stable
canUndo() → boolean
Returns true if there's something to undo and false otherwise.
Stable
canRedo() → boolean
Returns true if there's something to redo and false otherwise.
Stable
setClean() → number
Marks the contents as clean and returns the current version number.
Stable
isClean() → boolean
Returns true if contents of the text area are clean i.e. no changes were made since the last version.
Stable
jumpToLine()
Opens an in-editor dialog asking for a line to jump to. Once given, it changes cursor to that line.
Stable
moveLineUp()
Moves the content of the current line or the lines selected up a line.
Unstable
moveLineDown()
Moves the content of the current line or the lines selected down a line.
Unstable

extend(funcs: object)
Extends an instance of the Editor object with additional functions. Each function will be called with conext as the first argument. Context is a {ed, cm} object where 'ed' is an instance of the Editor object and 'cm' is an instance of the CodeMirror object. Example:

function hello(ctx, name) {
  let { cm, ed } = ctx;
  cm; // CodeMirror instance
  ed; // Editor instance
  name; // "Mozilla"
}

editor.extend({ hello: hello });
editor.hello("Mozilla");
This is the recommended way to write Editor extensions.
Stable
destroy()
Cleans up all the references and emits a 'destroy' event.
Stable

Static Methods

Description Status
Editor.accel(key: string, ?modifiers:object) → string
Returns a string representation of a shortcut key with an OS specific modfiier. Cmd- for Macs, Ctrl- for other platforms. You can also toggle Shift- and Alt- modifiers by passing the modifiers object. Examples:
 
// Assuming Mac platform
Editor.accel("F"); // Cmd-F
Editor.accel("F", { shift: true }); // Shift-Cmd-F
Editor.accel("F", { alt: true }); // Cmd-Alt-F
Stable
Editor.keyFor(cmd: string) → string
Returns a localized string representation of a shortcut for a command specified by cmd and defined in sourceeditor.properties.
Stable

扩展

我们在我们的发行版中包含了少量的CodeMirror扩展。为了使用它们,你需要来启用下述的配置选项:

  • styleActiveLine: highlights the currently active line (on by default)
  • autoCloseBrackets: automatically adds a closing bracket (on by default)
  • matchBrackets: highlights matching brackets (on by default)
  • showTrailingSpace: highlights trailing spaces (off by default)
  • enableCodeFolding: enables code folding (off by default)

快捷键

我们同时也包含了三种适用于VIM, Emacs 和Sublime Text模块附加的快捷键组合。你可以通过设置键盘布局配置选项来启用VIM, Emacs 和Sublime Text它们中的任何一类常用快捷键。除此以外,默认的快捷键也可以由位于about:config   devtools.editor.keymap来控制。

反馈

如果有反馈请使用开发工具邮件列表。并且如果你认为你发现了一个bug,请让我们知道它

文档标签和贡献者

此页面的贡献者: wbamberg, eaglekindoms, penkui
最后编辑者: wbamberg,