Editor
加粗格式
",
"application/x-doc-editor": '[{"children":[{"text":"Editor"}],"heading":{"type":"h1","id":"W5xjbuxy"}},{"children":[{"text":"加粗","bold":true},{"text":"格式"}]}]',
}
```
我们接下来需要设想下如何将内容写入到剪贴板，以及实际触发的场景。除了常见的`Ctrl+C`来触发复制行为外，用户还有可能希望通过按钮来触发复制行为，例如飞书就可以通过工具栏复制整个行/块结构，因此我们不能直接通过`OnCopy`事件的`clipboardData`来写数据，而是需要主动触发额外的`Copy`事件。
前边也提到了`navigator.clipboard.write`同样可以写入剪贴板，调用这个`API`是不需要真正触发`Copy`事件的，但是当我们使用这个方法写入数据的时候，可能会抛出异常。此外这个`API`必须要在`HTTPS`环境下才能使用，否则会完全没有这个函数的定义。
在下面的例子中需要焦点在`document`上，需要在延迟时间内点击页面，否则会抛出`DOMException`。而即使当我们焦点在页面上，执行后同样会抛出`DOMException`，从抛出的异常来看是因为`application/x-doc-editor`类型不被支持。
```js
(async () => {
await new Promise((resolve) => setTimeout(resolve, 3000));
const params = {
"text/plain": "Editor",
"text/html": "Editor",
"application/x-doc-editor": '[{"children":[{"text":"Editor"}]}]',
}
const dataItems = {};
for (const [key, value] of Object.entries(params)) {
const blob = new Blob([value], { type: key });
dataItems[key] = blob;
}
// DOMException: Type application/x-doc-editor not supported on write.
navigator.clipboard.write([new ClipboardItem(dataItems)]);
})();
```
因为这个`API`不支持我们写入自定义的类型，因此我们就需要主动触发`Copy`事件来写入剪贴板，虽然我们同样可以将这个字段的数据作为`HTML`的某个属性值写入`text/html`中，但是我们这里还是将其独立出来处理。那么以同样的数据，我们使用`document.execCommand`写入剪贴板的方式就需要新建`textarea`元素来实现。
```js
const data = {
"text/plain": "Editor",
"text/html": "Editor",
"application/x-doc-editor": '[{"children":[{"text":"Editor"}]}]',
}
const textarea = document.createElement("textarea");
textarea.addEventListener("copy", event => {
for (const [key, value] of Object.entries(data)) {
event.clipboardData && event.clipboardData.setData(key, value);
}
event.stopPropagation();
event.preventDefault();
});
textarea.style.position = "fixed";
textarea.style.left = "-999px";
textarea.style.top = "-999px";
textarea.value = data["text/plain"];
document.body.appendChild(textarea);
textarea.select();
document.execCommand("copy");
document.body.removeChild(textarea);
```
当然这里我们能够很明显地看到由于`textarea.select`，我们原本的编辑器焦点会丢失。因此这里我们还需要注意，在执行复制的时候需要记录当前的选区值，在写入剪贴板之后先将焦点置于编辑器，之后再恢复选区。
接下来我们来处理插件化的定义，这里的`Context`非常简单，只需要记录当前正在处理的`Node`以及当前已经处理过后的`html`节点即可。而在插件中我们需要实现`serialize`方法，用来将`Node`序列化为`HTML`，`willSetToClipboard`则是`Hook`定义，当即将写入剪贴板时会被调用。
```js
// packages/core/src/clipboard/utils/types.ts
/** Fragment => HTML */
export type CopyContext = {
/** Node 基准 */
node: BaseNode;
/** HTML 目标 */
html: Node;
};
// packages/core/src/plugin/modules/declare.ts
abstract class BasePlugin {
/** 将 Fragment 序列化为 HTML */
public serialize?(context: CopyContext): void;
/** 内容即将写入剪贴板 */
public willSetToClipboard?(context: CopyContext): void;
}
```
既然我们的具体转换是在插件中实现的，那么我们主要的工作就是调度插件的执行了。为了方便处理数据，我们这里就不使用`Immutable`的形式来处理了，我们的`Context`对象是整个调度过程中保持一致的，即插件中我们所有的方法都是原地处理的。那么调度的方式就直接通过`plugin`组件调度，调用后从`context`中获取`html`节点即可。
```js
// packages/core/src/plugin/modules/declare.ts
public call
if (node.children && !node.children.length) {
node.children.push({ text: "" });
}
}
}
}
```
对于内容的处理则是判断出`HTML`节点存在加粗的格式后，对当前已经处理的`Node`节点树中所有的文本节点实现加粗操作，这里同样需要原地处理数据。这里我们还封装了`applyMark`的方法，用来处理所有的文本节点格式。其实这里有趣的是，因为我们的目标是构造整个`JSON`，我们就不需要关注使用`slate`的`Transform`模块操作`Model`。
```js
// packages/plugin/src/clipboard/utils/apply.ts
export class BoldPlugin extends LeafPlugin {
public deserialize(context: PasteContext): void {
const { nodes, html } = context;
if (!isHTMLElement(html)) return void 0;
if (isMatchTag(html, "strong") || isMatchTag(html, "b") || html.style.fontWeight === "bold") {
// applyMarker packages/plugin/src/clipboard/utils/apply.ts
context.nodes = applyMarker(nodes, { [BOLD_KEY]: true });
}
}
}
```
### 段落结构
段落结构指的是标题、行高、文本对齐等结构样式，这里则以标题为例来处理序列化与反序列化。序列化段落结构，我们只需要`Node`是标题节点时，构造相关的`HTML`节点，将本来的节点原地包装并赋值到`context`即可，同样采用嵌套节点的方式。
```js
// packages/plugin/src/heading/index.tsx
export class HeadingPlugin extends BlockPlugin {
public serialize(context: CopyContext): void {
const element = context.node as BlockElement;
const heading = element[HEADING_KEY];
if (!heading) return void 0;
const id = heading.id;
const type = heading.type;
const node = document.createElement(type);
node.id = id;
node.setAttribute("data-type", HEADING_KEY);
node.appendChild(context.html);
context.html = node;
}
}
```
反序列化则是相反的操作，判断当前正在处理的`HTML`节点是否为标题节点，如果是的话就将其转换为`Node`节点。这里同样需要原地处理数据，与行内节点不同的是，需要使用`applyLineMarker`将所有的行节点加入标题格式。
```js
// packages/plugin/src/heading/index.tsx
export class HeadingPlugin extends BlockPlugin {
public deserialize(context: PasteContext): void {
const { nodes, html } = context;
if (!isHTMLElement(html)) return void 0;
const tagName = html.tagName.toLocaleLowerCase();
if (tagName.startsWith("h") && tagName.length === 2) {
let level = Number(tagName.replace("h", ""));
if (level <= 0 || level > 3) level = 3;
// applyLineMarker packages/plugin/src/clipboard/utils/apply.ts
context.nodes = applyLineMarker(this.editor, nodes, {
[HEADING_KEY]: { type: `h` + level, id: getId() },
});
}
}
}
```
### 组合结构
组合结构在这里指的是引用块、有序列表、无序列表等结构样式，这里则以引用块为例来处理序列化与反序列化。序列化组合结构，同样需要`Node`是引用块节点时，构造相关的`HTML`节点进行包装。
```js
// packages/plugin/src/quote-block/index.tsx
export class QuoteBlockPlugin extends BlockPlugin {
public serialize(context: CopyContext): void {
const element = context.node as BlockElement;
const quote = element[QUOTE_BLOCK_KEY];
if (!quote) return void 0;
const node = document.createElement("blockquote");
node.setAttribute("data-type", QUOTE_BLOCK_KEY);
node.appendChild(context.html);
context.html = node;
}
}
```
反序列化同样是判断是否为引用块节点，并且构造对应的`Node`节点。这里与标题模块不同的是，标题是将格式应用到相关的行节点上，而引用块则是在原本的节点上嵌套一层结构。
```js
// packages/plugin/src/quote-block/index.tsx
export class QuoteBlockPlugin extends BlockPlugin {
public deserialize(context: PasteContext): void {
const { nodes, html } = context;
if (!isHTMLElement(html)) return void 0;
if (isMatchTag(html, "blockquote")) {
const current = applyLineMarker(this.editor, nodes, {
[QUOTE_BLOCK_ITEM_KEY]: true,
});
context.nodes = [{ children: current, [QUOTE_BLOCK_KEY]: true }];
}
}
}
```
### 嵌入结构
嵌入结构在这里指的是图片、视频、流程图等结构样式，这里则以图片为例来处理序列化与反序列化。序列化嵌入结构，我们只需要`Node`是图片节点时，构造相关的`HTML`节点进行包装。与之前的节点不同的是，此时我们不需要嵌套`DOM`节点了，将独立节点原地替换即可。
```js
// packages/plugin/src/image/index.tsx
export class ImagePlugin extends BlockPlugin {
public serialize(context: CopyContext): void {
const element = context.node as BlockElement;
const img = element[IMAGE_KEY];
if (!img) return void 0;
const node = document.createElement("img");
node.src = img.src;
node.setAttribute("data-type", IMAGE_KEY);
node.appendChild(context.html);
context.html = node;
}
}
```
对于反序列化的结构，判断当前正在处理的`HTML`节点是否为图片节点，如果是的话就将其转换为`Node`节点。与先前的转换不同的是，我们此时不需要嵌套结构，只需要固定`children`为零宽字符占位即可。实际上这里还有个常用的操作是，粘贴图片内容通常需要将原本的`src`转储到我们的服务上，例如飞书的图片就是临时链接，在生产环境中需要转储资源。
```js
// packages/plugin/src/image/index.tsx
export class ImagePlugin extends BlockPlugin {
public deserialize(context: PasteContext): void {
const { html } = context;
if (!isHTMLElement(html)) return void 0;
if (isMatchTag(html, "img")) {
const src = html.getAttribute("src") || "";
const width = html.getAttribute("data-width") || 100;
const height = html.getAttribute("data-height") || 100;
context.nodes = [
{
[IMAGE_KEY]: {
src: src,
status: IMAGE_STATUS.SUCCESS,
width: Number(width),
height: Number(height),
},
uuid: getId(),
children: [{ text: "" }],
},
];
}
}
}
```
### 块级结构
块级结构指的是高亮块、代码块、表格等结构样式，这里则以高亮块为例来处理序列化与反序列化。高亮块则是飞书中比较定制的结构，本质上是`Editable`结构的嵌套，这里的两层`callout`嵌套结构则是为了兼容飞书的结构。序列化块级结构在`slate`中跟引用结构类似，在外层直接嵌套组合结构即可。
```js
// packages/plugin/src/highlight-block/index.tsx
export class HighlightBlockPlugin extends BlockPlugin {
public serialize(context: CopyContext): void {
const { node: node, html } = context;
if (this.reflex.isBlock(node) && node[HIGHLIGHT_BLOCK_KEY]) {
const colors = node[HIGHLIGHT_BLOCK_KEY]!;
// 提取具体色值
const border = colors.border || "";
const background = colors.background || "";
const regexp = /rgb\((.+)\)/;
const borderVar = RegExec.exec(regexp, border);
const backgroundVar = RegExec.exec(regexp, background);
const style = window.getComputedStyle(document.body);
const borderValue = style.getPropertyValue(borderVar);
const backgroundValue = style.getPropertyValue(backgroundVar);
// 构建 HTML 容器节点
const container = document.createElement("div");
container.setAttribute(HL_DOM_TAG, "true");
container.classList.add("callout-container");
container.style.border = `1px solid rgb(` + borderValue + `)`;
container.style.background = `rgb(` + backgroundValue + `)`;
container.setAttribute("data-emoji-id", "balloon");
const block = document.createElement("div");
block.classList.add("callout-block");
container.appendChild(block);
block.appendChild(html);
context.html = container;
}
}
}
```
反序列化则是判断当前正在处理的`HTML`节点是否为高亮块节点，如果是的话就将其转换为`Node`节点。这里的处理方式同样与引用块类似，只是需要在外层嵌套一层结构。
```js
// packages/plugin/src/highlight-block/index.tsx
export class HighlightBlockPlugin extends BlockPlugin {
public deserialize(context: PasteContext): void {
const { nodes, html: node } = context;
if (isHTMLElement(node) && node.classList.contains("callout-block")) {
const border = node.style.borderColor;
const background = node.style.backgroundColor;
const regexp = /rgb\((.+)\)/;
const borderColor = border && RegExec.exec(regexp, border);
const backgroundColor = background && RegExec.exec(regexp, background);
if (!borderColor || !backgroundColor) return void 0;
context.nodes = [
{
[HIGHLIGHT_BLOCK_KEY]: {
border: borderColor,
background: backgroundColor,
},
children: nodes,
},
];
}
}
}
```
## 扁平数据类型
`quill`的基本数据结构是扁平结构的`JSON`类型，相关的`DEMO`实现都在`https://github.com/WindRunnerMax/BlockKit`中。我们同样以标题与加粗的格式为例，描述其基础内容结构:
```js
[
{ insert: "Editor" },
{ attributes: { heading: "h1" }, insert: "\n" },
{ attributes: { bold: "true" }, insert: "加粗" },
{ insert: "格式" },
{ insert: "\n" },
];
```
序列化的调度方案与`slate`类似，我们同样需要在剪贴板模块提供基本的序列化与反序列化的接口，而具体的实现则归于插件本身处理。针对序列化的方法，也是按照基本行遍历的方式，优先处理`Delta`结构的的文本，再处理行结构的格式。但是由于`delta`的数据结构是扁平的，因此我们不能直接递归处理，而是应该循环到`EOL`时将当前行的节点更新为新的行节点。
```js
// packages/core/src/clipboard/modules/copy.ts
const root = rootNode || document.createDocumentFragment();
let lineFragment = document.createDocumentFragment();
const ops = normalizeEOL(delta.ops);
for (const op of ops) {
if (isEOLOp(op)) {
const context: SerializeContext = { op, html: lineFragment };
this.editor.plugin.call(CALLER_TYPE.SERIALIZE, context);
let lineNode = context.html as HTMLElement;
if (!isMatchBlockTag(lineNode)) {
lineNode = document.createElement("div");
lineNode.setAttribute(LINE_TAG, "true");
lineNode.appendChild(context.html);
}
root.appendChild(lineNode);
lineFragment = document.createDocumentFragment();
continue;
}
const text = op.insert || "";
const textNode = document.createTextNode(text);
const context: SerializeContext = { op, html: textNode };
this.editor.plugin.call(CALLER_TYPE.SERIALIZE, context);
lineFragment.appendChild(context.html);
}
```
反序列化的整体流程则与`slate`更加类似，因为我们同样都是以`HTML`为基准处理数据，深度递归遍历优先处理叶子节点，然后以处理过的`delta`为基准处理额外节点。只不过这里我们最终输出的数据结构会是扁平的，这样的话就不需要特别关注`Normalize`的操作。
```js
// packages/core/src/clipboard/modules/paste.ts
public deserialize(current: Node): Delta {
const delta = new Delta();
// 结束条件 Text Image 等节点都会在此时处理
if (!current.childNodes.length) {
if (isDOMText(current)) {
const text = current.textContent || "";
delta.insert(text);
} else {
const context: DeserializeContext = { delta, html: current };
this.editor.plugin.call(CALLER_TYPE.DESERIALIZE, context);
return context.delta;
}
return delta;
}
const children = Array.from(current.childNodes);
for (const child of children) {
const newDelta = this.deserialize(child);
delta.ops.push(...newDelta.ops);
}
const context: DeserializeContext = { delta, html: current };
this.editor.plugin.call(CALLER_TYPE.DESERIALIZE, context);
return context.delta;
}
```
此外，对于块级嵌套结构的处理，我们的处理方式可能会更加复杂，但是在当前的实现中还并没有完成，因此暂时还处于设计阶段。序列化的处理方式类似于下面的流程，与先前结构不同的是，当处理到块结构时，直接调用剪贴板的序列化模块，将内容嵌入即可。
```
| -- bold ··· -- |
| -- line -- | | --
