猫でもわかるWebプログラミングと副業

本業Webエンジニア。副業でもWebエンジニア。Web開発のヒントや、副業、日常生活のことを書きます。

Yjs の「Awareness & Presence」ドキュメントを読む

f:id:yoshiki_utakata:20220210150014j:plain

docs.yjs.dev

※ Yjs は、ドキュメント共同編集用のライブラリです。

※ Awareness 、あるいは、 Awareness 情報というのは、ドキュメント共同編集の際の、各ユーザーのカーソルの位置など、ドキュメントの更新以外の情報のことを指します。

Awareness & Presence

Awareness は、共同編集のアプリケーションにおいて、重要となります。

共同編集エディタの章 で、ユーザー間で同期するエディタを実装しました。

しかし、もっといろんな情報を共有した方が、仕事が効率的になります。例えば、カーソルの位置を共有すれば、もっと他のユーザーの状況がわかりやすくなります。

さらに、ユーザーごとに名前をつけたり、色を変えたりすれば、もっとわかりやすくなります。

このような情報も、Awareness 情報には含まれています。

これにより、他のユーザーがしようとしていることが分かりやすくなります。

※もし、このような Awareness 情報を共有しないのであれば、この章は飛ばして、必要な時に戻ってきてください。

Awareness 情報は、Yjs ドキュメントには保存されていない情報です。一時的に必要な情報であって、保存する必要はないからです。

Awareness 情報は、JSON形式で、他のユーザーと共有されます。

もしあなたがオフラインになったら、あなたの Awareness state は全てのユーザーの Awarenes state から削除され、あなたがオフラインになったことが通知されます。

このような Awareness 情報はオプショナルなものですが、ネットワーク Provider(Websocket など、ネットワークを経由して各編集者の状態を共有する仕組みを提供するもの)は Awareness 情報の共有機能を実装するのがオススメです。

Yjs 公式から提供されている全ての Provider は Awareness CRDT を実装しています(CRDT は、ドキュメントの編集をユーザー間で衝突なく共有するプロトコルで、それに Awareness 情報を追加したものが Awareness CRDT)。

このチュートリアルでは、Awareness CRDT を利用して、 Quill editor (リッチエディタのライブラリ)でカーソルの場所の表示を実装してみたいと思います。

Quick start: Awareness CRDT

以下は、 Awareness CRDT を Provider から取得する例です。"user" に、名前と色を設定することで、全てのユーザーにこの情報が共有されます。

// Yjs から提供されている全ての provider は awareness CRDT が実装されている
const awareness = provider.awareness

// awareness情報が更新された時はイベントを受け取る
awareness.on('change', changes => {
  // もし、誰かの Awareness 情報が更新されたら、
  // 全員の Awareness 情報をログに出力sる
  console.log(Array.from(awareness.getStates().values()))
})

// 自分の Awareness 情報を key-value ストアにセットできる
// "user" を更新することでユーザー情報を更新できる
awareness.setLocalStateField('user', {
  // 表示される名前
  name: 'Emmanuelle Charpentier',
  // 表示される時の色
  color: '#ffb61e' // should be a hex color
})

Awareness CRDT には、JSONエンコード可能な値であればなんでもセットできます。通常は、cursor フィールドでカーソルの位置を共有します。user でカーソルの色や、カーソルの上で表示する名前を共有します。

カーソル位置を表示することが可能なエディタであれば、これを使ってカーソル位置を表示できます。user フィールドが指定されていない場合は、ランダムな名前と、デフォルトのカーソルの色で表示されます。

const binding = new QuillBinding(ytext, quill, provider.awareness)

チュートリアルで紹介する機能は以上です。

Awareness に関する全ての情報を知りたい場合は、以下のドキュメントを参考にしてください。

docs.yjs.dev

この日本語訳の元になったドキュメントはこちら

docs.yjs.dev