今天初步探討 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 屬性,這個屬性是一個操作陣列。每個操作都是一個物件,包含 insertdeleteretain 等屬性,分別代表插入文字、刪除文字、保留文字等操作。

以下是一個 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' 
    } 
  }] 
}

關於 BoltNameParchment 的介紹,我們之後再來仔細探討。(又挖坑…) XD

小結

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

雜記

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

Reference

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