[TOC] <!-- Deltas are a simple, yet expressive format that can be used to describe Quill's contents and changes. The format is essentially JSON, and is human readable, yet easily parsible by machines. Deltas can describe any Quill document, includes all text and formatting information, without the ambiguity and complexity of HTML. --> Delta被用做描述Quill编辑器的内容和变化，简单但表达力强的数据格式。这种格式本质上是一种JSON格式，人类可读同时及其也能容易识别。Delta能描述任意Quill内容，包括所有的文本、格式信息，并且没有HTML多义性及复杂性的缺点。 <!-- Don't be confused by its name Delta&mdash;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迷惑，Deltas(&Delta;增量)代表文档和文档的改变。如果将Deltas看做是一个文档到另一个文档的操作指令，那么Delta表示一个文档就是从空文档开始到现有文档的操作指令的表达。 <!-- Deltas are implemented as a separate [standalone library](https://github.com/quilljs/delta/), allowing its use outside of Quill. It is suitable for [Operational Transform](https://en.wikipedia.org/wiki/Operational_transformation) and can be used in realtime, Google Docs like applications. For a more in depth explanation behind Deltas, see [Designing the Delta Format](/guides/designing-the-delta-format.md). --> Delta被独立成一个[单独的库](https://github.com/quilljs/delta/),以便其能在Quill以外的地方使用。它非常适合[Operational Transform](https://en.wikipedia.org/wiki/Operational_transformation)，可以用于实时的，类似Google Docs的应用。想要更深入的了解Delta，请查看[设计Delta格式](guides/designing-the-delta-format.md). <!-- **Note:** It is not recommended to construct Deltas by hand&mdash;rather use the chainable [`insert()`](https://github.com/quilljs/delta#insert), [`delete()`](https://github.com/quilljs/delta#delete), and [`retain()`](https://github.com/quilljs/delta#retain) methods to create new Deltas. --> **注意**：不推荐手动构建Delta格式，推荐用链式操作[`insert()`](https://github.com/quilljs/delta#insert), [`delete()`](https://github.com/quilljs/delta#delete), and [`retain()`](https://github.com/quilljs/delta#retain) 新建Delta对象。 ## 文档 <!-- The Delta format is almost entirely self-explanatory&mdash;the example below describes the string "Gandalf the Grey" where "Gandalf" is bolded and "Grey" is colored #cccccc. --> Delta格式几乎是完全独立解析。下面这个示例中，描述了字符串"Gandalf the Grey"，其中"Gandalf"是加粗的，"Grey"的颜色是 #cccccc。 ```javascript { ops: [ { insert: 'Gandalf', attributes: { bold: true } }, { insert: ' the ' }, { insert: 'Grey', attributes: { color: '#cccccc' } } ] } ``` <!-- 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，描述内容实际上是一种特别的情况。上面的示例中更具体的说明了：插入加粗字符"Gandalf"、没有格式的 " the "，接下来插入带有颜色#cccccc的字符串"Grey"。当使用Delta来描述内容时，可以将其看作是delta执行于空文档所创建的内容。 <!-- 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&mdash;this is a choice that Quill makes, and can be modified if desired with [Parchment](https://github.com/quilljs/parchment/). --> 因为Delta是一种数据格式，所以它没有在内部定义`attribute`的键-值对。例如，Delta格式中没有规定颜色值必须是十六进制的。这是Quill做出的取舍，如果需要，可以用[Parchment](https://github.com/quilljs/parchment/)修改。 ### 嵌入 <!-- 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](https://github.com/quilljs/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. --> 对于非文本内容，如图像、公式，插入的值是对象。这个对象应该来确定其类型的键(key)。如果你是用[Parchment](https://github.com/quilljs/parchment/)自定义内容的话，这个键是`blotName`。和文本一样，嵌入对象仍需要 `attributes`来描述作用与这个嵌入对象上的格式。所有嵌入对象的长度都为1。 ```javascript { ops: [{ // An image link insert: { image: 'https://quilljs.com/assets/images/icon.png' }, attributes: { link: 'https://quilljs.com' } }] } ``` ### 行格式编排 <!-- Attributes associated with a newline character describes formatting for that line. --> 带有换行符的内容对应属性是描述一行的格式。 ```javascript { ops: [ { insert: 'The Two Towers' }, { insert: '\n', attributes: { header: 1 } }, { insert: 'Aragorn sped on up the hill.\n' } ] } //表示的内容：<h1>The Two Towers</h1><p>Aragorn sped on up the hill.</p> ``` <!-- 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文档须以换行符结尾，甚至在最后一行上没有格式设置。这样你始终有一个字符的位置来表示应用行格式。 <!-- 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. --> 很多行格式是独占的，例如，Quill不允许同一行同时作为标题和列表，尽管他们可以用Delta格式来表示。 ## 修改 <!-- When you register a listener for Quill's [`text-change`](/docs/api/#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. --> 当你监听 Quill的 [`text-change`](api/事件events.md)事件时，你会得到一个描述哪些内容改变了的参数。除了 `insert`操作以外，Delta可以还有`delete` 或 `retain`操作。 ### Delete 删除 <!-- The `delete` operation instructs exactly what it implies: delete the next number of characters. --> 删除操作必然明确指示：接下来删除的字符数。 ```javascript { ops: [ { delete: 10 } // 删除接下来的10个字符数 ] } ``` <!-- Since `delete` operations do not include *what* was deleted, a Delta is not reversible. --> Delta的删除操作是不可逆的，因为`delete` 操作没有包含被删除的内容。 ### Retain 保留 <!-- 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. --> `retain` 操作只表示不做修改的保留接下来指定数量的字符串。如果带有`attributes`值，则表示只保留这些字符串但要应用被`attributes`定义的格式。如果`attributes`定义的格式值为`null`表示移除文本原来的格式。 <!-- Starting with the above "Gandalf the Grey" example: --> 从上面提到的 "Gandalf the Grey" 示例开始： ```javascript // { // 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 } ] } ``` <!-- 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. --> 注意，Delta的指令总是从文档开头开始。因为有简单的`retain` ，所以我们不需要再为`delete` 或 `insert` 操作定义一个index值。 ### 演示 <!-- Play around Quill and take a look at how its content and changes look. Open your developer console for another view into the Deltas. --> 有关Quill的演示，输入观察内容及其变化。打开你的开发者控制台查看Delta数据。 <div data-height="470" data-theme-id="23269" data-slug-hash="dMQGmq" data-default-tab="result" data-embed-version="2" class='codepen'><pre><code></code></pre></div> <!-- script --> <script src="//codepen.io/assets/embed/ei.js"></script> <!-- script -->