---
title: "コメントのメンションのクリップボード形式"
description: "メンションのチップを含むコメントのコピー・貼り付けを web・desktop・iOS・Android が同じく読み書きするための形式"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.koyori.app/llms.txt
> Use this file to discover all available pages before exploring further.

# コメントのメンションのクリップボード形式

## 概要

コメントまたはタスクの説明文の入力欄でチップを含む文をコピー・切り取りし、task の入力欄（同じ欄・別のコメント・別のタスク・別の端末の app）へ貼ると、チップのまま戻る。本文は `<@利用者ID>` である。task の外のアプリへ貼ると `@今の名` の素の文字になる。このページは、その往復を web・desktop・iOS・Android のすべてが同じく読み書きするための決まりを定める。親のページは[コメント・アクティビティ](https://docs.koyori.app/dev/features/tasks/collaboration)の @メンションの小節である。

## 用語

| 語 | 意味 |
|---|---|
| チップ | メンションのチップ。画面で `@名` と描く部品である |
| マーカー | メンションのマーカー。本文に埋める `<@利用者ID>` である |
| 版 | `data-task-mention` の値で示す、このページの形式の版である |

## 振る舞い

### 形式

クリップボードには、1 つの項目に 2 つの表現を載せる。独自の MIME 型は足さない。

| MIME 型 | 中身 |
|---|---|
| `text/plain` | チップを `@今の名` に直した文。マーカー（`<@`）も id も含まない |
| `text/html` | 同じ文を、チップの要素つきの HTML 断片にしたもの |

### チップの要素

`text/html` の断片は次の形である。

```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 の実体参照にする。

### 書く側の決まり

1. 選んだ範囲のマーカー `<@id>` をチップの要素に変える。マーカーでない地の文は、実体参照にしたうえで改行を `br` にして並べる
2. `text/plain` には、マーカーを画面のチップと同じ文字に直した文を置く。名前が引ける利用者は状態にかかわらず `@今の名` で、引けない利用者は `@（不明な利用者）`・`@（退会した利用者）`・`@（このプロジェクトの外の利用者）` である
3. 切り取りは、書いたあとに範囲を消す
4. 利用者の id は秘密ではない。画面では見た目のために隠しているだけである。名前を出してよいかはサーバーが決め、サーバーが `mentions` の表で返さなかった名前は `text/plain` にも表示文字にも書かれない

### 読む側の決まり

貼り付けでは、`text/html` を次の順に確かめる。1 つでも外れたら、そのチップはチップにせず、文字（要素の中身）だけ拾う。チップが 1 つも残らなければ、`text/html` は無かったものとして扱い、`text/plain` を素の文字として入れる。

1. `data-task-mention` を持つ要素だけをチップの候補とする。属性が無い要素の `data-user-id` は読まない
2. `data-task-mention` の値が知っている版（今は `1`）か確かめる。知らない値はチップにせず、素の文字にする
3. `data-user-id` がマーカーの形（`[0-9a-fA-F]{8}-…-[0-9a-fA-F]{12}` の 36 字）か確かめる。壊れた id はチップにしない
4. 通ったチップは小文字の 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
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> 確認` である。

読む側がチップにしない例は次のとおりである。いずれも文字だけ入る。

```html
<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 ごとの写し方](#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 が読めない |

Source: https://docs.koyori.app/dev/features/tasks/collaboration-clipboard/index.mdx
