Quill基本使用和配置 - DevUI

DevUI團隊發表於2021-06-21
UIdev

DevUI 是一款面向企業中後臺產品的開源前端解決方案，它倡導沉浸、靈活、至簡的設計價值觀，提倡設計者為真實的需求服務，為多數人的設計，拒絕譁眾取寵、取悅眼球的設計。如果你正在開發 ToB 的工具類產品，DevUI 將是一個很不錯的選擇！

Kagol.png

以下文章和本文相關，也許你也會喜歡：

《現代富文字編輯器Quill的模組化機制》

《Quill富文字編輯器的實踐》

《如何將龍插入到編輯器中？》

《今天是兒童節，整個貪吃蛇到編輯器裡玩兒吧》

《現代富文字編輯器Quill的內容渲染機制》

引言

之前在HWEB大前端技術分享會上給大家分享過 Quill 的一些實踐，不過由於時間關係只講了個大概，後續打算深入淺出地對 Quill 做一個詳細的介紹。

這個系列打算從實踐的角度去講 Quill 富文字編輯器，先從 Quill 的基本使用開始吧！

極簡方式使用 Quill

快速開始三部曲：

  • 安裝
  • 引入
  • 使用
// 安裝
npm i quill

<div id="editor"></div>

// 引入
import Quill from 'quill';

// 使用
const quill = new Quill('#editor');

雖然我們已經初始化了 Quill 例項，但是在頁面中卻什麼也看不到。

極簡Quill.png

雖然看上去什麼也沒有，但是我們點選空白處，會發現有一個游標，並且可以輸入內容，並給內容增加格式（由於沒有工具欄，只能通過 Quill 快捷鍵Ctrl+B增加格式），以下是動畫效果：

快速開始.gif

雖然只是一個極簡版的富文字編輯器，不過加上邊框和按鈕，就是一個基礎版的掘金評論框（還差插入表情和圖片）?

基礎版掘金評論框.png

這是使用 Quill 最簡單的方式。

加一些配置選項吧

配置編輯器容器元素 container

Quill 類一共有兩個引數，第一個引數是必選的編輯器容器元素container，可以是一個CSS選擇器，比如前面的#editor，也可以是一個DOM元素，比如：

const container = document.getElementById('editor');
// const container = document.querySelector('#editor');
// const container = $('#editor').get(0);
const quill = new Quill(container);

如果容器裡面已經有一些 HTML 元素，那麼初始化 Quill 的時候，那些元素也會渲染出來，比如：

<div id="editor">
  <p>DevUI：面向企業中後臺的前端開源解決方案</p>
  <h2>宗旨與法則</h2>
  <p>規範的元件化的目的不是為了限制創造，而是為了創造者更確定、科學、高效。所有行為決策的價值歸依是產品業務。產品業務永遠比元件化本身更重要，業務第一。</p>
  <p>規範不是絕對、教條、冷漠、強制的，實際工作中總會有新增需求、存優化空間、情感化設計需求超出一般通用規範。保持克制的同時，允許基於強烈業務需求的規範突破；之後如果有足夠的理由迭代出元件，那麼就進行元件深化。</p>
  <h2>設計語言</h2>
  <p>DevUI的價值觀奠定了 DevCloud品牌的基礎。它是 DevCloud 的設計師們思考、工作的產物，反映了 DevCloud 的產品文化、設計理念和對客戶的承諾。DevUI的這些價值觀貫穿於所有產品和麵向客戶的溝通和內容中。同時，它是 DevUI 設計原則的源頭，為具體的設計方法提供啟發和指引。</p>
  <p>DevUI倡導<code>沉浸</code>、<code>靈活</code>、<code>致簡</code>的設計價值觀，提倡設計者為真實的需求服務，為多數人的設計，拒絕譁眾取寵、取悅眼球的設計。</p>
  <h2>致簡</h2>
  <p>DevUI堅持以使用者為中心去進行設計，注重直觀可達性，把服務示例化以幫助使用者快速融入到使用中去。同時， DevUI提供大量的快捷鍵，簡化使用的流程、提高操作效率。</p>
  <h2>沉浸</h2>
  <p>DevUI的沉浸式體驗包括人的感官體驗和認知體驗，當使用者的個人技能與面對的挑戰互相匹配，並且長時間處在穩定狀態時，使用者達到心流狀態並且不易被外界因素所干擾。</p>
  <p>在產品設計中，DevUI專注在降低使用者在完成任務目標時的認知阻力中。為此，DevUI同時提供多種不同的切換頁面的途徑，包括麵包屑、快捷鍵、按鈕和連結等，方便使用者隨時快速、連續地切換頁面，到達自己所需的頁面，使使用者處於流暢的體驗中，減輕尋找資訊的焦慮感。</p>
  <h2>靈活</h2>
  <p>DevUI提供超過60個獨立原子級元件，可以自由組合，像搭積木一樣，用小元件搭建出符合自身產品需要的分子級元件，進而搭建出自己的業務系統。</p>
</div>

渲染出來的編輯器效果：

渲染初始HTML.png

配置選項 options

第二個引數是可選的配置選項options，options是一個JSON物件，比如我們想給我們的編輯器增加一個主題，使它不再那麼單調。

const quill = new Quill('#editor', {
  theme: 'snow'
});

另外需要引入該主題對應的樣式：

@import 'quill/dist/quill.snow.css';

這時我們看到編輯器已經有一個工具欄。

snow主題.png

並且可以通過工具欄對編輯器的內容進行操作，比如給DevUI增加一個超連結：

配置snow主題.gif

除了snow主題，Quill 還內建了一個bubble氣泡主題，配置方式和snow主題一樣：

  • 引入主題樣式
  • 在options裡配置主題
// 引入bubble主題樣式
@import 'quill/dist/quill.bubble.css';

const quill = new Quill('#editor', {
  theme: 'bubble' // 配置 bubble 主題
});

效果如下：

bubble主題.png

bubble主題沒有顯性的工具欄，它會在你選中編輯器中的文字時，在選中文字的下方顯示一個氣泡工具欄，從而對文字進行格式化操作，比如給選中的段落增加引用格式：

bubble主題.gif

更多配置選項

Quill 不僅僅可以配置主題，options一共支援8個配置選項：

  • bounds 編輯器內浮框的邊界
  • debug debug級別
  • formats 格式白名單
  • modules 模組
  • placeholder 佔位文字
  • readOnly 只讀模式
  • scrollingContainer 滾動容器
  • theme 主題

formats 格式白名單

這個配置項非常有用，比如剛剛提到的掘金評論框，我們發現評論框裡只能插入純文字，其他格式都不允許，即使時貼上進來的格式化文字也會變成純文字。

在 Quill 裡很容易實現，只需要配置formats為空陣列即可。

const quill = new Quill('#editor', {
  theme: 'snow',
  formats: []
});

注意這裡的formats格式白名單，控制的是內容實際的格式，和設定格式的渠道無關，比如formats設定為空，那麼無論是：

  • 通過工具欄設定格式
  • 還是通過快捷鍵（比如Ctrl+B）設定格式
  • 抑或是貼上帶格式的文字
    都是無法設定格式的。

如果我們想保留一部分格式，比如只保留粗體和列表兩種格式：

const quill = new Quill('#editor', {
  theme: 'snow',
  formats: [ 'bold', 'list' ]
});

Quill 一共支援11種行內格式：

  • background
  • bold
  • color
  • font
  • code
  • italic
  • link
  • size
  • strike
  • script
  • underline

7種塊級格式：

  • blockquote
  • header
  • indent
  • list
  • align
  • direction
  • code-block

3種嵌入格式：

  • formula
  • image
  • video

不配置formats選項，會預設支援所有的21種格式。

placeholder 佔位文字

我們發現掘金的評論框在沒有輸入內容時，會有一個輸入評論...的佔位文字。

圖片.png

這可以很容易地通過配置placeholder選項實現。

const quill = new Quill('#editor', {
  formats: [],
  placeholder: '輸入評論...',
});

placeholder.png

readOnly 只讀模式

通過配置readOnly可以實現：

初始狀態編輯器是閱讀態，不可以編輯，可以通過點選編輯按鈕讓編輯器變成編輯態。

由於掘金的評論框不支援編輯，就不拿它舉例子。

以 DevCloud 看板專案的評論框為例，初始狀態下評論是不可編輯的，點選編輯按鈕，變成可編輯狀態，並且顯示工具欄、儲存按鈕等元素，點選儲存按鈕，新增的內容被儲存，編輯器變成只讀態。

readOnly.gif

modules 模組配置

這個配置項放在最後並不代表它不重要，恰恰相反，這是 Quill 中最重量級也是最常用的配置。

在之前的文章中，給大家介紹過 Quill 的模組化機制，這個配置項就是用來配置 Quill 的模組的。

在Quill的模組化機制一文中，我們提到

Quill 一共有6個內建模組：

  • Clipboard 貼上版
  • History 操作歷史
  • Keyboard 鍵盤事件
  • Syntax 語法高亮
  • Toolbar 工具欄
  • Uploader 檔案上傳

每個模組的用途詳見Quill內建模組章節。

modules選項可以用來配置這些模組。

配置 toolbar 模組

Quill 預設只在工具欄中顯示一部分格式化按鈕，裡面沒有插入圖片的按鈕，我們可以通過配置toolbar模組來增加。

const quill = new Quill('#editor', {
  theme: 'snow',
  modules: {
    toolbar: [
      // 預設的
      [{ header: [1, 2, 3, false] }],
      ['bold', 'italic', 'underline', 'link'],
      [{ list: 'ordered'}, { list: 'bullet' }],
      ['clean'],
      
       // 新增的
      ['image']
    ]
  }
});

插入圖片.png

如果想做一個掘金這樣的富文字編輯器，也非常簡單。

掘金富文字.png

掘金的富文字編輯器主要包含以下工具欄按鈕：

  • 加粗
  • 斜體
  • 下劃線
  • 一級/二級標題
  • 引用
  • 程式碼塊
  • 行內程式碼
  • 無序列表
  • 有序列表
  • 超連結
  • 插入圖片

使用 Quill 實現，需要這樣配置toolbar模組。

const quill = new Quill('#editor', {
  theme: 'snow',
  modules: {
    toolbar: [
      'bold', 'italic', 'underline', 
      { header: 1 }, { header: 2 },
      'blockquote', 'code-block', 'code', 'link',
      { list: 'ordered'}, { list: 'bullet' },
      'image',
    ]
  }
});

稍微修改下樣式，就能做出一個和掘金富文字編輯器差不多的富文字編輯器啦，效果如下：

掘金編輯器效果.png

以下是和掘金實際的富文字編輯器的對比圖：

對比圖.png

對比以上效果對比圖，除了工具欄的 icon 使用的是掘金 Markdown 編輯器的 icon 之外，其他幾乎是一樣的。

配置 keyboard 模組

除了工具欄模組，我們還可以配置別的模組，比如快捷鍵模組keyboard，keyboard模組預設支援很多快捷鍵，比如：

  • 加粗的快捷鍵是Ctrl+B；
  • 超連結的快捷鍵是Ctrl+K;
  • 撤銷/回退的快捷鍵是Ctrl+Z/Y。

但它不支援刪除線的快捷鍵，如果我們想定製刪除線的快捷鍵，假設是Ctrl+Shift+S，可以這樣配置：

const quill = new Quill('#editor', {
  theme: 'snow',
  modules: {
    toolbar: [
      // 預設的
      [{ header: [1, 2, 3, false] }],
      ['bold', 'italic', 'underline', 'link'],
      [{ list: 'ordered'}, { list: 'bullet' }],
      ['clean'],
      ['image']
    ],
    
    // 新增的
    keyboard: {
      bindings: {
        strike: {
          key: 'S',
          ctrlKey: true,
          shiftKey: true,
          handler: function(range, context) {
            // 獲取當前游標所在文字的格式
            const format = this.quill.getFormat(range);
            // 增加/取消刪除線
            this.quill.format('strike', !format.strike);
          }
        },
      }
    },
  }
});

配置 history 模組

Quill 內建的history模組，每隔1s會記錄一次操作歷史，並放入歷史操作棧（最大100）中，便於撤銷/回退操作。

如果我們不想記錄得那麼頻繁，想2s記錄一次，另外我們想增加操作棧的大小，最大記錄200次操作歷史，可以這樣配置：

const quill = new Quill('#editor', {
  theme: 'snow',
  modules: {
    toolbar: [
      // 預設的
      [{ header: [1, 2, 3, false] }],
      ['bold', 'italic', 'underline', 'link'],
      [{ list: 'ordered'}, { list: 'bullet' }],
      ['clean'],
      ['image']
    ],
    keyboard: {
      bindings: {
        strike: {
          key: 'S',
          ctrlKey: true,
          shiftKey: true,
          handler: function(range, context) {
            // 獲取當前游標所在文字的格式
            const format = this.quill.getFormat(range);
            // 增加/取消刪除線
            this.quill.format('strike', !format.strike);
          }
        },
      }
    },
    
    // 新增的
    history: {
      delay: 2000, // 2s記錄一次操作歷史
      maxStack: 200, // 最大記錄200次操作歷史
    }
  }
});

小結

本文主要介紹了 Quill 的基本用法，以及如何通過 options 選項配置 Quill。

後續將介紹更多關於 Quill 的實踐，關注 DevUI 不迷路?。

歡迎加DevUI小助手微信：devui-official，一起討論Angular技術和前端技術。

歡迎關注我們DevUI元件庫，點亮我們的小星星?：

https://github.com/devcloudfe/ng-devui

也歡迎使用DevUI新發布的DevUI Admin系統，開箱即用，10分鐘搭建一個美觀大氣的後臺管理系統！

加入我們

我們是DevUI團隊，歡迎來這裡和我們一起打造優雅高效的人機設計/研發體系。招聘郵箱：muyang2@huawei.com。

文/DevUI Kagol

往期文章推薦

《Angular Schematics在DevUI Admin中的實踐》

《現代富文字編輯器Quill的模組化機制》

《Quill富文字編輯器的實踐》

《如何將龍插入到編輯器中？》

《今天是兒童節，整個貪吃蛇到編輯器裡玩兒吧》

相關文章