增量

Delta 是一种简单但富有表现力的格式，可用于描述 Quill 的内容和更改。该格式是 JSON 的严格子集，易于人类阅读，并且易于被机器解析。Delta 可以描述任何 Quill 文档，包含所有文本和格式信息，且没有 HTML 的歧义性和复杂性。

¥Deltas are a simple, yet expressive format that can be used to describe Quill's contents and changes. The format is a strict subset of JSON, is human readable, and easily parsible by machines. Deltas can describe any Quill document, includes all text and formatting information, without the ambiguity and complexity of HTML.

Note

不要被它的名称 Delta 混淆 - Deltas 既代表文档，也代表对文档的更改。如果你将 Deltas 视为从一个文档到另一个文档的指令，那么 Deltas 表示文档的方式就是从空文档开始表达指令。

¥Don't be confused by its name Delta—Deltas represents both documents and changes to documents. If you think of Deltas as the instructions from going from one document to another, the way Deltas represent a document is by expressing the instructions starting from an empty document.

Delta 被实现为一个单独的独立库对象，允许在 Quill 之外使用。它适用于操作转换，并且可以在类似 Google Docs 的实时应用中使用。有关 Delta 格式的更深入解释，请参阅设计增量格式。

¥Deltas are implemented as a separate standalone library, allowing its use outside of Quill. It is suitable for Operational Transform and can be used in realtime, Google Docs like applications. For a more in depth explanation behind Deltas, see Designing the Delta Format.

Note

不建议手动构建 Delta，而是使用可链接的 insert()、delete() 和 retain() 方法来创建新的 Delta。你可以使用 import() 从 Quill 访问 Delta。

¥It is not recommended to construct Deltas by hand—rather use the chainable insert(), delete(), and retain() methods to create new Deltas. You can use import() to access Delta from Quill.

文档

¥Document

Delta 格式几乎完全不言自明 - 下面的示例描述了字符串 "灰色甘道夫"，其中 "甘道夫" 以粗体显示，"灰色" 以 #cccccc 颜色显示。

¥The Delta format is almost entirely self-explanatory—the example below describes the string "Gandalf the Grey" where "Gandalf" is bolded and "Grey" is colored #cccccc.

{
  ops: [
    { insert: 'Gandalf', attributes: { bold: true } },
    { insert: ' the ' },
    { insert: 'Grey', attributes: { color: '#cccccc' } }
  ]
}

顾名思义，描述内容实际上是 Delta 的一个特例。上面的例子更具体地说明了如何插入加粗的字符串 "甘道夫"、无格式的字符串 "the"，以及颜色为 #cccccc 的字符串 "灰色"。当使用 Delta 描述内容时，可以将其视为将 Delta 应用于空文档时所创建的内容。

¥As its name would imply, describing content is actually a special case for Deltas. The above example is more specifically instructions to insert a bolded string "Gandalf", an unformatted string " the ", followed by the string "Grey" colored #cccccc. When Deltas are used to describe content, it can be thought of as the content that would be created if the Delta was applied to an empty document.

由于 Delta 是一种数据格式，因此 attribute 密钥对的值没有固有含义。例如，Delta 格式中没有任何内容规定颜色值必须为十六进制 - 这是 Quill 的选择，如果需要，可以使用羊皮纸进行修改。

¥Since Deltas are a data format, there is no inherent meaning to the values of attribute keypairs. For example, there is nothing in the Delta format that dictates color value must be in hex—this is a choice that Quill makes, and can be modified if desired with Parchment.

嵌入

¥Embeds

对于非文本内容，例如图片或公式，插入键可以是对象。对象应该有一个键，用于确定其类型。如果你使用羊皮纸构建自定义内容，则此为 blotName。与文本类似，嵌入对象仍然可以使用 attributes 键来描述要应用于嵌入对象的格式。所有嵌入的长度都为 1。

¥For non-text content such as images or formulas, the insert key can be an object. The object should have one key, which will be used to determine its type. This is the blotName if you are building custom content with Parchment. Like text, embeds can still have an attributes key to describe formatting to be applied to the embed. All embeds have a length of one.

{
  ops: [{
    // An image link
    insert: {
      image: 'https://quill.nodejs.cn/assets/images/icon.png'
    },
    attributes: {
      link: 'https://quill.nodejs.cn'
    }
  }]
}

行格式

¥Line Formatting

与换行符关联的属性描述了该行的格式。

¥Attributes associated with a newline character describes formatting for that line.

{
  ops: [
    { insert: 'The Two Towers' },
    { insert: '\n', attributes: { header: 1 } },
    { insert: 'Aragorn sped on up the hill.\n' }
  ]
}

所有 Quill 文档都必须以换行符结尾，即使最后一行没有应用任何格式。这样，你始终都有一个字符位置可以应用行格式。

¥All Quill documents must end with a newline character, even if there is no formatting applied to the last line. This way, you will always have a character position to apply line formatting to.

许多行格式是独占的。例如，Quill 不允许一行同时作为标题和列表，尽管可以用 Delta 格式表示。

¥Many line formats are exclusive. For example Quill does not allow a line to simultaneously be both a header and a list, despite being possible to represent in the Delta format.

变更

¥Changes

当你为 Quill 的 text-change 事件注册监听器时，你将获得的参数之一是描述更改内容的 Delta。除了 insert 操作之外，此 Delta 还可能包含 delete 或 retain 操作。

¥When you register a listener for Quill's text-change event, one of the arguments you will get is a Delta describing what changed. In addition to insert operations, this Delta might also have delete or retain operations.

删除

¥Delete

delete 操作的确切含义如下：删除接下来的字符数。

¥The delete operation instructs exactly what it implies: delete the next number of characters.

{
  ops: [
    { delete: 10 } // Delete the next 10 characters
  ]
}

由于 delete 操作不包含已删除的内容，因此 Delta 不可逆。

¥Since delete operations do not include what was deleted, a Delta is not reversible.

保留

¥Retain

retain 操作仅表示保留接下来的字符数，不进行修改。如果指定了 attributes，则仍然保留这些字符，但应用 attributes 对象指定的格式。属性键的 null 值用于指定格式移除。

¥A retain operation simply means keep the next number of characters, without modification. If attributes is specified, it still means keep those characters, but apply the formatting specified by the attributes object. A null value for an attributes key is used to specify format removal.

从上面的 "灰色甘道夫" 示例开始：

¥Starting with the above "Gandalf the Grey" example:

// {
//   ops: [
//     { insert: 'Gandalf', attributes: { bold: true } },
//     { insert: ' the ' },
//     { insert: 'Grey', attributes: { color: '#cccccc' } }
//   ]
// }

{
  ops: [
    // Unbold and italicize "Gandalf"
    { retain: 7, attributes: { bold: null, italic: true } },

    // Keep " the " as is
    { retain: 5 },

    // Insert "White" formatted with color #fff
    { insert: 'White', attributes: { color: '#fff' } },

    // Delete "Grey"
    { delete: 4 }
  ]
}

请注意，Delta 的指令始终从文档开头开始。并且由于简单的 retain 操作，我们永远不需要为 delete 或 insert 操作指定索引。

¥Note that a Delta's instructions always starts at the beginning of the document. And because of plain retain operations, we never need to specify an index for a delete or insert operation.

在线运行

¥Playground

试用一下 Quill，看看它的内容和变化是什么样子的。打开开发者控制台，以另一种方式查看增量。

¥Play around with Quill and take a look at how its content and changes look. Open your developer console for another view into the Deltas.