docs-matrix-spec/locales/zh-Hans/client-server-api/modules/mentions.md

用户和房间提及

{{% changed-in v="1.7" %}}

本模块允许用户在房间事件中“提及”其他用户和房间。 这主要用于指示收件人应接收到关于该事件的通知。 通过在事件的 m.mentions 内容属性中包含元数据以引用被提及的实体来实现这一点。

m.mentions 的定义如下：

{{% definition path="api/client-server/definitions/m.mentions" %}}

一个事件的内容示例如下：

{
    "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_room_mention 推送规则。 用户不应将自己的 Matrix ID 添加到 m.mentions 属性中，因为发出的消息无法对本人进行通知。

{{% boxes/warning %}} 如果加密事件的载荷中包含 m.mentions，应像普通内容一样进行加密。为正确处理加密房间中的提及，必须首先对事件进行解密。参见接收通知。 {{% /boxes/warning %}}

请注意，为了向后兼容，像 .m.rule.contains_display_name、 .m.rule.contains_user_name 和 .m.rule.roomnotif 这样的推送规则，仍将在事件的 body 包含用户显示名或 ID 时匹配。为避免无意的通知，建议客户端在每个事件中都包含一个 m.mentions 属性。（若无提及内容，可为一个空对象。）

{{% boxes/rationale %}} 在以往的规范版本中，用户提及是通过在事件明文 body 中包含用户的显示名或其 Matrix ID localpart 实现的，而房间提及则是包含字符串“@room”。这种方式容易导致混乱和 bug。 {{% /boxes/rationale %}}

客户端行为

虽然可以悄悄地提及用户，但推荐在 m.room.message 事件的 HTML 正文中包含一个 Matrix URI。这仅适用于 msgtype 为 m.text、m.emote 或 m.notice 的 m.room.message 事件。事件的 format 必须为 org.matrix.custom.html，因此需要有 formatted_body。

客户端在向即将发送的事件中添加用于提及的 Matrix URI 时，应遵循以下准则：

• 当链接到用户时，在锚文本中显示用户可能存在歧义的显示名。若用户无显示名，则使用用户的 ID。
• 当链接到房间时，使用该房间的规范别名（canonical alias）。若房间无规范别名，则优先使用房间上列出的别名之一。若找不到任何别名，则退回到房间 ID。在所有情况下，锚文本应为所链接的别名或房间 ID。

锚文本部分应在事件的 body 中用于原本表示该链接的位置，如上例所示。

客户端应将提及与其他元素区分开来。例如，可以通过改变提及的背景色以突出其与普通链接的不同。

如果当前用户在消息中被提及，客户端应将此提及以不同于其他提及的方式显示，例如使用红色背景以提醒用户本人被提及。请注意，用户可能会被提及但事件中未包含其 Matrix URI。

点击提及时，应导航到相应的用户或房间信息。