56 lines
No EOL
3.4 KiB
Markdown
56 lines
No EOL
3.4 KiB
Markdown
### 用户和房间提及
|
||
|
||
{{% changed-in v="1.7" %}}
|
||
|
||
本模块允许用户在房间事件中“提及”其他用户和房间。 这主要用于指示收件人应接收到关于该事件的通知。 通过在事件的 `m.mentions` 内容属性中包含元数据以引用被提及的实体来实现这一点。
|
||
|
||
`m.mentions` 的定义如下：
|
||
|
||
{{% definition path="api/client-server/definitions/m.mentions" %}}
|
||
|
||
一个事件的内容示例如下：
|
||
|
||
```json
|
||
{
|
||
"body": "Hello Alice!",
|
||
"msgtype": "m.text",
|
||
"format": "org.matrix.custom.html",
|
||
"formatted_body": "Hello <a href='https://matrix.to/#/@alice:example.org'>Alice</a>!",
|
||
"m.mentions": {
|
||
"user_ids": ["@alice:example.org"]
|
||
}
|
||
}
|
||
```
|
||
|
||
此外，请参阅 [`.m.rule.is_user_mention`](#_m_rule_is_user_mention) 和
|
||
[`.m.rule.is_room_mention`](#_m_rule_is_room_mention) 推送规则。
|
||
用户不应将自己的 Matrix ID 添加到 `m.mentions` 属性中，因为发出的消息无法对本人进行通知。
|
||
|
||
{{% boxes/warning %}}
|
||
如果加密事件的载荷中包含 `m.mentions`，应像普通内容一样进行加密。为正确处理加密房间中的提及，必须首先对事件进行解密。参见[接收通知](#receiving-notifications)。
|
||
{{% /boxes/warning %}}
|
||
|
||
请注意，为了向后兼容，像 [`.m.rule.contains_display_name`](#_m_rule_contains_display_name)、
|
||
[`.m.rule.contains_user_name`](#_m_rule_contains_user_name) 和
|
||
[`.m.rule.roomnotif`](#_m_rule_roomnotif) 这样的推送规则，仍将在事件的 `body` 包含用户显示名或 ID 时匹配。为避免无意的通知，**建议客户端在每个事件中都包含一个 `m.mentions` 属性**。（若无提及内容，可为一个空对象。）
|
||
|
||
{{% boxes/rationale %}}
|
||
在以往的规范版本中，用户提及是通过在事件明文 `body` 中包含用户的显示名或其 Matrix ID localpart 实现的，而房间提及则是包含字符串“@room”。这种方式容易导致混乱和 bug。
|
||
{{% /boxes/rationale %}}
|
||
|
||
#### 客户端行为
|
||
|
||
虽然可以悄悄地提及用户，但推荐在 [m.room.message](#mroommessage) 事件的 HTML 正文中包含一个 [Matrix URI](/appendices/#uris)。这仅适用于 `msgtype` 为 `m.text`、`m.emote` 或 `m.notice` 的 [m.room.message](#mroommessage) 事件。事件的 `format` 必须为 `org.matrix.custom.html`，因此需要有 `formatted_body`。
|
||
|
||
客户端在向即将发送的事件中添加用于提及的 `Matrix URI` 时，应遵循以下准则：
|
||
|
||
- 当链接到用户时，在锚文本中显示用户可能存在歧义的显示名。若用户无显示名，则使用用户的 ID。
|
||
- 当链接到房间时，使用该房间的规范别名（canonical alias）。若房间无规范别名，则优先使用房间上列出的别名之一。若找不到任何别名，则退回到房间 ID。在所有情况下，锚文本应为所链接的别名或房间 ID。
|
||
|
||
锚文本部分应在事件的 `body` 中用于原本表示该链接的位置，如上例所示。
|
||
|
||
客户端应将提及与其他元素区分开来。例如，可以通过改变提及的背景色以突出其与普通链接的不同。
|
||
|
||
如果当前用户在消息中被提及，客户端应将此提及以不同于其他提及的方式显示，例如使用红色背景以提醒用户本人被提及。请注意，用户可能会被提及但事件中未包含其 `Matrix URI`。
|
||
|
||
点击提及时，应导航到相应的用户或房间信息。 |