Day 13：讀 Quill Editor API 技術文件

繼昨天的 Contents 相關的 API，今天來看看 Formatting 的部分。

format

根據使用者當前選擇的字串套用文字格式，回傳的 Delta 代表變更的內容。當使用者選擇字串長度為 0 時，代表是游標的狀態，對應的文字樣式則會變成啟動狀態，使用者接下來輸入的內容則會套用啟動的文字樣式。Source 一樣可以設定 user，api 或 silent。當呼叫的時候如果編輯器為禁用(disabled) 狀態，則會直接略過 source 為 user 的呼叫。

source 預設是 api

方法：

format(name: String, value: any, source: String = 'api'): Delta

範例：

quill.format('color', 'red');
quill.format('align', 'right');

formatLine

將選到的行數套用樣式，回傳的 Delta 代表變更的內容。關於可使用的樣式有哪些，可以參考官網文件 formats描述。這個方法主要是處理區塊 (block) 樣式，當呼叫的時候如果帶入的樣式是屬於行內 (inline) 樣式，則會沒有效果。要移除格式的話直接在 value 的參數傳入 false 即可。另外套用區塊樣式的時候，可能會在套用後導致使用者當前的選擇被取消，並且游標移動到新的位置。

source 預設是 api

方法：

formatLine(index: Number, length: Number, source: String = 'api'): Delta

formatLine(index: Number, length: Number, format: String, value: any, source: String = 'api'): Delta 

formatLine(index: Number, length: Number, formats: { [String]: any }, source: String = 'api'): Delta

範例：

quill.setText('Hello\nWorld!\n');
quill.formatLine(1, 2); // 沒有給樣式的話，預設套用的樣式是 bold
quill.formatLine(1, 2, 'align', 'right'); // 第一行置右
quill.formatLine(4, 4, 'align', 'center'); // 兩行都置中

// 套用多個區塊樣式
quill.formatLine(0, 5, {
  list: 'bullet',
  align: 'right',
});

format VS formatLine

最主要的差別就是 format 用在更改選取範圍內的特定格式，例如字體大小、顏色、粗體等。而 formatLine 處理的是整行的樣式，例如列表、對齊方式等。

formatText

一樣是在編輯器針對選定的範圍套用文字的樣式，回傳的是內容變更的 Delta，如果要移除文字樣式，則直接在對應樣式的值帶入 false 即可移除。如果是操作 block 相關的樣式，使用者的選擇範圍可能不會保留。Source 的來源有 user，api，以及 silent，當編輯器為 disabled 狀態則會直接無視 source 為 user 的呼叫。

source 預設是 api

方法：

formatText(index: Number, length: Number, source: String = 'api'): Delta 

formatText(index: Number, length: Number, format: String, value: any, source: String = 'api'): Delta

formatText(index: Number, length: Number, formats: { [String]: any }, source: String = 'api'): Delta

範例：

quill.setText('Hello\nWorld!\n');
quill.formatText(0, 5, 'bold', true); // 將 Hello 設為粗體
quill.formatText(0, 5, { // 將 Hello 解除粗體，並設為藍色 
  'bold': false, 
  'color': 'rgb(0, 0, 255)'  
});
quill.formatText(5, 1, 'align', 'right'); // 將 Hello 的那一行置右

getFormat

這個方法可以讓我們查詢特定範圍內文字的格式。如果範圍內的所有文字共用相同的格式，則會回傳該格式。如果有不同的真值 (truthy value)，則會回傳所有的真值在陣列中。當不帶參數呼叫此方法，將針對當前使用者選取的範圍進行操作。

source 預設是 api

方法：

getFormat(range: Range = current): { [String]: any }
getFormat(index: Number, length: Number = 0): { [String]: any }

範例：

// 假設設定一段文字 Hello World!，並設定樣式
quill.setText('Hello World!');
quill.formatText(0, 2, 'bold', true);
quill.formatText(1, 2, 'italic', true);
quill.getFormat(0, 2); // { bold: true }
quill.getFormat(1, 1); // { bold: true, italic: true }

quill.formatText(0, 2, 'color', 'red');
quill.formatText(2, 1, 'color', 'blue');
quill.getFormat(0, 3); // { color: ['red', 'blue'] }

quill.setSelection(3);
quill.getFormat(); // { italic: true, color: 'blue' }

quill.format('strike', true);
quill.getFormat(); // { italic: true, color: 'blue', strike: true }

quill.formatLine(0, 1, 'align', 'right');
quill.getFormat(); // { italic: true, color: 'blue', strike: true, // align: 'right' }

removeFormat

將選定的範圍內刪除所有的格式及嵌入內容，並回復到沒有格式的狀態。回傳的 Delta 代表變更的操作，如果範圍內包含到 block format，也會一併移除。因此使用者的選取狀態可能不會被保留。Source 可以是 user，api 或 silent。當編輯器為 disabled 狀態時，source 為 user 的呼叫將會被忽略。

source 預設是 api

方法：

removeFormat(index: Number, length: Number, source: String = 'api'): Delta

範例：

quill.setContents([
  { insert: 'Hello', { bold: true } },
  { insert: '\n', { align: 'center' } },
  { insert: { formula: 'x^2' } },
  { insert: '\n', { align: 'center' } },
  { insert: 'World', { italic: true }},
  { insert: '\n', { align: 'center' } }
]);

quill.removeFormat(3, 7);
// 編輯器在執行之後內容會變成
// [
// { insert: 'Hel', { bold: true } },
// { insert: 'lo\n\nWo' },
// { insert: 'rld', { italic: true }},
// { insert: '\n', { align: 'center' } }
// ]

小結

今天嘗試使用格式化相關的 API，基本上使用的方式都差不多，但我們還沒討論到 Format 還有哪些可以使用，剛才的介紹中也有提到這篇文件有列出所有支援的格式，要找時間來實驗看看並感受一下。

雜記

明天就開始一小段假期，不過按照往年的慣例，都會先回去宜蘭開車回台南拜拜，希望這次塞車不要塞的太久QQ，儘管早上四點半就起床，五點就出門了，到了七八點還是會開始塞。印象中過台中之前都滿大的機會遇到塞車的情況，還好可以跟弟弟輪流開，不至於累到不行 XD

祝中秋佳節愉快 :)

Reference

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

Jeff Wu's Note