Day 11：讀 Quill Editor API 技術文件

今天開始來細看 Quill Editor 的技術文件，看看 Quill 有哪些方法可以使用。同時也準備了範例練習，實際呼叫並觀察也許會比較有感覺。這會是一段細節探索的旅程。

關於 `Source`

在閱讀技術文件的時候，有部分的 function 會提供 Source 的參數名稱，稍微研究了一下。

API：當更改的事件來自 API 的呼叫，例如直接用 JavaScript 呼叫 Instance 的 function
User：當變更來自使用者的操作時，例如：使用者在編輯器打字輸入內容、貼上圖片或是修改文字樣式。
Silent：此選項允許我們在不觸發任何 Quill 事件的情況下進行更改。這在某些情況下很實用，例如，我們想要在不通知其他程式的情況下更新編輯器的內容。

大部分的情況是不需要自訂設定這些值，只有在較特殊的情況下，需要額外設置以更精確的控制編輯的行為。例如：

// 使用 'api' 作為 source，代表這個更改是由 API 控制的
quill.format('bold', true, 'api'); 

// 使用 'user' 作為 source，代表這個更改是模擬使用者操作
quill.format('italic', true, 'user');

透過這樣的分別使用，我們可以在事件監聽或其他處理邏輯中區分更改的來源，進而執行不同的操作或處理。例如我們只對使用者所做的更改進行特定的處理，並忽略由 API 控制的更改。透過 source 的設置就讓我們滿足這樣的需求。

deleteText：在指定位置刪除文字

刪除的來源可以是從 user, api 或 silent。當編輯器狀態為 disabled 時，會直接忽略掉從 user 來的呼叫

方法：

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

範例：

quill.deleteText(4, 6) // 從第 4 個位置，刪除長度 6 的內容

getContents：獲取編輯器指定位置與長度的內容

獲取編輯器的內容以及格式資料，收到的是 Delta 物件。可選參數有兩個：

index：指定獲取內容的起始索引，預設是從 0
length：指定要獲取內容的長度，預設 remaining 是指從起始索引後的剩餘內容

方法：

getContents(index: Number = 0, length: Number = remaining): Delta

範例：

// 獲取完整內容的 Delta
const delta = quill.getContents();

// 獲取部分內容的 Delta
const delta = quill.getContents(27, 5);

getLength：獲取編輯器內容的長度

獲取編輯器內容的長度。需要注意的是，即使 Quill 為空，仍然有一個由 ‘\n’ 表示的空行，因此 getLength 將返回 1。

方法：

getLength(): Number

範例：

const length = quill.getLength();

getText：獲取指定位置與長度的文本內容

獲取編輯器的字串內容，非字串的內容會直接省略，因此返回的字串長度可能會比呼叫 getLength 回傳的編輯器長度短些。這邊一樣要留意的是，即使編輯器是空的沒有內容，仍然會留一個空行，所以在這樣的情況將會返回 \n。

index：指定獲取內容的起始索引，預設是從 0
length：指定要獲取內容的長度，預設 remaining 是指從起始索引後的剩餘內容

方法：

getText(index: Number = 0, length: Number = remaining): String

範例：

// 獲取從 0 開始，長度為 10 的文本內容
const text = quill.getText(0, 10);

小結

今天開始仔細閱讀技術文件，會相對的比較乏味，但是能徹底的去看每個方法及參數要如何使用，知道自己有哪些武器可以用，對於特殊的需求也比較能找到合適的方法來實現。

雜記

由於中秋節快到了，開始收到各種月餅禮盒，周遭也開始出現柚子，雖然還沒開始烤肉，但希望中秋之後別長太多肥肉出來，剛轉換跑道一陣子，還在適應節奏的階段，需要找到合適的運動時間，目前看來只剩下早上了，下班後加上通勤時間到健身房，運動完回家洗完澡也差不多到睡覺的時間了，最近嘗試調整起床的時間，先從六點半開始觀察看看囉…XD

Reference

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

Jeff Wu's Note