Day 8：Quill Editor 的資料物件

今天初步探討 Quill Editor 資料物件之一，Delta，就一起來了解一下吧。

什麼是 Delta 物件？

不要被 Delta 這酷酷的名字給嚇到，它其實是很單純的東西。

首先我們將官網文件的描述翻譯來看：

Delta 是一種簡單但富有表現力的格式，可用於描述 Quill 的內容和變化。這個格式是 JSON 的嚴格子集，可讀性高，並且機器也能容易解析。Delta 可以描述任何 Quill 文件，包含所有文字和格式資訊，並去除 HTML 的歧義與複雜性。

Delta 是 Quill Editor 使用的資料物件，它同時也作為獨立的儲存庫，使 Delta 可以在 Quill 外的情境中被使用。主要用途在處理操作轉換（Operational Transform），並且可以套用到即時協同編輯的應用，像 Google Docs，之後我們再來深入了解 Delta 的格式設計概念。

因此，Delta 主要用來儲存編輯器的內容，它由一系列的操作物件組成，每個操作物件代表一個對內容的變更，例如插入文字、刪除內容、新增樣式等。Delta 的結構主要是以操作物件（OPS Object）的陣列方式呈現。

另外需要注意的一點是：不建議手動建立 Delta 物件，應該要透過可連結 Deltas 物件的方法像是：insert()、delete()，和 keep() 等方法來建立新的 Delta。

當 Delta 為文件內容的描述

每個 Delta 物件都包含一個 ops 屬性，這個屬性是一個操作陣列。每個操作都是一個物件，包含 insert、delete、retain 等屬性，分別代表插入文字、刪除文字、保留文字等操作。

以下是一個 Delta 物件的範例：

{
  ops: [
    { insert: 'Hello, ' },
    { insert: 'world', attributes: { bold: true } },
    { insert: '!' },
  ]
}

在這個範例中，Delta 物件表示一個包含「Hello, 」和「world」（加粗樣式）兩個片段的內容，是不是非常容易閱讀及理解呢？上面有提到，Delta 是用來描述文件內容及變更的內容，而當 Deltas 用於描述內容時，當套用到空白的文件時，可以將其視為要建立的內容。

Delta ops 的屬性：

insert：插入文字，可以指定要插入的文字內容。
delete：刪除文字，可以指定要刪除的文字數量。
retain：保留文字，可以指定要保留的文字數量。
attributes：操作的屬性，例如文字樣式、顏色等。

操作的順序和組合：

Delta 的操作按照順序應用於文本，從左到右。它們可以組合在一起，以建立完整的編輯器內容。例如 Delta 物件表示在游標的位置插入「Hello, world!」這段文字：

{
  ops: [
    { insert: 'Hello, world!' },
  ]
}

操作的應用：

我們可以使用 Quill Editor 提供的 setContents 方法，將 Delta 物件設置到編輯器中。這樣就能夠在編輯器中動態修改內容。

  setEditorContent() {
    const delta = {
      ops: [{ insert: 'Hello, world!' }],
    };
    
    this.quillEditor.setContents(delta as any);
  }

Embeds 嵌入式內容：

除了文字內容與樣式的資料，Delta 也可以描述嵌入式 (Embed) 的內容，例如：圖片、超連結或數學公式。這類型的內容在 Delta 物件中必須要有一個描述該類型的 key，而這個 key 同時也是 bolt 的名稱，如果有用 parchment 來建立自訂內容，嵌入式內容也可以像文字一樣擁有 attributes 的 key ，讓嵌入的內容也能有格式的設定。另外所有嵌入式內容的在編輯器中的內容長度 length 均為 1。

{
  ops: [{ 
    // 圖片連結 
    insert: { 
      image: 'https://quilljs.com/assets/images/icon.png' 
    }, 
    attributes: { 
      link: 'https://quilljs.com' 
    } 
  }] 
}

關於 BoltName 與 Parchment 的介紹，我們之後再來仔細探討。(~~又挖坑…~~) XD

小結

今天初步了解 Quill Editor 使用的 Delta 物件，在編輯器的處理情境中，我們有時候會需要利用 Delta 處理編輯器的內容，透過 Delta 可以解析文本內容，並依照專案需求進一步的處理資料，最後利用內建的方法將處理後的內容更新回編輯器，因此要能對 Quill 得心應手，對於 Delta 物件的理解也是很重要的一環。

雜記

本來還煩惱著要怎麼安排週末的行程，因為週日要到台中參加教師節聚餐，同時還要記著上來日更文章，但週六是要補班的，然後昨天才知道原來今天不需要補班，還好是昨天就知道，如果今天匆匆到公司之後才發現，大概會很錯愕吧，雖然接著回老家非常方便，站點就在展覽館旁邊而已 XD

Reference

Delta - Quill Rich Text Editor (quilljs.com)

文章同步發表於2023 iThome 鐵人賽

Jeff Wu's Note