@メンション

@ と数文字を入力して、一覧から人物を選びます。エディターは、その人の ID を持つ小さな編集不可のチップを挿入するため、サーバーで誰へのメンションかを判別できます。一覧には、静的な配列、またはサーバーに問い合わせる関数を使えます。

有効にする

この機能は mentionplugin.js プラグインで提供されます（plugins/all_plugins.js にも含まれます）。ツールバーボタンはなく、トリガー文字を入力するとピッカーが開きます。@ のトリガーは、一覧または取得元を指定した場合にのみ登録されるため、読み込むだけでは何も起きません。

<link rel="stylesheet" href="/richtexteditor/rte_theme_default.css">
<script src="/richtexteditor/rte.js"></script>
<script src="/richtexteditor/plugins/mentionplugin.js"></script>

<div id="editor"><p>Thanks for the review.</p></div>
<script>
var editor = new RichTextEditor("#editor", {
    mentionStaticList: [
        { id: "u1", label: "Ana Ruiz", subtitle: "ana@example.com" },
        { id: "u2", label: "Ben Okafor", subtitle: "ben@example.com" },
        { id: "u3", label: "Bea Lindqvist", subtitle: "bea@example.com" },
        { id: "u4", label: "Chen Wei", subtitle: "chen@example.com" }
    ]
});
</script>

各項目には id と label が必要です。subtitle と avatarUrl は省略可能で、アバターがなければイニシャルを表示します。{ id, name, email } の形式も使えます。name をラベル、email をサブタイトルとして使います。

サーバーへの問い合わせ

実際のユーザーディレクトリを使うには、代わりに mentionSource を渡します。トリガーの後に入力したテキストを受け取り、配列、または配列を解決値とする Promise を返します。実行中は「Searching…」、結果が空の場合は「No matches」と表示します。

var people = [{ id: 7, name: "Ana Ruiz", email: "ana@example.com" }, { id: 9, name: "Ben Okafor", email: "ben@example.com" }];
var editor = new RichTextEditor("#editor", {
    mentionSource: function (query, ctx) {
        // ctx.trigger is "@"; replace this with a fetch to your own endpoint
        return new Promise(function (resolve) {
            setTimeout(function () {
                resolve(people.filter(function (p) { return p.name.toLowerCase().indexOf(query.toLowerCase()) >= 0; }));
            }, 100);
        });
    }
});

トリガー直後の最初の呼び出しは、空のクエリですぐに実行します。以後は最後の入力から mentionDebounceMs 待って実行します。新しいクエリより後に届いた古い応答は破棄します。

オプション

オプション	既定値	動作
`mentionStaticList`	`null`	人物の配列です。ラベル、サブタイトル、ID に対して大文字と小文字を区別せず照合します。クエリが空なら先頭 50 件を表示します。
`mentionSource`	`null`	配列または Promise を返す `function (query, ctx)` です。静的な一覧と両方を設定した場合はこちらを使います。
`mentionTrigger`	`"@"`	ピッカーを開く文字です。
`mentionMaxItems`	`8`	一度に表示する最大項目数です。
`mentionDebounceMs`	`150`	再度取得元を呼び出すまでの、入力後の待ち時間です。
`mentionInsertClass`	`"rte-mention"`	挿入したチップに付けるクラスです。
`mentionTriggers`	`null`	追加のトリガー定義の配列です。下記の `register` と同じ形式で、起動時に登録します。
`mentionEnabled`	`true`	`false` にすると無効になり、`editor.mentions` も作成されません。

追加のトリガーと API

editor.mentions.register() で、タグ用の # などのトリガーを追加します。上記と同じ source(query, ctx)、または search(query, done) を渡し、後者では done(list) を呼び出します。

editor.mentions.register({
    trigger: "#",
    search: function (query, done) { done([{ id: "t-12", label: "release-2.6" }, { id: "t-13", label: "billing" }]); },
    insertClass: "tag-chip"
});

定義には、一覧の行のテキストまたはノードを返す renderItem(item)、チップのテキストまたはノードを返す renderInsert(item)、一覧のアクセシブルな名前である label も指定できます。ほかのメソッドは editor.mentions.remove(trigger)、list()、close()、isOpen() です。

ピッカーを開いている間は、ArrowUp と ArrowDown で移動し、Enter または Tab で挿入し、Escape で閉じます。空白を入力しても閉じます。行の先頭か空白の後でのみ開くため、mail@example.com のようなメールアドレスでは開きません。<code>、<pre>、既存のチップ内でも開きません。

注意点

保存される HTML は次のとおりです。チップの後に改行しない空白を付け、カーソルを置けるようにします。
```
<p>Thanks for the review. <span class="rte-mention" contenteditable="false" data-rte-mention-id="u1" data-rte-mention-trigger="@">@Ana Ruiz</span>&nbsp;and ...</p>
```
通知を送るには、サーバーで data-rte-mention-id を読み取ります。HTML をサニタイズする場合は、class、contenteditable、2 つの data-rte-mention-* 属性を持つ span を許可してください。
チップの丸みのあるスタイルはエディター内にのみ追加します。表示先には .rte-mention 用の CSS が必要です。独自の insertClass にはスタイルを付けません。
トリガーは押されたキーと比較するため、1 文字にする必要があります。
ピッカーの文言は、言語キー text_mn_searching と text_mn_nomatches から取得します。

関連情報：@メンションのデモ、設定リファレンス。