Meta の新しいリッチテキストエディターフレームワーク Lexical を調べる

おや、、、この流れもどこかで知っているな 🤔

Meta が提唱している Flux のフローですね。 Lexical の文脈では Command と呼ばれていますが、 Flux の Action とみなすことができます。予め登録しておく処理は reducer に相当します。 Action がディスパッチされたら reducer がステートを更新する流れである Flux を意識しているような Command のフローです(僕がそう思っただけでドキュメントに記載があるわけではありませんが)。

Flux 同様、 Command をディスパッチする際にペイロードを付与することもできます。例えばエディターにテキストカラーを変更する UI を搭載したい場合は、 TEXT_COLOR_COMMAND とともに何色にするかの情報を一緒にディスパッチします。

上の図が単方向データバインディングに見えなくなっているかもしれませんが、 EditorState 更新処理を Editor に登録するだけであって Command が Editor に何か作用するわけではありません。ですので、処理の流れは依然として EditorState --> Editor --> DOM --> EditorState のループです。

Node Transforms

Node 単位で変換をかける処理 Node Transform を Editor に対して予め登録しておくことができます。 EditorState が変更されて DOM に適用される前に Node Transform で更に EditorState が書き換えられます。

一度の EditorState の変更によって複数の transform が作用することがあります。しかし、いくつの transform が発行されても最終的に行われる DOM 更新は一度だけです。

https://lexical.dev より引用

例えば Twitter のツイート入力欄は "@" から始まる文字列はメンション先として青色に装飾されます。その機能を実装するときに Node Transforms が使えて、入力に応じて Node を差し替えていくことで実現できます。

$ prefixed functions

Lexical のパッケージから export されている $ で始まる名前の関数は特別な場所でしか使えないようになっています。それは、次のメソッドのコールバック関数の中です。

• editor.update(() => {})
• editorState.read(() => {})

(他にもあるっぽいですが全部特定できてません。)

ドキュメントでは「React Hooks がコンポーネント内部でしか使えないのと似ている」と説明されています。ただし、 $ プレフィックス関数はトップレベルである必要も、順番の固定を保証する必要もないようで React Hooks と比べるとだいぶ制約は弱いです。

実装例

ここまでは概念をコードなしで説明してきました。ここからは実装例を交えながら説明していきます(動くサンプルは最後に載せています)。

最小構成

npm install lexical

HTML に <div id="editor" contenteditable="true"></div> が含まれているとします。

import { createEditor } from "lexical";

const editorRoot = document.getElementById("editor");

const editor = createEditor();

editor.setRootElement(editorRoot);

createEditor で Editor インスタンスを生成して、エディターのビューをレンダリングする div 要素を指定します。 div 要素は予め contenteditable にしておく必要があります。

この状態では、 contenteditable なのでキャレットは当たりますが入力ができません。なぜでしょう。

ユーザーの操作はすべて Command のディスパッチ に変換されるはずでしたね。 editor にはデフォルトの動作が何も登録されていないので、キーボード入力すら反応しません。ユーザーのテキスト入力によって発行される Command に対して EditorState の更新を行う処理を追加しましょう。

editor.registerCommand(
  INSERT_TEXT_COMMAND,
  (text: string) => {
    const selection = $getSelection();
    selection?.insertText(text);
    return true;
  },
  COMMAND_PRIORITY_EDITOR
);

INSERT_TEXT_COMMAND はユーザーのキーボード入力によってディスパッチされるコマンドです。それを受け取ったら実行する処理を editor に登録します。こんな感じで色々な Command に対して処理を登録しないとまともに動くエディターにならないのですが、テキストエディターのよくあるキーバインド(Cmd+B でボールドスタイルを適用するなど)は用意しておいてほしいですよね。もちろん用意してあります。

• plain-text なエディターの場合

  最低限のテキストエディターです。ほとんど textarea と変わりないです。

  # peerDependencies 含む
  npm install @lexical/plain-text @lexical/utils @lexical/selection @lexical/clipboard
  

  https://github.com/facebook/lexical/blob/f3c5e8bc6897dabfcebd13112e57c253c7d325e7/packages/lexical-plain-text/src/index.js

  import { createEditor } from "lexical";
  import { registerPlainText } from "@lexical/plain-text";
  
  const editorRoot = document.getElementById("editor");
  const editor = createEditor();
  editor.setRootElement(editorRoot);
  registerPlainText(editor); // ここで一括登録
  

• rich-text なエディターの場合

  よくあるリッチテキストエディターの構成です。Cmd+B でボールドになったり Tab でインデントができます。

  # peerDependencies 含む
  npm install @lexical/rich-text @lexical/utils @lexical/selection @lexical/clipboard
  

  https://github.com/facebook/lexical/blob/f3c5e8bc6897dabfcebd13112e57c253c7d325e7/packages/lexical-rich-text/src/index.js

  import { createEditor } from "lexical";
  import { registerRichText } from "@lexical/rich-text";
  
  const editorRoot = document.getElementById("editor");
  const editor = createEditor();
  editor.setRootElement(editorRoot);
  registerRichText(editor); // ここで一括登録
  

テキストに応じて文字色が変化する Node を作ってみる

入力されたテキストに応じて色を変更したいケースは多いと思います。今回は "color:red" のようなテキストを受け取ったら、その色がフォントカラーになるような TextNode を作ってみます。

まずは色を判定する関数。 StackOverflow で見つけました。 new Option() とかいうの初めて見た…。

// https://stackoverflow.com/questions/48484767/javascript-check-if-string-is-valid-css-color
const isValidColor = (strColor: string) => {
  const s = new Option().style;
  s.color = strColor;
  return s.color !== "";
};

そして色が切り替わる専用の Node を TextNode を継承して作ります。継承してオリジナルの Node を作る手順はドキュメントに記載されています(ページ)。

import { TextNode } from "lexical";

export class AnyColoredTextNode extends TextNode {
  private __color: string;
  constructor(color: string, text: string, key?: NodeKey) {
    super(text, key);
    this.__color = color;
  }
}

内部プロパティとして __color を持ちます。コンストラクタで継承元である TextNode のコンストラクタ引数に加えて独自の color を取ります。

続いて、独自 Node クラスには 2 つの必須な static メソッドを生やす必要があるようです。 static getType() と static clone() です。 type は EditorState を JSON から復元するために使用され、clone は EditorState のスナップショットの作成に使用されるとのこと。

export class AnyColoredTextNode extends TextNode {
  /* other properties */

  static getType(): string {
    return "any-colored";
  }
  static clone(node: AnyColoredTextNode): AnyColoredTextNode {
    return new AnyColoredTextNode(node.__color, node.__text, node.__key);
  }
}

ところで、 __color は private プロパティですが、外から読みたいこともあるでしょう。その場合、アクセサとして getColor() と setColor(color) を生やしても良いのですが、書き方に癖があるので要注意です。

export class AnyColoredTextNode extends TextNode {
  /* other properties */

  getColor(): string {
    const self = this.getLatest<AnyColoredTextNode>();
    return self.__color;
  }

  setColor(color: string): void {
    const self = this.getWritable<AnyColoredTextNode>();
    self.__color = color;
  }
}

getLatest() で EditorState から最新の Node インスタンスを取得します。取得した最新のインスタンスの __color 返却するようにします。

また、getWritable() でクローンを作ってからミューテーションを行います。 EditorState は immutable なので this.__color = color などとやってはいけません。

続いて Node と対応する DOM を返すメソッドです。

export class AnyColoredTextNode extends TextNode {
  /* other properties */

  createDOM(config: EditorConfig<{}>): HTMLElement {
    const element = super.createDOM(config);
    element.style.color = this.__color;
    return element;
  }
  updateDOM(
    prevNode: AnyColoredTextNode,
    dom: HTMLElement,
    config: EditorConfig<{}>
  ): boolean {
    const isUpdated = super.updateDOM(prevNode, dom, config);
    if (prevNode.__color !== this.__color) {
      dom.style.color = this.__color;
    }
    return isUpdated;
  }
}

createDOM も updateDOM も基本は親クラスに処理を渡すだけですが、スタイルに自分が持っている __color を当てる処理だけ追加しています。

また、独自 Node クラスを作成したら そのクラスインスタンスを操作するユーティリティ関数を $ プレフィックスで定義することをエチケットとして推奨しています。

export function $createAnyColoredTextNode(
  color: string,
  text: string
): AnyColoredTextNode {
  return new AnyColoredTextNode(color, text);
}

export function $isAnyColoredTextNode(node: LexicalNode): node is AnyColoredTextNode {
  return node instanceof AnyColoredTextNode;
}

自作 Node は完成しました。続いて、標準の TextNode に "color:red" と入力されたら TextNode を AnyColoredTextNode に変換する処理を書きます。 Node Transforms の出番です。

まずは TextNode -> AnyColoredTextNode の変換です。 valid な color を入力してもらえた時だけ変換します。変換処理は Editor に対して登録します。

editor.registerNodeTransform(TextNode, (textNode: TextNode) => {
  const text = textNode.getTextContent();
  const matched = /color:(.*)/.exec(text);
  if (matched !== null) {
    const color = matched[1];
    if (isValidColor(color)) {
      textNode.replace($createAnyColoredTextNode(color, text));
    }
  }
});

registerNodeTransform の第 1 引数は変換対象の Node クラスです。クラスなので TS から JS にコンパイルされても実体があり引数に渡せます。 textNode.replace で全体のツリーから見たその Node の位置を別の Node で置き換えることができます(執筆時点で node.replace についてドキュメントなし)。正規表現で入力されたテキストから color を取り出して isValidColor(color) を満たせば AnyColoredTextNode に差し替えます。

続いて AnyColoredTextNode -> TextNode の変換です。入力されたテキストが "color:red" にマッチしなくなったら標準の TextNode に戻してあげます。また、別の色を入力されたら Node はそのままでフォントカラーが変わるようにします。

editor.registerNodeTransform(AnyColoredTextNode, (node: AnyColoredTextNode) => {
  const text = node.getTextContent();
  const matched = /color:(.*)/.exec(text);
  if (matched === null) {
    node.replace($createTextNode(text));
  } else {
    const color = matched[1];
    const currentColor = node.getColor();
    if (color !== currentColor && isValidColor(color)) {
      node.setColor(color);
    }
  }
});

registerNodeTransform の第 1 引数で指定する変換ターゲットは今度は AnyColoredTextNode です。 matched === null の時は TextNode に置き換えます。また、マッチしてかつ指定された色が変わっていれば、定義しておいた setColor メソッドで色を変更します。

ところで、Lexical の registerXXX と命名されたメソッドには実は戻り値があります。登録を解除するための関数です。 useEffect のクリーンアップでの使用を意識しているようです。今回 2 つの registerNodeTransform を使いましたが、複雑なリッチテキストエディターを開発する場合、もっとたくさんの registerXXX を使うことになるでしょう。ひとつずつ登録解除していくのは面倒なので、公式でマージユーティリティを用意してくれています(執筆時点でドキュメントなし)。

import { mergeRegister } from "@lexical/utils";

const bulkUnregister = mergeRegister(
  editor.registerNodeTransform(OneNode, (node) => {}),
  editor.registerNodeTransform(TwoNode, (node) => {}),
  editor.registerNodeTransform(ThreeNode, (node) => {})
);

bulkUnregister(); // 全部の register を解除したことになる

今回用意する registerNodeTransform は 2 つだけですが、せっかくなので mergeRegister を使ってラップします。

export function registerTransformAnyColoredText(editor: LexicalEditor): () => void {
  return mergeRegister(
    editor.registerNodeTransform(TextNode, (textNode: TextNode) => {
      /* TextNode -> AnyColoredTextNode */
    }),
    editor.registerNodeTransform(AnyColoredTextNode, (node: AnyColoredTextNode) => {
      /* AnyColoredTextNode -> TextNode */
    })
  );
}

registerTransformAnyColoredText は editor を受け取って登録解除関数を返すようなインターフェイスの関数です。@lexical/rich-text のようなコア以外のプラグインライブラリに倣っています。

import {
  TextNode,
  EditorConfig,
  LexicalNode,
  LexicalEditor,
  NodeKey,
  $createTextNode,
} from "lexical";
import { mergeRegister } from "@lexical/utils";

export class AnyColoredTextNode extends TextNode {
  private __color: string;
  constructor(color: string, text: string, key?: NodeKey) {
    super(text, key);
    this.__color = color;
  }

  static getType(): string {
    return "any-colored";
  }
  static clone(node: AnyColoredTextNode): AnyColoredTextNode {
    return new AnyColoredTextNode(node.__color, node.__text, node.__key);
  }

  getColor(): string {
    const self = this.getLatest<AnyColoredTextNode>();
    return self.__color;
  }

  setColor(color: string): void {
    const self = this.getWritable<AnyColoredTextNode>();
    self.__color = color;
  }

  createDOM(config: EditorConfig<{}>): HTMLElement {
    const element = super.createDOM(config);
    element.style.color = this.__color;
    return element;
  }
  updateDOM(
    prevNode: AnyColoredTextNode,
    dom: HTMLElement,
    config: EditorConfig<{}>
  ): boolean {
    const isUpdated = super.updateDOM(prevNode, dom, config);
    if (prevNode.__color !== this.__color) {
      dom.style.color = this.__color;
    }
    return isUpdated;
  }
}

export function $createAnyColoredTextNode(
  color: string,
  text: string
): AnyColoredTextNode {
  return new AnyColoredTextNode(color, text);
}

export function $isAnyColoredTextNode(node: LexicalNode): node is AnyColoredTextNode {
  return node instanceof AnyColoredTextNode;
}

export function registerTransformAnyColoredText(editor: LexicalEditor): () => void {
  return mergeRegister(
    editor.registerNodeTransform(TextNode, (textNode: TextNode) => {
      const text = textNode.getTextContent();
      const matched = /color:(.*)/.exec(text);
      if (matched !== null) {
        const color = matched[1];
        if (isValidColor(color)) {
          textNode.replace($createAnyColoredTextNode(color, text));
        }
      }
    }),
    editor.registerNodeTransform(AnyColoredTextNode, (node: AnyColoredTextNode) => {
      const text = node.getTextContent();
      const matched = /color:(.*)/.exec(text);
      if (matched === null) {
        node.replace($createTextNode(text));
      } else {
        const color = matched[1];
        const currentColor = node.getColor();
        if (color !== currentColor && isValidColor(color)) {
          node.setColor(color);
        }
      }
    })
  );
}

// https://stackoverflow.com/questions/48484767/javascript-check-if-string-is-valid-css-color
const isValidColor = (strColor: string) => {
  const s = new Option().style;
  s.color = strColor;
  return s.color !== "";
};

ここまでで独自 Node クラスとそれを変換する registerTransformAnyColoredText を用意しました。それを Editor に対して使ってみましょう。

const editorRoot = document.getElementById("editor");

const editor = createEditor({
  nodes: [AnyColoredTextNode], // here
  onError: console.error,
});

editor.setRootElement(editorRoot);

registerPlainText(editor);

registerTransformAnyColoredText(editor); // here

createEditor を実行する時点で、自作 Node を登録する必要があります。

さぁ、動作確認してみましょう。下の CoddSandbox のプレビューに "color:red" のような文字列を入力してみてください。 valid なカラーなら何でも大丈夫です。