README
Aotter-Text-Editor
一個可以橫跨Vanilla JS, Vue, React, Angular和Native App的冨文本編輯器 預計含有以下功能:
- Web端跨框架共用 (實作完成)
- Web <=> App 共用 (已實作,待測試)
- 來源支持HTML及Delta格式 (實作完成)
- 支持輸出HTML及Delta格式 (可輸出Delta)
- 支持單一頁面多編輯器 (實作完成)
- 支持多人同步編輯 (待實作)
- 支持離線編輯 (待實作)
Demo
http://aotter-text-editor.surge.sh/
Guide for Web
【快速上手】
Aotter-Text-Editor使用Web Component實作,並暴露一個HTML標籤:<aotter-text-editor>
使用前請安裝aotter-text-editor:
npm i aotter-text-editor
接著,在.html
裡面使用如下:
<html>
<head>
<script src="./node_modules/aotter-text-editor/dist/aotter-text-editor/aotter-text-editor.js"></script>
</head>
<body>
<aotter-text-editor />
</body>
</html>
==或是直接下載唯一必要檔案aotter-text-editor.js==
【Vue 使用方式】
STEP.1 安裝
npm i aotter-text-editor
STEP.2 修改main.js
// main.js
import Vue from 'vue';
import App from './App.vue';
import { defineCustomElements, applyPolyfills } from 'aotter-text-editor/loader'
Vue.config.productionTip = false;
// 告訴Vue將其視為普通HTML Element, 而非Vue Component
Vue.config.ignoredElements = ['aotter-text-editor'];
applyPolyfills().then(() => {
defineCustomElements(window);
});
new Vue({
render: h => h(App)
}).$mount('#app');
STEP.3 使用
// App.vue
<template>
<div>
<aotter-text-editor></aotter-text-editor>
</div>
</template>
【Nuxt 使用方式】
STEP.1 安裝
npm i aotter-text-editor
STEP.2 修改nuxt.config.js設定
// nuxt.config.js
export default {
// 其餘的nuxt config 內容
plugins: [
{ src: '~/plugins/aotter-text-editor', mode: 'client' }
],
ignoredElements: [
// 告訴Vue將其視為普通HTML Element, 而非Vue Component
'aotter-text-editor'
],
}
STEP.3 新增Plugin
// ~/plugins/aotter-text-editor.js
import { defineCustomElements, applyPolyfills } from 'aotter-text-editor/loader'
applyPolyfills().then(() => {
defineCustomElements(window)
})
STEP.4 使用
// ~/pages/index.vue
<template>
<div>
<aotter-text-editor></aotter-text-editor>
</div>
</template>
【APIs for Web】
<aotter-text-editor>
接受兩種方式傳入初始的編輯器內容
方式1: 透過HTML Attribute
content
接受Delta格式的字串
<aotter-text-editor
content='
[{
"attributes": { "color": "red" },
"insert": "標題"
}, {
"attributes": { "header": 1 },
"insert": "\n"
}, {
"insert": "Lorem ipsum dolor sit amet, consectetur adipisicing elit. Totam, magnam\n"
}]
'
/>
方式2: 透過內部的HTML
使用此種方式時,樣式需使用inline style定義
<aotter-text-editor>
<h1 style="color: red">標題</h1>
<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Totam, magnam</p>
</aotter-text-editor>
==注意:當兩種方式同時使用時,會以Attribute內容為優先==
除了傳入初始內容,<aotter-text-editor>
也暴露了一些事件供使用
一個簡單的使用範例:
<body>
<aotter-text-editor id="my-editor">
<h1 style="color: red">標題</h1>
<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Totam, magnam</p>
</aotter-text-editor>
<script>
const myEditor = document.querySelector('#my-editor');
myEditor.addEventListenser('text-change', (e) => {
console.log(e.detail.ops)
})
</script>
</body>
事件名稱 | 觸發時機 | 傳入參數 | 備註 |
---|---|---|---|
text-change | 當編輯器內容或樣式改變時 | CustomEvent | CustomEvent.detail為編輯器當前Delta內容 |
Guide for App
【快速上手】
Aotter-Text-Editor透過WebView達成在App端使用原生UI對編輯器的控制
Aotter-Text-Editor在全域執行環境(window)下暴露了一個aotterTextEditor: Object
物件
該物件下最重要的一個方法為trigger: Function
,用來執行編輯器的各種功能
一個簡單的JavaScript程式碼例子如下,可以改變使用者反白的文字(未反白時,為接下來輸入的文字)的字型:
aotterTextEditor.trigger('font', 'monospace');
【iOS呼叫方式】(不確定是否可用,待測試)
方式1:透過evaluateJavaScript
參照:iOS呼叫JS函數方式 - 透過evaluateJavaScript
- (void)setFontToMonospace {
NSString *trigger = @"aotterTextEditor.trigger('font', 'monospace');"
[self.editorView evaluateJavaScript:trigger completionHanlder:^(NSString *result, NSError *error) {
// 處理JavaScript回傳值
}];
}
方式2:透過JavaScriptCore
參照:iOS呼叫JS函數方式 - 透過JavaScriptCore
// BasicsViewController.swift
import JavaScriptCore
var jsContext: JSContext!
func initializeJS() {
self.jsContext = JSContext()
// 指定 jssource.js 檔案路徑
if let jsSourcePath = Bundle.main.path(forResource: "jssource", ofType: "js") {
do {
// 將檔案內容加載到 String
let jsSourceContents = try String(contentsOfFile: jsSourcePath)
// 通過 jsContext 對象,將 jsSourceContents 中包含的腳本添加到 Javascript 運行時
self.jsContext.evaluateScript(jsSourceContents)
}
catch {
print(error.localizedDescription)
}
}
}
func setFontToMonospace() {
let font = "monospace"
if let trigger = self.jsContext.objectForKeyedSubscript("aotterTextEditor.trigger") {
// 呼叫trigger函數,將編輯器反白部分文字字型改為monospace
if let result = trigger.call(withArguments: [font]) {
// 處理JavaScript回傳值
}
}
}
self.initializeJS()
self.setFontToMonospace()
【trigger參數清單】
aotterTextEditor.trigger
接受的參數為
aotterTextEditor.trigger(【編輯器的樣式名稱】, 【(可選)該樣式的內容】)
樣式名稱 | 功能 | 樣式內容 | 內容型別 | 內容是否必填? |
---|---|---|---|---|
bold | 文字加粗 | true | false | Boolean | 否 |
italic | 文字斜體 | true | false | Boolean | 否 |
underline | 文字底線 | true | false | Boolean | 否 |
strike | 文字刪除線 | true | false | Boolean | 否 |
blockquote | 插入引用 | true | false | Boolean | 否 |
code-block | 插入程式碼區塊 | true | false | Boolean | 否 |
header | 插入標題 | '1' | '2' | '3' | ... '6' | String | ==是== |
list | 插入表單 | 'ordered' | 'bullet' | String | ==是== |
indent | 增減縮排 | '-1' | '+1' | String | ==是== |
direction | 行列對齊方式 | null | Null | 否 |
size | 字型大小 | 'small' | 'normal' | 'large' | 'huge' | String | ==是== |
color | 字體顏色 | 待補 | 待補 | 待補 |
background | 字體背景顏色 | 待補 | 待補 | 待補 |
font | 更改字型 | 'serif' | 'monospace' | or ... | String | ==是== |
align | 文字對齊方式 | 'center' | 'right' | 'justify' | String | ==是== |
clean | 清除格式 | null | Null | 否 |
link | 插入超連結 | 待補 | 待補 | 待補 |
image | 插入圖片 | url | String | ==是== |