Cloning Medium with Parchment

Cloning Medium with Parchment

注意：本节包含大量代码，原文都是 codepen 的代码预览视图，我为了阅读方便也将代码贴过来了，但是 HTML 和 css 代码我只会贴一遍，后面遇到 codepen 的地方我只贴 js 的代码。

要提供一致的编辑体验，您需要一致的数据和可预测的行为。不幸的是，DOM缺乏这两者。现代编辑器的解决方案是维护自己的文档模型来表示其内容。Parchment就是Quill的解决方案。它在自己的代码库中组织，具有自己的API层。通过Parchment，您可以自定义Quill识别的内容和格式，或添加全新的内容和格式。

在本指南中，我们将使用Parchment和Quill提供的构建块在Medium上复制编辑器。我们将从Quill的骨干开始，没有任何主题，无关的模块或格式。在这个基本级别，Quill只能理解纯文本。但是，在本指南结束时，我们将了解链接，视频甚至推文。

Groundwork（准备工作）

让我们在没有使用Quill的情况下开始，只需要一个textarea和按钮，连接到一个虚拟事件监听器。我们将在本指南中使用jQuery以方便使用，但Quill和Parchment都不依赖于此。在Google Fonts和Font Awesome的帮助下，我们还将添加一些基本样式。这些与Quill或Parchment没有任何关系，所以我们会快速进行。

HTML：

<div id="tooltip-controls">
  <button id="bold-button"><i class="fa fa-bold"></i></button>
  <button id="italic-button"><i class="fa fa-italic"></i></button>
  <button id="link-button"><i class="fa fa-link"></i></button>
  <button id="blockquote-button"><i class="fa fa-quote-right"></i></button>
  <button id="header-1-button"><i class="fa fa-header"><sub>1</sub></i></button>
  <button id="header-2-button"><i class="fa fa-header"><sub>2</sub></i></button>
</div>
<div id="sidebar-controls">
  <button id="image-button"><i class="fa fa-camera"></i></button>
  <button id="video-button"><i class="fa fa-play"></i></button>
  <button id="tweet-button"><i class="fa fa-twitter"></i></button>
  <button id="divider-button"><i class="fa fa-minus"></i></button>
</div>
<!-- <textarea id="editor-container">Tell your story...</textarea> -->
<div id="editor-container">Tell your story...</div>

CSS：

* {
  box-sizing: border-box;
}
html, body {
  height: 100%;
  margin: 0;
  width: 100%;
}
body {
  padding: 25px;
}
#editor-container {
  display: block;
  font-family: 'Open Sans', Helvetica, sans-serif;
  font-size: 1.2em;
  height: 200px;
  margin: 0 auto;
  width: 450px;
}
#tooltip-controls, #sidebar-controls {
  text-align: center;
}
button {
  background: transparent;
  border: none;
  cursor: pointer;
  display: inline-block;
  font-size: 18px;
  padding: 0;
  height: 32px;
  width: 32px;
  text-align: center;
}
button:active, button:focus {
  outline: none;
}

JavaScript：

$('button').click(function() {
  alert('Click!');
});

注：原文这里是一个 codepen 的视图，我们可以直接通过这个链接过去。

Adding Quill Core

接下来，我们将用Quill核心替换textarea，缺少主题，格式和无关模块。在键入编辑器时打开开发人员控制台以检查演示。您可以在工作中看到Parchment文档的基本构建块。

$('button').click(function() {
  alert('Click!');
});
let quill = new Quill('#editor-container');

注：原文这里是一个 codepen 的视图，我们可以直接通过这个链接过去。

与DOM一样，Parchment文档也是一棵树。它的节点称为Blots，是DOM节点的抽象。我们已经为我们定义了一些blots：Scroll, Block, Inline, Text 和 Break。键入时，Text blot与相应的DOM Text节点同步; 输入通过创建新的blot块来处理。在Parchment中，可以拥有孩子的Blots必须至少有一个孩子，所以空的块填充了一个Break blot。这使得处理叶子简单且可预测。所有这些都是在根Scroll blot下组织的。

您只能在此处键入内容来观察Inline blot，因为它不会为文档提供有意义的结构或格式。合理的Quill文档必须是规范和紧凑的。这里只有一个可以表示给定文档的有效DOM树，并且该DOM树包含最少数量的节点。

由于文本 和文本表示相同的内容，因此前者无效，并且它是Quill打开的优化过程的一部分。同样，一旦我们添加格式，Test和Test 也无效，因为它们不是最紧凑的表示。

由于这些约束，Quill不能支持任意DOM树和HTML的更改。但正如我们将看到的，这种结构提供的一致性和可预测性使我们能够轻松地构建丰富的编辑体验。

Basic Formatting

我们之前提到Inline不提供格式化。这是基础Inline类的例外，而不是规则。基本块级blot对块级元素的工作方式相同。

要实现粗体和斜体，我们只需要从Inline继承，设置blotName和tagName，并将其注册到Quill。有关继承和静态方法和变量的签名的完整参考，请查看Parchment。

let Inline = Quill.import('blots/inline');
class BoldBlot extends Inline { }
BoldBlot.blotName = 'bold';
BoldBlot.tagName = 'strong';
class ItalicBlot extends Inline { }
ItalicBlot.blotName = 'italic';
ItalicBlot.tagName = 'em';
Quill.register(BoldBlot);
Quill.register(ItalicBlot);

我们在这里使用strong和em标签遵循Medium的例子，但你也可以使用b和i标签。 blot的名称将被Quill用作格式的名称。通过注册我们的blots，我们现在可以在我们的新格式上使用Quill的完整API：

Quill.register(BoldBlot);
Quill.register(ItalicBlot);
var quill = new Quill('#editor');
quill.insertText(0, 'Test', { bold: true });
quill.formatText(0, 4, 'italic', true);
// If we named our italic blot "myitalic", we would call
// quill.formatText(0, 4, 'myitalic', true);

让我们摆脱我们的虚拟按钮处理程序，并将粗体和斜体按钮连接到Quill的format()。为了简单起见，我们将硬编码true以始终添加格式。在您的应用程序中，您可以使用getFormat()来检索任意范围内的当前格式，以决定是添加还是删除格式。Toolbar模块为Quill实现了这一点，我们不在这里重新实现它。

打开您的开发人员控制台，以新的粗体和斜体格式试用Quill的API！确保将上下文设置为正确的CodePen iframe，以便能够访问演示中的quill变量。

let Inline = Quill.import('blots/inline');
class BoldBlot extends Inline { }
BoldBlot.blotName = 'bold';
BoldBlot.tagName = 'strong';
class ItalicBlot extends Inline { }
ItalicBlot.blotName = 'italic';
ItalicBlot.tagName = 'em';
Quill.register(BoldBlot);
Quill.register(ItalicBlot);
var quill = new Quill('#editor-container');
$('#bold-button').click(function() {
  quill.format('bold', true);
});
$('#italic-button').click(function() {
  quill.format('italic', true);
});

注：原文这里是一个 codepen 的视图，我们可以直接通过这个链接过去。

请注意，如果您对某些文本同时应用粗体和斜体，则无论您执行何种顺序，Quill都会以一致的顺序将标记包装在标记之外。

Links

链接稍微复杂一些，因为我们需要不止一个布尔值来存储链接URL。这会以两种方式影响我们的链接blot：创建和格式检索。我们将url表示为字符串值，但我们可以通过其他方式轻松实现，例如带有url键的对象，允许设置其他键/值对并定义链接。我们稍后将用下文的image演示。

class LinkBlot extends Inline {
  static create(value) {
    let node = super.create();
    // 如果需要，清除url值
    node.setAttribute('href', value);
    // 可以设置其他非格式相关的属性
    // 这些对于Parchment是不可见的，所以必须是静态的
    node.setAttribute('target', '_blank');
    return node;
  }
  static formats(node) {
    // 我们将只在已经有节点的情况下被调用
    // 确定是Link blot，所以我们这样做
    // 不需要检查自己
    return node.getAttribute('href');
  }
}
LinkBlot.blotName = 'link';
LinkBlot.tagName = 'a';
Quill.register(LinkBlot);

现在我们可以将链接按钮挂钩到一个花哨的prompt，再次保持简单，然后传递给Quill的format()。

let Inline = Quill.import('blots/inline');
class BoldBlot extends Inline { }
BoldBlot.blotName = 'bold';
BoldBlot.tagName = 'strong';
class ItalicBlot extends Inline { }
ItalicBlot.blotName = 'italic';
ItalicBlot.tagName = 'em';
class LinkBlot extends Inline {
  static create(url) {
    let node = super.create();
    node.setAttribute('href', url);
    node.setAttribute('target', '_blank');
    return node;
  }
  static formats(node) {
    return node.getAttribute('href');
  }
}
LinkBlot.blotName = 'link';
LinkBlot.tagName = 'a';
Quill.register(BoldBlot);
Quill.register(ItalicBlot);
Quill.register(LinkBlot);
let quill = new Quill('#editor-container');
$('#bold-button').click(function() {
  quill.format('bold', true);
});
$('#italic-button').click(function() {
  quill.format('italic', true);
});
$('#link-button').click(function() {
  let value = prompt('Enter link URL');
  quill.format('link', value);
});

注：原文这里是一个 codepen 的视图，我们可以直接通过这个链接过去。

Blockquote and Headers

Blockquotes的实现方式与Bold blots相同，只是我们要继承的基本块级别的Blot是Block，而不是Inline。虽Inline blots可以嵌套，但Block blots不能。当应用于相同的文本范围时，Block blots不是合并，而是直接相互替换。

let Block = Quill.import('blots/block');
class BlockquoteBlot extends Block { }
BlockquoteBlot.blotName = 'blockquote';
BlockquoteBlot.tagName = 'blockquote';

标题的实现方式完全相同，只有一个区别：它可以由多个DOM元素表示。默认情况下，格式的值变为tagName，而不是true。我们可以通过扩展formats()来定制它，类似于我们links那样。

class HeaderBlot extends Block {
  static formats(node) {
    return HeaderBlot.tagName.indexOf(node.tagName) + 1;
  }
}
HeaderBlot.blotName = 'header';
// Medium只支持两种页眉大小，所以我们只演示两种,
// 但我们可以轻松地在这个数组中添加更多标签
HeaderBlot.tagName = ['H1', 'H2'];

让我们将这些新的blot挂钩到各自的按钮，并为<blockquote>标记添加一些CSS。

let Inline = Quill.import('blots/inline');
let Block = Quill.import('blots/block');
class BoldBlot extends Inline { }
BoldBlot.blotName = 'bold';
BoldBlot.tagName = 'strong';
class ItalicBlot extends Inline { }
ItalicBlot.blotName = 'italic';
ItalicBlot.tagName = 'em';
class LinkBlot extends Inline {
  static create(url) {
    let node = super.create();
    node.setAttribute('href', url);
    node.setAttribute('target', '_blank');
    return node;
  }
  static formats(node) {
    return node.getAttribute('href');
  }
}
LinkBlot.blotName = 'link';
LinkBlot.tagName = 'a';
class BlockquoteBlot extends Block { }
BlockquoteBlot.blotName = 'blockquote';
BlockquoteBlot.tagName = 'blockquote';
class HeaderBlot extends Block { }
HeaderBlot.blotName = 'header';
HeaderBlot.tagName = ['h1', 'h2'];
Quill.register(BoldBlot);
Quill.register(ItalicBlot);
Quill.register(LinkBlot);
Quill.register(BlockquoteBlot);
Quill.register(HeaderBlot);
let quill = new Quill('#editor-container');
$('#bold-button').click(function() {
  quill.format('bold', true);
});
$('#italic-button').click(function() {
  quill.format('italic', true);
});
$('#link-button').click(function() {
  let value = prompt('Enter link URL');
  quill.format('link', value);
});
$('#blockquote-button').click(function() {
  quill.format('blockquote', true);
});
$('#header-1-button').click(function() {
  quill.format('header', 1);
});
$('#header-2-button').click(function() {
  quill.format('header', 2);
});

注：原文这里是一个 codepen 的视图，我们可以直接通过这个链接过去。

尝试将一些文本设置为H1，然后在控制台中运行quill.getContents()。您将看到我们的自定义静态formats()函数正常工作。确保将上下文设置为正确的CodePen iframe，以便能够访问演示中的quill变量。

Dividers

现在让我们实现我们的第一片叶子Blot。虽然我们之前的Blot示例提供格式化并实现format()，leaf Blots 提供内容并实现value()。Leaf Blots可以是Text或Embed Blots，因此我们的section divider将是一个Embed。一旦创建，Embed Blots的值是不可变的，需要删除和重新插入才能更改该位置的内容。

除了从BlockEmbed继承之外，我们的方法与之前类似。Embed也存在于blots/embed下，但是用于内联级别的blots。我们希望块级实现代替分区器。

let BlockEmbed = Quill.import('blots/block/embed');
class DividerBlot extends BlockEmbed { }
DividerBlot.blotName = 'divider';
DividerBlot.tagName = 'hr';

我们的点击处理程序调用insertEmbed()，它不像我们那样可以方便地确定，保存和恢复用户选择，例如format()。是的，所以我们必须做更多的工作来保护自己的选择。另外，当我们尝试在Block的中间插入一个BlockEmbed时，Quill会为我们分割Block。为了使这种行为更加清晰，我们将通过在插入分隔符之前插入换行符来自行拆分块。请查看CodePen中的Babel选项卡以了解具体信息。

注：原文这里是一个 codepen 的视图，我们可以直接通过这个链接过去。

Images

image的实现可以借鉴Link和Dividerblots的实现方式。我们将使用一个对象作为值来显示如何支持它。我们用于插入图像的按钮处理程序将使用静态值，因此我们不会被与Parchment无关的工具提示UI代码分心，这是本指南的重点。

let BlockEmbed = Quill.import('blots/block/embed');
class ImageBlot extends BlockEmbed {
  static create(value) {
    let node = super.create();
    node.setAttribute('alt', value.alt);
    node.setAttribute('src', value.url);
    return node;
  }
  static value(node) {
    return {
      alt: node.getAttribute('alt'),
      url: node.getAttribute('src')
    };
  }
}
ImageBlot.blotName = 'image';
ImageBlot.tagName = 'img';

注：原文这里是一个 codepen 的视图，我们可以直接通过这个链接过去。

Videos

我们将以与image类似的方式实现视频。我们可以使用HTML5<video>标签，但我们不能以这种方式播放YouTube视频，因为这可能是更常见和相关的用例，我们将使用<iframe>来支持此功能。在此我们不必，但是如果你想要多个Blots来使用相同的标签，除了tagName之外你还可以使用className，在下一个Tweet示例中进行了演示。

此外，我们将添加对宽度和高度的支持，作为未注册的格式。只要没有与注册格式的命名空间冲突，就不必单独注册Embeds特有的格式。这是有效的，因为Blots只是将未知格式传递给它的孩子，最终到达了叶子。这也允许不同的Embeds以不同方式处理未注册的格式。例如，我们从早期嵌入的image可以识别和处理width格式，与我们的视频在这里不同。

class VideoBlot extends BlockEmbed {
  static create(url) {
    let node = super.create();
    node.setAttribute('src', url);
    // 使用静态值设置非格式相关属性
    node.setAttribute('frameborder', '0');
    node.setAttribute('allowfullscreen', true);
    return node;
  }
  static formats(node) {
    // 我们仍然需要报告未注册的嵌入格式
    let format = {};
    if (node.hasAttribute('height')) {
      format.height = node.getAttribute('height');
    }
    if (node.hasAttribute('width')) {
      format.width = node.getAttribute('width');
    }
    return format;
  }
  static value(node) {
    return node.getAttribute('src');
  }
  format(name, value) {
    // 处理未注册的嵌入格式
    if (name === 'height' || name === 'width') {
      if (value) {
        this.domNode.setAttribute(name, value);
      } else {
        this.domNode.removeAttribute(name, value);
      }
    } else {
      super.format(name, value);
    }
  }
}
VideoBlot.blotName = 'video';
VideoBlot.tagName = 'iframe';

请注意，如果您打开控制台并调用getContents，Quill会将视频报告为：

{
  ops: [{
    insert: {
      video: 'https://www.youtube.com/embed/QHH3iSeDBLo?showinfo=0'
    },
    attributes: {
      height: '170',
      width: '400'
    }
  }]
}

注：原文这里是一个 codepen 的视图，我们可以直接通过这个链接过去。

Tweets

Medium支持许多嵌入类型，但我们只关注本指南的推文。Tweet blot实现与image几乎完全相同。我们利用Embed blots不必对应于void节点的事实。它可以是任意节点，Quill会将其视为void节点，而不是遍历其子节点或后代。这允许我们使用<div>和本地Twitter Javascript库在我们指定的<div>容器中做它喜欢的事情。

由于我们的根Scroll Blot也使用className``````tagName``className

我们使用Tweet id作为定义Blot的值。我们的点击处理程序再次使用静态值来避免分散不相关的UI代码。

class TweetBlot extends BlockEmbed {
  static create(id) {
    let node = super.create();
    node.dataset.id = id;
    // Allow twitter library to modify our contents
    twttr.widgets.createTweet(id, node);
    return node;
  }
  static value(domNode) {
    return domNode.dataset.id;
  }
}
TweetBlot.blotName = 'tweet';
TweetBlot.tagName = 'div';
TweetBlot.className = 'tweet';

注：原文这里是一个 codepen 的视图，我们可以直接通过这个链接过去。

Final Polish

我们从一堆按钮和一个只能理解明文的Quill核心开始。使用Parchment，我们可以添加粗体，斜体，链接，块引用，标题，部分分隔符，图像，视频甚至推文。所有这些都是在维护可预测且一致的文档的同时，允许我们使用Quill强大的API以及这些新格式和内容。

让我们添加一些最后的润色来完成我们的演示。它不会与Medium的用户界面相比，但我们会尽力接近。

注：原文这里是一个 codepen 的视图，我们可以直接通过这个链接过去。

Quill 编辑器文档翻译

cloning-medium-with-parchment

Cloning Medium with Parchment

Groundwork（准备工作）

Adding Quill Core

Basic Formatting

Links

Blockquote and Headers

Dividers

Images

Videos

Tweets

Final Polish