机器翻译正文由机器翻译自项目原始文档（英文），排版经程序统一处理，可能存在偏差，请以原项目仓库为准。

特里克斯

适用于日常写作的富文本编辑器

在您的网页应用中撰写格式美观的文本。 Trix 是一个所见即所得（WYSIWYG）编辑器，用于编写消息、评论、文章和列表——这些都是大多数网页应用所需的简单文档。它具有复杂的文档模型，支持嵌入附件，并输出简洁且一致的 HTML。

Trix 是一个来自 37signals 的开源项目，该公司是 Ruby on Rails 的创建者。数百万人信任我们来处理他们的文本，而我们开发 Trix 即是为了给他们提供最佳的编辑体验。在 Basecamp 中可查看 Trix 的实际使用。

设计上的不同

Trix 于 2014 年设计时，大多数 WYSIWYG 编辑器都是围绕 HTML 的 contenteditable 和 execCommand API 封装的，这些 API 由微软设计，用于在 Internet Explorer 5.5 中支持网页的实时编辑，并被其他浏览器 最终逆向工程 并复制。

由于这些 API 并没有完整的规范或文档，并且 WYSIWYG HTML 编辑器的范围非常庞大，每个浏览器的实现都有自己的一套漏洞和怪异之处，JavaScript 开发者需要自己解决这些不一致问题。

Trix 通过将 contenteditable 视为一种 I/O 设备来规避这些不一致性：当输入到达编辑器时，Trix 将该输入转换为对其内部文档模型的编辑操作，然后再将该文档重新渲染回编辑器。这使 Trix 完全控制每次按键后的结果，并避免了完全使用 execCommand 的必要。

这是所有现代、生产级 WYSIWYG 编辑器现在采用的方法。

基于 Web 标准构建

Trix 支持所有常更新、自我更新的桌面和移动浏览器。

Trix 是基于成熟的网页标准构建的，尤其是 自定义元素、元素内部、变动观察器 和 Promises。

入门指南

Trix 提供 ESM 和 UMD 格式，并可与任何资源打包系统一起使用。

开始使用 Trix 的最简单方法是在页面的 <head> 中通过 npm CDN 引入它：

<head>
  …
  <link rel="stylesheet" type="text/css" href="https://unpkg.com/trix@2.0.8/dist/trix.css">
  <script type="text/javascript" src="https://unpkg.com/trix@2.0.8/dist/trix.umd.min.js"></script>
</head>

trix.css 包含 Trix 工具栏、编辑器和附件的默认样式。如果你希望自己定义这些样式，可以跳过此文件。

或者，你可以安装 npm 包并在你的应用程序中导入它：

import Trix from "trix"

document.addEventListener("trix-before-initialize", () => {
  // Change Trix.config if you need
})

创建编辑器

在页面上放置一个空的 <trix-editor></trix-editor> 标签。Trix 会在编辑器之前自动插入一个单独的 <trix-toolbar>。

像 HTML 的 <textarea> 一样，<trix-editor> 接受 autofocus 和 placeholder 属性。与 <textarea> 不同，<trix-editor> 会自动垂直扩展以适应其内容。

创建工具栏

Trix 会自动为您创建一个工具栏，并将其附加在 <trix-editor> 元素之前。如果您想将工具栏放在其他位置，可以使用 toolbar 属性：

<main>
  <trix-toolbar id="my_toolbar"></trix-toolbar>
  <div class="more-stuff-inbetween"></div>
  <trix-editor toolbar="my_toolbar" input="my_input"></trix-editor>
</main>

要在不修改 Trix 的情况下更改工具栏，您可以重写 Trix.config.toolbar.getDefaultHTML() 函数。默认的工具栏 HTML 位于 config/toolbar.js 中。Trix 使用数据属性来决定如何响应工具栏按钮点击。

切换属性

使用 data-trix-attribute="<attribute name>"，您可以向当前选区添加属性。例如，要将加粗样式应用到所选文本，按钮是：

<button type="button" class="bold" data-trix-attribute="bold" data-trix-key="b"></button>

Trix 将确定已选择一段文本，并将应用在 Trix.config.textAttributes（位于 config/text_attributes.js 中）中定义的格式。

data-trix-key="b" 告诉 Trix，当你使用 meta b 时，应应用此属性。

如果该属性在 Trix.config.blockAttributes 中定义，Trix 将把该属性应用到当前的文本块。

<button type="button" class="quote" data-trix-attribute="quote"></button>

点击引用按钮可以切换该块是否应使用 <blockquote> 渲染。

与元素内部集成

Trix 将根据浏览器对 Element Internals 的支持，将 <trix-editor> 元素与表单集成。如果需要禁用对 ElementInternals 的支持，请设置 Trix.elements.TrixEditorElement.formAssociated = false :

import Trix from "trix"

Trix.elements.TrixEditorElement.formAssociated = false

当 Trix 配置为与 ElementInternals 兼容时，它也能够在没有 <input type="hidden"> 元件的情况下运行。要配置 <trix-editor> 元件以跳过创建其 <input type="hidden">，请设置该元件的 willCreateInput = false：

addEventListener("before-trix-initialize", (event) => {
  const trixEditor = event.target

  trixEditor.willCreateInput = false
})

调用内部 Trix 操作

内部操作在 controllers/editor_controller.js 中定义，包括：

• 撤销
• 重做
• 链接
• 增加块级别
• 减少块级别

<button type="button" class="block-level decrease" data-trix-action="decreaseBlockLevel"></button>

调用外部自定义操作

如果你想在工具栏上添加一个按钮并让它调用外部操作，你可以在操作名称前加上 x-。例如，如果我想在每次点击我的新按钮时打印一条日志语句，我会将按钮的数据属性设置为 data-trix-action="x-log"

<button id="log-button" type="button" data-trix-action="x-log"></button>

要响应该操作，请监听 trix-action-invoke。事件的 target 属性返回对 <trix-editor> 元素的引用，其 invokingElement 属性返回对 <button> 元素的引用，而其 actionName 属性返回 [data-trix-action] 属性的值。使用 actionName 属性的值来检测调用了哪个外部操作。

document.addEventListener("trix-action-invoke", function(event) {
  const { target, invokingElement, actionName } = event

  if (actionName === "x-log") {
    console.log(`Custom ${actionName} invoked from ${invokingElement.id} button on ${target.id} trix-editor`)
  }
})

与表单集成

要通过表单提交 <trix-editor> 的内容，首先在表单中定义一个隐藏输入字段，并为其分配一个 id。然后在编辑器的 input 属性中引用该 id。

<form …>
  <input id="x" type="hidden" name="content">
  <trix-editor input="x"></trix-editor>
</form>

Trix 会在编辑器每次更改时自动更新隐藏输入字段的值。

填充存储的内容

要用存储的内容填充 <trix-editor>，请将该内容包含在相关输入元素的 value 属性中。

<form …>
  <input id="x" value="Editor content goes here" type="hidden" name="content">
  <trix-editor input="x"></trix-editor>
</form>

使用关联的输入元素来初始化填充编辑器。当没有关联的输入元素时，Trix 会在将内容加载到编辑器中时清理 <trix-editor>…</trix-editor> 标签内的 HTML 内容。

<form …>
  <trix-editor>Editor content goes here</trix-editor>
</form>

验证编辑器

开箱即用，<trix-editor> 元素支持浏览器内置的 Constraint validation。当使用 required 属性渲染时，如果编辑器完全为空，它们将被视为无效。例如，考虑以下 HTML：

<input id="x" value="" type="hidden" name="content">
<trix-editor input="x" required></trix-editor>

由于 <trix-editor> 元素是 [required]，当其值为空时，这是无效的：

const editor = document.querySelector("trix-editor")

editor.validity.valid        // => false
editor.validity.valueMissing // => true
editor.matches(":valid")     // => false
editor.matches(":invalid")   // => true

editor.value = "A value that isn't empty"

editor.validity.valid         // => true
editor.validity.valueMissing  // => false
editor.matches(":valid")      // => true
editor.matches(":invalid")    // => false

除了内置的 [required] 属性外，<trix-editor> 元素还支持通过它们的 setCustomValidity 方法进行自定义验证。例如，考虑以下 HTML：

<input id="x" value="" type="hidden" name="content">
<trix-editor input="x"></trix-editor>

自定义验证可以在任何时候发生。例如，验证可以在编辑器内容更改后触发的 trix-change 事件之后进行：

addEventListener("trix-change", (event) => {
  const editorElement = event.target
  const trixDocument = editorElement.editor.getDocument()
  const isValid = (trixDocument) => {
    // determine the validity based on your custom criteria
    return true
  }

  if (isValid(trixDocument)) {
    editorElement.setCustomValidity("")
  } else {
    editorElement.setCustomValidity("The document is not valid.")
  }
}

禁用编辑器

要禁用 <trix-editor>，请使用 [disabled] 属性呈现它：

<trix-editor disabled></trix-editor>

已禁用的编辑器不可编辑，无法获得焦点，并且在其相关的 <form> 元素提交时，其值将被忽略。

要更改编辑器是否被禁用，可以切换 [disabled] 属性或为 .disabled 属性分配一个布尔值：

<trix-editor id="editor" disabled></trix-editor>

<script>
  const editor = document.getElementById("editor")

  editor.toggleAttribute("disabled", false)
  editor.disabled = true
</script>

禁用时，编辑器将匹配 :disabled CSS 伪类。

提供可访问名称

像其他表单控件一样，<trix-editor> 元素应具有可访问名称。<trix-editor> 元素可与 <label> 元素集成。它支持两种与 <label> 元素集成的样式：

1. 使用 [id] 属性渲染 <trix-editor> 元素，而 <label> 元素通过其 [for] 属性引用该属性：

<label for="editor">Editor</label>
<trix-editor id="editor"></trix-editor>

2. 将 <trix-editor> 元素作为 <label> 元素的子元素呈现：

<trix-toolbar id="editor-toolbar"></trix-toolbar>
<label>
  Editor

  <trix-editor toolbar="editor-toolbar"></trix-editor>
</label>

除了与 <label> 元素集成之外，<trix-editor> 元素还支持 [aria-label] 和 [aria-labelledby] 属性。

为格式化内容设置样式

为了确保在编辑时看到的内容与保存时看到的内容一致，请使用 CSS 类名来限定 Trix 格式内容的样式范围。将此类名应用到您的 <trix-editor> 元素，以及在应用中呈现存储的 Trix 内容以供显示时的容器元素上。

<trix-editor class="trix-content"></trix-editor>

<div class="trix-content">Stored content here</div>

默认的 trix.css 文件包括基本格式化内容的样式——包括项目符号和编号列表、代码块以及块引用——在类名 trix-content 下。我们鼓励您将这些样式作为起点，通过将它们复制到您的应用程序的 CSS 中并使用不同的类名来使用。

存储附加文件

Trix 会自动接受拖入或粘贴到编辑器中的文件，并将它们作为附件插入到文档中。每个附件在远程存储并向 Trix 提供永久 URL 之前，都被视为_待处理_状态。

要存储附件，请监听 trix-attachment-add 事件。你需要自己使用 XMLHttpRequest 上传附加的文件，并在完成后设置附件的 URL 属性。有关详细信息，请参阅附件示例。

如果你不想接受拖入或粘贴的文件，请在 trix-file-accept 事件上调用 preventDefault()，该事件由 Trix 在 trix-attachment-add 事件之前分发。

预览附加文件

Trix 会自动预览附加的图像文件。为了确定是否预览附加文件，Trix 会将文件的内容类型与 Trix.Attachment.previewablePattern 进行比较。默认情况下，Trix 会预览以下内容类型：

• image/gif
• image/png
• image/webp
• image/jpg
• image/jpeg

要自定义附件的预览，请监听 trix-attachment-add 事件。在处理该事件时，设置附件的 previewable 属性，然后通过调用 setPreviewURL 更改其预览 URL：

addEventListener("trix-attachment-add", (event) => {
  if (event.attachment.file instanceof File) {
    event.attachment.setAttribute("previewable", true)
    event.attachment.setPreviewURL("...")
  }
})

以编程方式编辑文本

您可以通过 Trix.Editor 接口以编程方式操作 Trix 编辑器，该接口可通过每个 <trix-editor> 元素的 editor 属性访问。

var element = document.querySelector("trix-editor")
element.editor  // is a Trix.Editor instance

理解文档模型

Trix 编辑器的格式化内容被称为 document，并表示为 Trix.Document 类的一个实例。要获取编辑器当前的文档，请使用 editor.getDocument 方法。

element.editor.getDocument()  // is a Trix.Document instance

您可以使用 document.toString 方法将文档转换为未格式化的 JavaScript 字符串。

var document = element.editor.getDocument()
document.toString()  // is a JavaScript string

不可变性与相等性

文档是不可变的值。你在编辑器中所做的每一次更改，都会用一个新文档替换之前的文档。捕获编辑器内容的快照就像保留对其文档的引用一样简单，因为该文档随时间永远不会改变。（这就是 Trix 实现撤销的方法。）

要比较两个文档是否相等，请使用 document.isEqualTo 方法。

var document = element.editor.getDocument()
document.isEqualTo(element.editor.getDocument())  // true

获取和设置选区

Trix 文档被组织为可以单独寻址的字符序列。文档中某个字符的索引称为 位置，起始和结束位置一起构成一个 范围。

要获取编辑器当前的选择区域，请使用 editor.getSelectedRange 方法，该方法返回一个包含起始和结束位置的两元素数组。

element.editor.getSelectedRange()  // [0, 0]

您可以通过将一个范围数组传递给 editor.setSelectedRange 方法来设置编辑器的当前选区。

// Select the first character in the document
element.editor.setSelectedRange([0, 1])

折叠的选择

当一个范围的起始位置和结束位置相等时，该范围被称为“折叠”。在编辑器中，折叠的选择显示为闪烁的光标，而不是高亮的文本范围。

为了方便起见，在处理折叠的选择时，以下对 setSelectedRange 的调用是等效的：

element.editor.setSelectedRange(1)
element.editor.setSelectedRange([1])
element.editor.setSelectedRange([1, 1])

方向移动

要通过编程方式移动文档中的光标或选区，请使用 direction 参数调用 editor.moveCursorInDirection 或 editor.expandSelectionInDirection 方法。方向可以是 "forward" 或 "backward"。

// Move the cursor backward one character
element.editor.moveCursorInDirection("backward")

// Expand the end of the selection forward by one character
element.editor.expandSelectionInDirection("forward")

将位置转换为像素偏移量

有时你需要知道编辑器中某个位置的字符的_x_和_y_坐标。例如，你可能想要将一个弹出菜单元素定位在编辑器光标下方。

调用 editor.getClientRectAtPosition 方法并传入一个位置参数，以获取一个 DOMRect 实例，该实例表示给定位置的字符的左边距和上边距、宽度和高度。

var rect = element.editor.getClientRectAtPosition(0)
[rect.left, rect.top]  // [17, 49]

插入和删除文本

编辑器界面提供了在当前选区插入、替换和删除文本的方法。

要插入或替换文本，首先设置选定的范围，然后调用下面的插入方法之一。Trix 会先删除任何选中的文本，然后在选定范围的起始位置插入新文本。

插入纯文本

要将未格式化的文本插入文档，请调用 editor.insertString 方法。

// Insert “Hello” at the beginning of the document
element.editor.setSelectedRange([0, 0])
element.editor.insertString("Hello")

插入 HTML

要将 HTML 插入文档，请调用 editor.insertHTML 方法。Trix 会首先将 HTML 转换为其内部文档模型。在此转换过程中，任何无法在 Trix 文档中表示的格式都会丢失。

// Insert a bold “Hello” at the beginning of the document
element.editor.setSelectedRange([0, 0])
element.editor.insertHTML("<strong>Hello</strong>")

插入文件

要将 DOM File 对象插入到文档中，请调用 editor.insertFile 方法。Trix 会为文件插入一个待处理的附件，就好像你将其拖放到编辑器中一样。

// Insert the selected file from the first file input element
var file = document.querySelector("input[type=file]").file
element.editor.insertFile(file)

插入内容附件

内容附件是独立的 HTML 单元，在编辑器中表现得像文件。它们可以被移动或移除，但不能直接编辑，并在文档模型中以单个字符位置表示。

要将 HTML 插入为附件，请创建一个带有 content 属性的 Trix.Attachment，并调用 editor.insertAttachment 方法。内容附件中的 HTML 不受 Trix 文档转换规则影响，将按原样呈现。

var attachment = new Trix.Attachment({ content: '<span class="mention">@trix</span>' })
element.editor.insertAttachment(attachment)

插入换行符

要插入换行符，请调用 editor.insertLineBreak 方法，其功能等同于按回车键。

// Insert “Hello\n”
element.editor.insertString("Hello")
element.editor.insertLineBreak()

删除文本

如果当前选择已折叠，您可以使用 editor.deleteInDirection 方法模拟删除光标前或光标后的文本。

// “Backspace” the first character in the document
element.editor.setSelectedRange([1, 1])
element.editor.deleteInDirection("backward")

// Delete the second character in the document
element.editor.setSelectedRange([1, 1])
element.editor.deleteInDirection("forward")

要删除一段文本，首先设置选定范围，然后调用 editor.deleteInDirection，并将任一方向作为参数。

// Delete the first five characters
element.editor.setSelectedRange([0, 4])
element.editor.deleteInDirection("forward")

处理属性和嵌套

Trix 表示文档范围内应用的一组 属性 来进行格式化。

默认情况下，Trix 支持行内属性 bold、italic、href 和 strike，以及块级属性 heading1、quote、code、bullet 和 number。

应用格式化

要将格式应用于当前选定内容，请使用 editor.activateAttribute 方法。

element.editor.insertString("Hello")
element.editor.setSelectedRange([0, 5])
element.editor.activateAttribute("bold")

要设置 href 属性，请将 URL 作为第二个参数传递给 editor.activateAttribute。

element.editor.insertString("Trix")
element.editor.setSelectedRange([0, 4])
element.editor.activateAttribute("href", "https://trix-editor.org/")

删除格式

使用 editor.deactivateAttribute 方法从选定内容中删除格式。

element.editor.setSelectedRange([2, 4])
element.editor.deactivateAttribute("bold")

使用折叠选择进行格式化

如果在选择折叠时激活或停用属性，你的格式更改将应用于随后任何对 editor.insertString 的调用插入的文本。

element.editor.activateAttribute("italic")
element.editor.insertString("This is italic")

调整嵌套级别

要调整引号、项目符号列表或编号列表的嵌套级别，请调用 editor.increaseNestingLevel 和 editor.decreaseNestingLevel 方法。

element.editor.activateAttribute("quote")
element.editor.increaseNestingLevel()
element.editor.decreaseNestingLevel()

使用撤销和重做

Trix 编辑器支持无限次撤销和重做。连续的输入和格式更改会在五秒间隔内合并；所有其他输入更改会单独记录在撤销历史中。

调用 editor.undo 和 editor.redo 方法以执行撤销或重做操作。

element.editor.undo()
element.editor.redo()

通过编辑器界面进行的更改不会自动记录撤销条目。您可以通过调用 editor.recordUndoEntry 方法并传入描述参数来保存您自己的撤销条目。

element.editor.recordUndoEntry("Insert Text")
element.editor.insertString("Hello")

加载和保存编辑器状态

使用 JSON.stringify 序列化编辑器的状态，并使用 editor.loadJSON 方法恢复已保存的状态。序列化的状态包括文档和当前选择，但不包括撤销历史。

// Save editor state to local storage
localStorage["editorState"] = JSON.stringify(element.editor)

// Restore editor state from local storage
element.editor.loadJSON(JSON.parse(localStorage["editorState"]))

HTML 消毒

Trix 使用 DOMPurify 来清理编辑器内容。您可以通过 Trix.config.dompurify 设置 DOMPurify 配置。

例如，如果您想保留一个自定义标签，您可以这样操作：

Trix.config.dompurify.ADD_TAGS = [ "my-custom-tag" ]

HTML 渲染

Trix 通过用新节点替换现有节点来渲染编辑器内容的更改。

要自定义 Trix 的渲染更改方式，请将 <trix-editor> 元素的 render 属性设置为一个函数，该函数接受一个 <trix-editor> 实例和一个 DocumentFragment ：

document.addEventListener("trix-before-render", (event) => {
  const defaultRender = event.render

  event.render = function(editorElement, documentFragment) {
    // modify the documentFragment…
    customize(documentFragment)

    // render it with the default rendering function
    defaultRender(editorElement, documentFragment)
  }
})

观察编辑器变化

<trix-editor> 元素会发出多个事件，可用于观察并响应编辑器状态的变化。

• trix-before-initialize 在 <trix-editor> 元素附加到 DOM、Trix 安装其 editor 对象之前触发。如果需要使用自定义 Trix 配置，可以在此处修改 Trix.config。

• trix-initialize 在 <trix-editor> 元素附加到 DOM 并且其 editor 对象可以使用时触发。

• trix-change 在编辑器内容更改时触发。

• trix-before-render 在渲染编辑器的新内容之前触发。你可以通过事件上的 render 属性覆盖用于渲染内容的函数。render 函数期望两个位置参数：将要渲染的 <trix-editor> 元素和包含新内容的 DocumentFragment 实例。阅读 HTML Rendering 了解更多信息。

• trix-before-paste 在文本粘贴到编辑器之前触发。你可以利用此事件修改要粘贴的内容或完全阻止粘贴事件的发生。事件上的 paste 属性包含粘贴的 string 或 html 以及插入文本的 range。

• trix-paste 在文本粘贴到编辑器时触发。事件上的 paste 属性包含粘贴的 string 或 html 以及插入文本的 range。

• trix-selection-change 在编辑器中选定范围发生更改时触发。

• trix-focus 和 trix-blur 分别在编辑器获取或失去焦点时触发。

• trix-file-accept 在文件被拖放或插入编辑器时触发。你可以通过事件上的 file 属性访问 DOM File 对象。调用事件上的 preventDefault 方法可以防止将文件附加到文档中。

• trix-attachment-add 在附件被添加到文档后触发。你可以通过事件上的 attachment 属性访问 Trix 附件对象。如果 attachment 对象具有 file 属性，你应该远程存储此文件并设置附件的 URL 属性。详细信息见 attachment example。

• trix-attachment-edit 在文档中附件被编辑后触发。你可以通过事件上的 attachment 属性访问 Trix 附件对象。

• trix-attachment-remove 在附件从文档中移除时触发。你可以通过事件上的 attachment 属性访问 Trix 附件对象。你可能希望使用此事件来清理远程存储的文件。

• trix-action-invoke 在调用 Trix 操作时触发。您可以通过事件的 target 属性访问 <trix-editor> 元素，通过 invokingElement 属性访问负责调用操作的元素，通过 actionName 属性访问操作的名称。trix-action-invoke 事件只会在自定义操作中触发，而不会在内置操作中触发。

贡献于 Trix

Trix 是开源软件，根据MIT 风格许可证的条款可自由分发。源代码托管在 GitHub 上。

我们欢迎以错误报告、拉取请求或在GitHub 问题跟踪器中进行有深度的讨论等形式贡献。请参阅行为准则了解我们对贡献者的承诺。

Trix 由 Javan Makhmali 和 Sam Stephenson 创建，开发由 37signals 赞助。

从源码构建

Trix 使用 Yarn 管理依赖，使用 Rollup 打包源码。

使用以下命令安装开发依赖：

$ yarn install

要生成分发文件，请运行：

$ yarn build

在浏览器中开发

当你的源文件发生更改时，你可以运行一个监视进程来自动生成分发文件：

$ yarn watch

当监视进程运行时，你可以运行一个网络服务器来提供编译后的资源：

$ yarn dev

在开发服务器运行时，你可以访问 /index.html 来查看 Trix 调试器检查器，或者访问 /test.html 在浏览器中运行测试。

为了更方便开发，你可以监听 JavaScript 和样式文件的更改，并使用单个命令在浏览器中提供结果：

$ yarn start

运行测试

你也可以在无头模式下运行测试，方法是：

$ yarn test

---

© 37signals有限责任公司。