[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 -->