概要
コメントまたはタスクの説明文の入力欄でチップを含む文をコピー・切り取りし、task の入力欄(同じ欄・別のコメント・別のタスク・別の端末の app)へ貼ると、チップのまま戻る。本文は <@利用者ID> である。task の外のアプリへ貼ると @今の名 の素の文字になる。このページは、その往復を web・desktop・iOS・Android のすべてが同じく読み書きするための決まりを定める。親のページはコメント・アクティビティの @メンションの小節である。
用語
| 語 | 意味 |
|---|---|
| チップ | メンションのチップ。画面で @名 と描く部品である |
| マーカー | メンションのマーカー。本文に埋める <@利用者ID> である |
| 版 | data-task-mention の値で示す、このページの形式の版である |
振る舞い
形式
クリップボードには、1 つの項目に 2 つの表現を載せる。独自の MIME 型は足さない。
| MIME 型 | 中身 |
|---|---|
text/plain |
チップを @今の名 に直した文。マーカー(<@)も id も含まない |
text/html |
同じ文を、チップの要素つきの HTML 断片にしたもの |
チップの要素
text/html の断片は次の形である。
<div>見て <span data-task-mention="1" data-user-id="11111111-1111-4111-8111-111111111111">@alice</span> 確認お願いします<br>次の行</div>| 名前 | 意味 |
|---|---|
要素 span |
チップを表す。中身はチップの表示文字(@今の名)。HTML が読める別のアプリは、この文字だけを拾う |
属性 data-task-mention |
チップであることと版を示す。値は 1(このページの形式) |
属性 data-user-id |
利用者の id(ハイフン付き UUID、36 字) |
要素 br |
改行 |
外側の div |
断片の根。他の要素・属性は付けない |
表示文字(@今の名)はコピーした時点の名前で、貼り付け側は使わない。貼り付けた後のチップの名前はその場の対応表から引く。表示文字の特殊文字(& < > ")は HTML の実体参照にする。
書く側の決まり
- 選んだ範囲のマーカー
<@id>をチップの要素に変える。マーカーでない地の文は、実体参照にしたうえで改行をbrにして並べる text/plainには、マーカーを画面のチップと同じ文字に直した文を置く。名前が引ける利用者は状態にかかわらず@今の名で、引けない利用者は@(不明な利用者)・@(退会した利用者)・@(このプロジェクトの外の利用者)である- 切り取りは、書いたあとに範囲を消す
- 利用者の id は秘密ではない。画面では見た目のために隠しているだけである。名前を出してよいかはサーバーが決め、サーバーが
mentionsの表で返さなかった名前はtext/plainにも表示文字にも書かれない
読む側の決まり
貼り付けでは、text/html を次の順に確かめる。1 つでも外れたら、そのチップはチップにせず、文字(要素の中身)だけ拾う。チップが 1 つも残らなければ、text/html は無かったものとして扱い、text/plain を素の文字として入れる。
data-task-mentionを持つ要素だけをチップの候補とする。属性が無い要素のdata-user-idは読まないdata-task-mentionの値が知っている版(今は1)か確かめる。知らない値はチップにせず、素の文字にするdata-user-idがマーカーの形([0-9a-fA-F]{8}-…-[0-9a-fA-F]{12}の 36 字)か確かめる。壊れた id はチップにしない- 通ったチップは小文字の id にして
<@id>に戻し、チップでない文字はそのまま繋ぐ。brと段落の境(div・p・li・pre・blockquote)は改行にする
読み取るのは文字と上の 2 つの属性だけで、HTML の他の要素・属性は使わない。script と style は中身ごと読み飛ばし、実行も描画もしない。
貼り付けと権限
貼り付けで権限は増えない。
- 貼られた
<@id>で通知を送るかは、送信時に backend が判定する。宛先の範囲(プロジェクトに入れる利用者とテナント owner)は変わらず、範囲外・存在しない id は通知せずに保存する。clipboard から来た id でも同じである - チップの表示(
member・outside・gone)は、貼った先のコメント API が返す対応表に従う。clipboard に載った名前は使わないので、他人の環境から来た clipboard でoutsideの利用者の名前を引き出すことはできない - task の外から来た HTML に紛れた id は、
data-task-mention="1"が付いていなければチップにならない。付いていても、読む側の決まりの id の形でなければチップにならない - 属性を付けて偽った場合も、起きるのは「その id が本文に入る」ことだけで、手で
<@id>と打っても同じ結果になる。新しい権限の経路は生まれない
platform ごとの写し方
native の clipboard は、どれも「1 つの項目に複数の表現を載せ、型の名前で引く」作りである。text/plain と text/html は次の名前に対応する。
| platform | text/plain |
text/html |
注記 |
|---|---|---|---|
| web(Chromium・Firefox・Safari) | clipboardData.setData('text/plain', …) |
setData('text/html', …) |
貼り付けは paste event の getData('text/html') |
| Windows | CF_UNICODETEXT |
登録名 HTML Format(CF_HTML) |
UTF-8。Version・StartHTML・EndHTML・StartFragment・EndFragment の byte offset を持つ先頭部分と、断片を挟む <!--StartFragment-->・<!--EndFragment--> が要る。断片の中はチップの要素の div である |
| macOS | NSPasteboard.PasteboardType.string |
NSPasteboard.PasteboardType.html(public.html) |
1 つの NSPasteboardItem に両方の表現を載せる |
| iOS | public.utf8-plain-text(UTType.plainText) |
public.html(UTType.html) |
UIPasteboard.setItems で 1 つの項目に両方を載せる |
| Android | ClipData の text |
ClipData.newHtmlText(label, text, htmlText) の htmlText |
text は HTML を読めない受け手のための素の文字(@今の名)。MIME 型は text/html と text/plain |
native の app は、読む側の決まりをそのまま使う。HTML を DOM に直せない環境でも、data-task-mention="1" と data-user-id="…" を持つ span の 2 つの属性だけ取れれば足りる。
出所と確かめた範囲
- web の
clipboardDataとtext/htmlは、MDN「ClipboardEvent: clipboardData」による - Windows の
HTML Format(CF_HTML)は、Microsoft Learn「HTML Clipboard Format」による - iOS・macOS の pasteboard が 1 つの項目に複数の表現を型(UTI)で持つことは、Apple「Pasteboard Concepts」、
UIPasteboard.setItems(_:options:)による - Android の
ClipData.newHtmlText(textを HTML を読めない受け手の素の文字として必須)は、Android Developers「ClipData」による - 実測は Linux の Playwright 1.63 で行った。Chromium 153・Firefox 155・WebKit 26.6 のそれぞれで、実際のキー操作の copy と paste で
text/htmlのdata-task-mention・data-user-idが欠けずに届き、text/plainは@今の名のまま届く
例
本文が 見て <@11111111-1111-4111-8111-111111111111> 確認 のとき、選んだ文は次の形になる。
text/plain: 見て @alice 確認
text/html : <div>見て <span data-task-mention="1" data-user-id="11111111-1111-4111-8111-111111111111">@alice</span> 確認</div>読む側が出す本文は 見て <@11111111-1111-4111-8111-111111111111> 確認 である。
読む側がチップにしない例は次のとおりである。いずれも文字だけ入る。
<span data-user-id="11111111-1111-4111-8111-111111111111">@x</span>
<span data-task-mention="2" data-user-id="11111111-1111-4111-8111-111111111111">@x</span>
<span data-task-mention="1" data-user-id="not-a-uuid">@x</span>未実装と既知の制限
- desktop の app・iOS の app・Android の app の読み書きが無い。このページの形式をplatform ごとの写し方で実装する。このリポジトリの frontend は web で、native の app の作りは無い
- 版
2以降の拡張(例は表示文字の持ち方の変更)は決まっていない。読む側は知らない版を素の文字にするので、先に書く側を新しくしても古い読む側は壊れない - Windows・macOS・iOS・Android の native と、macOS・iOS の Safari の実機は確かめていない。特に、native の app が
text/htmlを貼るときにdata-*属性を落とさないかは、実装の段階で確かめる
決定の記録
| 日付 | 決定 | 理由 |
|---|---|---|
| 2026-10-18 | 独自の MIME 型を足さず、text/plain と text/html の 2 つの表現だけを載せる |
web の中だけで閉じる形式(Chromium の web custom format、DataTransfer の独自の型)に頼ると、OS のクリップボードを通る native の app が読めない |
