CKEditor 的使用方法

2月 20 2022 Plug-in

邊做筆記邊複習。

簡述

CKEditor 是一個所見即所得的文字編輯器，主要用途是給使用者編輯文字的環境，例如部落格裡面的編輯文章功能。

CKEditor 目前主要有 4、5 兩個版本，這兩者是不相容的，所以這篇會拿 5 來做教學。

備註 當初踩到的雷

在安裝編輯器跟套件的時候要特別注意「版本」，如果套件的版本比編輯器還新，像這樣：

1
2
3
4
5
6
7
8
9
{
  "name": "@ckeditor/ckeditor5-build-classic",
  "version": "19.0.0",  // -> 編輯器的版本
  "description": "The classic editor build of CKEditor 5 – the best browser-based rich text editor.",
  "devDependencies": {
    "@ckeditor/ckeditor5-ckfinder": "^19.0.0",
    "@ckeditor/ckeditor5-code-block": "^32.0.0", // -> 套件的版本
    "@ckeditor/ckeditor5-core": "^19.0.0",
  },

之後引入的時候就有機會碰到 duplicated modules（模組重複載入）的問題。

引入方式

  1. CDN 引入，如果你沒有安裝擴充套件的需求，那就用這個方式就好：
1
<script src="https://cdn.ckeditor.com/ckeditor5/32.0.0/classic/ckeditor.js"></script>
  1. 下載原始碼

目前有五個版本：

  • classic — the Classic editor
  • inline — the Inline editor
  • balloon — the Balloon editor
  • balloon-block — the Balloon block editor
  • decoupled-document — the Document editor

實際的差別可以去看官方文件，因為我也沒特別去看所以不清楚。

總之，最多人用的是 classic，所以這邊也會拿這個來用。

先到 這邊 下載原始碼：

1
git clone https://github.com/ckeditor/ckeditor5.git

備註：現在新版的 CKEditor5 已經整合到一個 Repository 了，不要下載錯版本，像這個就是舊版的：ckeditor5-build-classic。

接著只要根據路徑把 ckeditor.js 引入就 OK 了：

1
<script src="ckeditor5\packages\ckeditor5-build-classic\build\ckeditor.js"></script>

啟用方式

很簡單，只要這兩段 code 就搞定：

1
<textarea name="content" id="editor"></textarea>
1
2
3
4
5
6
7
8
<script src=".ckeditor5\packages\ckeditor5-build-classic\build\ckeditor.js"></script>
<script>
  ClassicEditor
    .create(document.querySelector('#editor'))
    .catch(error => {
      console.error(error);
    });
</script>

create 會根據 selector 來替換元素，所以不一定要 <textarea>，<div> 也行。

另外這很明顯是個 Promise，所以發生錯誤的話就會執行 catch 區塊，你可以在那邊看錯誤訊息。

一切順利的話你就會看到這個結果：

result

如果你沒有要安裝其他套件的話，到這邊就差不多了，有需求的話就繼續看下去吧。

安裝擴充功能

備註：安裝的方式有兩個，一種是改源碼重新 build，另一種是直接在 JS 裡面插入。這裡介紹的是第一種，如果你對第二種方式有興趣參考這裡。不過要切記，這兩個不可以混用，否則很有可能出問題。

備註：後來發現有更簡單的方式，官方有提供線上打包的服務，可以參考這裡

把原始碼下載下來後，會看到 ckeditor5-build-classic 這個資料夾，這裡說明一下資料結構：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
│   CHANGELOG.md
│   CONTRIBUTING.md
│   LICENSE.md
│   package.json  -> CKEditor 的所有資訊（很重要）
│   README.md
│
├───.github
│       PULL_REQUEST_TEMPLATE.md
│
├───build -> 打包後的檔案
│   │   ckeditor.js
│   │   ckeditor.js.map
│   │
│   └───translations       
│
├───sample -> 示範檔案（用這個能看 build 出來的編輯器長怎樣）
│       index.html
│
├───src -> 原始碼（程式的進入點）
│       ckeditor.js
│
└───tests -> 測試的地方
    │   ckeditor.js
    │
    └───manual

先說明一下安裝擴充套件的流程：

  1. npm install 你要安裝的擴充功能
  2. 到 src ckeditor.js 把套件引入跟設定
  3. 重新 build

不過在那之前，請務必先：

  • npm install 安裝所有 package.json 中的套件
  • npm install 安裝所有 package.json 中的套件
  • npm install 安裝所有 package.json 中的套件

因為它是用 webpack 來打包的，沒有先安裝好的話等一下 build 的時候會出錯。

安裝 Code blocks 套件

這邊拿 Code blocks 來當範例。不管安裝哪個套件流程都是一樣的，所以請務必弄懂這個流程。

接著照著文件的安裝說明來做：

1
2
# 在 ckeditor5-build-classic 這個資料夾下
npm install --save @ckeditor/ckeditor5-code-block

安裝完後 package.json 就會有紀錄了：

1
2
3
"dependencies": {
  "@ckeditor/ckeditor5-code-block": "^32.0.0"
}

引入及設定套件

接著打開 src 底下的 ckeditor.js，會看到像這樣的內容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
// The editor creator to use.
import ClassicEditorBase from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';

// 引入各種套件
import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
import UploadAdapter from '@ckeditor/ckeditor5-adapter-ckfinder/src/uploadadapter';
import Autoformat from '@ckeditor/ckeditor5-autoformat/src/autoformat';
import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
import BlockQuote from '@ckeditor/ckeditor5-block-quote/src/blockquote';
....


// build 時要載入的套件
ClassicEditor.builtinPlugins = [
  Essentials,
  UploadAdapter,
  Autoformat,
  Bold,
  Italic,
  BlockQuote,
  CKFinder,
  EasyImage,
  Heading,
  ...
];

// 設定編輯器的地方
ClassicEditor.defaultConfig = {
  // 工具列要顯示哪些 item
  toolbar: {
    items: [
      'heading',
      '|',
      'bold',
      'italic',
      'link',
      ...
    ]
  },
  // 圖片工具的設定
  image: {
    toolbar: [
      'imageStyle:full',
      'imageStyle:side',
      '|',
      'imageTextAlternative'
    ]
  },
  // 表格工具的設定
  table: {
    contentToolbar: [
      'tableColumn',
      'tableRow',
      'mergeTableCells'
    ]
  },
  // This value must be kept in sync with the language defined in webpack.config.js.
  language: 'en'
};

這邊只要做兩件事情就好：

  1. 把剛載好的套件 import 進來
  2. 把套件綁到 ClassicEditor.defaultConfig 下

一樣按照官方說明來做：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
// The editor creator to use.
import ClassicEditorBase from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';

// 引入各種套件
import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
import UploadAdapter from '@ckeditor/ckeditor5-adapter-ckfinder/src/uploadadapter';
import Autoformat from '@ckeditor/ckeditor5-autoformat/src/autoformat';
import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
import BlockQuote from '@ckeditor/ckeditor5-block-quote/src/blockquote';

// 剛載好的套件
import CodeBlock from '@ckeditor/ckeditor5-code-block/src/codeblock';
....


// build 時要載入的套件
ClassicEditor.builtinPlugins = [
  Essentials,
  UploadAdapter,
  Autoformat,
  Bold,
  Italic,
  BlockQuote,
  CKFinder,
  EasyImage,
  Heading,
  CodeBlock, // 加進去
  ...
];

// 設定每個套件的預設值
ClassicEditor.defaultConfig = {
  // 工具列要顯示哪些 item
  toolbar: {
    items: [
      'heading',
      '|',
      'bold',
      'italic',
      'link',
      ...
      'codeBlock' // 新增這個按鈕
    ]
  },
};

備註：套件設定的部分建議別動，要改的話去使用 CKEditor 的頁面在改就好。

重新編譯

最後一步最簡單啦，下這行指令就好：

1
npm run build

最後把編譯完的 ckeditor.js 引入就完成了。

怎麼取得編輯器的內容

  1. PHP

如果你是用 Form 表單來送出內容的話，那你可以在 PHP 裡面拿資料：

1
2
3
4
<form method="POST" action="result.php">
  <textarea name="content" id="editor"></textarea>
  <button class="btn">Send</button>
</form>
1
2
// result.php
$content = $_POST['content'];
  1. JavaScript

如果你是透過 AJAX 的話，參考這個做法：

1
2
<textarea name="content" id="editor"></textarea>
<button class="btn">send</button>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// 先宣告一個變數，等一下要儲存編輯器的實體
let editor = undefined;
ClassicEditor
  .create(document.querySelector('#editor'))
  .then( newEditor => {
    // 指定給變數
    editor = newEditor
  })
  .catch(error => {
    console.error(error);
  });
document.querySelector('.btn').addEventListener('click', () => {
  // 這裡就可以用 getData 來取得 HTML 內容
  console.log(editor.getData());
})

get_data

mentor-program-day69 highlight.js 的使用方法
Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now

×