Day 12：讀 Quill Editor API 技術文件

今天就繼續來看 Content 相關的 API 後半段。

insertEmbed

將嵌入式內容插入編輯器，return 為更改後的 Delta 物件。source 可以是 user、api 或 silent。當編輯器是 disabled 狀態時，當 source 設為 user 的呼叫則會被忽略。

index 可以選擇要插入的位置索引值

方法：

insertEmbed(index: Number, type: String, value: any, source: String = 'api'): Delta

範例：

quill.insertEmbed(10, 'image', 'https://quilljs.com/images/cloud.png');

insertText

顧名思義將文字插入編輯器，可以選擇使用指定格式或多種格式。return 收到的是更新後的 Delta 物件。source 可以是 user、api 或 silent。當編輯器 disabled 時，source 為 user 的呼叫將直接略過。

方法共有三種，後兩者的差別在於 format 可以設一個或多個文字格式。

insertText(index: Number, text: String, source: String = 'api'): Delta insertText(index: Number, text: String, format: String, value: any, source: String = 'api'): Delta 
insertText(index: Number, text: String, formats: { [String]: any }, source: String = 'api'): Delta

範例：

quill.insertText(0, 'Hello'); 
quill.insertText(3, 'Hello', 'bold', true); 
quill.insertText(8, 'Quill', { 'color': '#ffff00', 'italic': true });

setContents

將參數的內容覆蓋編輯器。內容必須以換行符號 \n 結尾。return 收到的是更新後的 Delta。如果給定 Delta 沒有無效操作，這將與傳入的 Delta 相同。source 可以為 user、api 或 silent。當編輯器是 disabled 狀態時，當source 為 user 的呼叫則會被忽略。

方法：

setContents(delta: Delta, source: String = 'api'): Delta

範例：

// 使用 new Delta() 新增 Delta 物件
const delta = new Delta()
    .insert('This is a title')
    .insert('\n', { header: 1 })
    .insert('This is a subtitle \n', {header: 2, color: 'red' })
    .insert('The description is Hello World', {
    bold: true,
    color: 'purple',
    });
quill.setContents(delta);

上面這個範例可以觀察到套用 header 的變化，除了從 text-change 觀察到的套用方式，如果想要在一個 insert 就實現樣式與 header 格式套用，可以在文字內容的最後加上換行符號，這樣加上 header 在 attribute 上才會有效果。

setText

將純文字內容覆蓋到編輯器，return 收到的是更新後的 Delta，文字內容必須以換行符號做結尾，沒有加上的話，編輯器會另外加上。與 setContents 不同的是，setText 只能將純文字覆蓋到編輯器，而 setContents 的文字內容可以包含不同的格式。source 可以為 user、api 或 silent，預設是 api。當編輯器是 disabled 狀態時，當source 為 user 的呼叫則會被忽略。

方法：

setText(text: String, source: String = 'api'): Delta

範例：

quill.setText('Hello\n');

updateContents

將 Delta 資料更新到編輯器，return 收到的是更新操作的 Delta。如果傳入的 Delta 沒有不合法的操作，return 收到的 Delta 則會是相同的內容。舉例來說，當編輯器沒有內容，但仍然執行 retain(6) 的話，實際上回傳的 Delta 中的 retain 會只有 1，因為空白的編輯器會預設一個換行符號，因此長度只有 1 可以 retain。
另外，即使執行 delete(5)，收到的 Delta 變化也不會有看到 ops 中有 delete 的操作，畢竟編輯器沒有內容可以讓我們刪除。

方法：

updateContents(delta: Delta, source: String = 'api'): Delta

範例：

// 假設編輯器當前的內容 [{ insert: 'Hello World!' }]
quill.updateContents(new Delta()
  .retain(6) // Keep 'Hello '
  .delete(5) // 'World' is deleted
  .insert('Quill')
  .retain(1, { bold: true }) // Apply bold to exclamation mark
);
// 編輯器現在會變成 [
//   { insert: 'Hello Quill' },
//   { insert: '!', attributes: { bold: true} }
// ]

小結

在實際看過每個方法及體驗過使用方式後，對於 Contents API 的運用有初步的認識，並在不同的情境下選擇適合的 API ，透過帶入不同參數的呼叫方式實現功能，我們也可以在特殊情況自訂 source 來決定保留或跳過編輯器的觸發機制，明天接著進入到 Formatting 的章節，也就是套用文字格式。

雜記

最近午餐跟著其他同事點外賣，不過也許是上班日的關係，在尖峰時段單點東西似乎特別容易漏掉，漏餐的話，幫忙開團的同事還要確認是否有其他同事也沒拿到，然後還要處理退款的申請，再次感謝願意開團的同事 XD。看來以後在尖峰時段還是盡量點套餐比較保險…也許吧XD

Reference

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

Jeff Wu's Note