67 lines
No EOL
3.2 KiB
Markdown
67 lines
No EOL
3.2 KiB
Markdown
### 事件注释与反应
|
||
|
||
{{% added-in v="1.7" %}}
|
||
|
||
#### `m.annotation` 关系类型
|
||
|
||
注释是一类采用[event 关系](#forming-relationships-between-events)并带有 `rel_type` 为 `m.annotation` 的事件。
|
||
|
||
注释通常用于“反应”：例如，如果用户想要对某个事件表示点赞，则客户端会发送一个带有相应表情（如👍）的注释事件。另一个可能的用例是让机器人发送事件来指示某条命令的成功或失败。
|
||
|
||
除了标准属性 `event_id` 和 `rel_type` 外，`m.relates_to` 属性中的 `rel_type: m.annotation` 应包含一个 `key`，用于表示所应用的注释。例如，在使用表情符号进行反应时，key 包含所使用的表情符号。
|
||
|
||
如下所示是一个 `m.annotation` 关系的示例：
|
||
|
||
```json
|
||
"m.relates_to": {
|
||
"rel_type": "m.annotation",
|
||
"event_id": "$some_event_id",
|
||
"key": "👍"
|
||
}
|
||
```
|
||
|
||
{{% boxes/note %}}
|
||
任何类型的事件都可以被注释，包括状态事件。
|
||
{{% /boxes/note %}}
|
||
|
||
#### 事件
|
||
|
||
{{% event event="m.reaction" %}}
|
||
|
||
#### 客户端行为 {id="annotations-client-behaviour"}
|
||
|
||
注释设计的意图是对其进行计数，而不是单独展示。客户端必须为每个事件统计他们观察到的给定事件 `type` 和注释 `key` 的注释数量；这些计数通常在时间线上与事件一起显示。
|
||
|
||
在进行计数时：
|
||
|
||
* 每个事件 `type` 和注释 `key` 通常应分别计数，但是否实际分开计数取决于具体的实现。
|
||
|
||
* [被忽略用户](#ignoring-users)发送的注释事件应排除在计数之外。
|
||
|
||
* 来自同一用户（即 `sender` 相同）的多个完全相同的注释（即 `type` 与 `key` 都相同）应计为一次注释。
|
||
|
||
* 对于引用了自身带有 `m.relates_to`，其 `rel_type` 为 `m.annotation` 或 `rel_type` 为 `m.replace` 的事件的注释事件，实现应忽略。换句话说，[替换事件](#event-replacements)或注释本身不能被再次注释。注释应仅指向原始事件。
|
||
|
||
* 当某个注释被撤回时，应从计数中移除。
|
||
|
||
{{% boxes/note %}}
|
||
反应不可编辑，因为替换事件不会更改 `m.relates_to`（见[应用 `m.new_content`](#applying-mnew_content)），并且 `m.reaction` 中没有其他有意义的内容。如果用户希望更改自己的反应，应该撤回原始反应，并发送新的反应事件替代。
|
||
{{% /boxes/note %}}
|
||
|
||
{{% boxes/note %}}
|
||
`m.reaction` 中的 `key` 字段可以为任意字符串，因此客户端在渲染过长反应内容时需采取合理方式。例如，客户端可以省略过长的反应内容。
|
||
{{% /boxes/note %}}
|
||
|
||
#### 服务器行为
|
||
|
||
##### 避免重复注释
|
||
|
||
HomeServer 应当防止用户针对同一事件，使用相同的事件 `type` 和注释 `key` 发送第二次注释（除非第一次发送的事件已被撤回）。
|
||
|
||
试图发送此类注释应返回 400 错误以及错误码 `M_DUPLICATE_ANNOTATION`。
|
||
|
||
但这并不能保证重复的注释不会通过联邦网络到达。客户端在[计数注释](#annotations-client-behaviour)时有责任对接收到的注释进行去重。
|
||
|
||
##### 服务器端对 `m.annotation` 关系的聚合
|
||
|
||
`m.annotation` 关系**不会**被服务器[聚合](#aggregations-of-child-events)。换句话说，`m.annotation` 不会包含在 `m.relations` 属性中。 |