这篇翻译不完整。请帮忙从英语翻译这篇文章。
这是一个可以嵌入到你的插件的代码编辑组件,已有的所有火狐开发者工具都使用了它,在其底层,该编辑组件是开源编辑器CodeMirror的简化封装。
基本用法
使用该编辑器的最简单方法是导入模块,建立一个编辑器项目实例,然后使用其appendTo 方法加载该实例到一个DOM节点。
let Editor = require("devtools/sourceeditor/editor"); let editor = new Editor(); editor.appendTo(parentNode);
The code above creates a new editor instance and attaches it to the DOM node references by the parentNode variable. (IMPORTANT: parentNode should be an element that can act as a parent.) When creating a new instance, you can pass a configuration object as an optional parameter.
let editor = new Editor({ value: "// hello", mode: Editor.modes.js, lineNumbers: true });
This configuration object can hold same properties as CodeMirror's configuration object. The only difference is the 'mode' property. Currently, it supports these syntax highlighting modes:
- 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
Since our Editor is a thin wrapper around CodeMirror it exposes some CodeMirror methods as-is. For more information refer to the CodeMirror documentation page. The rest of this page assumes that you're familiar with CodeMirror and its concepts. The following methods are identical to the ones provided by 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
These methods either don't exist in CodeMirror or behave differently:
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() 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 |
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 |
Addons
We include a few CodeMirror addons with our distribution. To use them all you need to do is enable the following configuration options:
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)
Keymaps
We also include three additional keymaps, for VIM, Emacs, and Sublime Text modes. To enable them, set the keyMap configuration option to either emacs, vim, or sublime. In addition to that, the default keymap can be controlled by the devtools.editor.keymap
option in about:config.
Feedback
For feedback please use Developer Tools mailing list. And if you think you found a bug, let us know about it.