# 自定义参与者排序
<a name="ssc-getting-started-custom-participant-ordering"></a>

借助自定义参与者排序功能，您可以根据参与者令牌中的自定义属性值控制参与者在网格和 PiP 布局中的定位，包括特写参与者的定位和 PiP 窗口中的参与者选择。这提供了确定性定位功能，可实现基于角色的布局。

## 自定义排序的工作原理
<a name="ssc-getting-started-custom-participant-ordering-how-custom-ordering-works"></a>

在布局配置中指定 `participantOrderAttribute` 后，系统将根据以下规则对参与者进行排序：
+ 令牌中包含指定排序属性的参与者排在最前，按其属性值的数值大小进行排序。
+ 缺少排序属性的参与者将重新按到达时间排序，并排在已排序的参与者之后。
+ 如有多个参与者的排序值相同，则按其进入舞台的时间再次排序。
+ 排序按数值大小（不是字典顺序）进行，因此“10”排在“9”之后，而不是在“1”之后。
+ 支持负值。负值应排于正值之前。
+ 非整数值（例如“abc”、“1.5”）将视为无效，这些参与者会重新按到达时间排序。

**重要提示：**参与者排序（无论是基于到达时间还是自定义）将在合成开始后生效。对于在合成开始之前进入舞台的参与者，无法保证参与者的正确排序。

## 创建具有排序属性的令牌
<a name="ssc-getting-started-custom-participant-ordering-creating-tokens-with-ordering-attributes"></a>

要使用自定义参与者排序功能，请在创建参与者令牌时将排序属性包含在其中：

```
aws ivs-realtime create-participant-token --stage-arn "arn:aws:ivs:us-east-1:123456789012:stage/u9OiE29bT7Xp" --attributes order=1

aws ivs-realtime create-participant-token --stage-arn "arn:aws:ivs:us-east-1:123456789012:stage/u9OiE29bT7Xp" --attributes order=2

aws ivs-realtime create-participant-token --stage-arn "arn:aws:ivs:us-east-1:123456789012:stage/u9OiE29bT7Xp" --attributes order=3
```

您可以将自定义参与者排序属性与用于为精选槽位和 PiP 窗口选择参与者的属性相结合：

```
aws ivs-realtime create-participant-token --stage-arn "arn:aws:ivs:us-east-1:123456789012:stage/u9OiE29bT7Xp" --attributes order=2,isFeatured=true

aws ivs-realtime create-participant-token --stage-arn "arn:aws:ivs:us-east-1:123456789012:stage/u9OiE29bT7Xp" --attributes order=3,isFeatured=true

aws ivs-realtime create-participant-token --stage-arn "arn:aws:ivs:us-east-1:123456789012:stage/u9OiE29bT7Xp" --attributes order=4,isPip=true
```

## 使用案例示例
<a name="ssc-getting-started-custom-participant-ordering-example-use-cases"></a>

示例使用案例包括：
+ 一致的定位：参与者使用相同的令牌重新连接时会保持原来的位置。
+ 基于角色的定位：例如，您可以指定教师的顺序为 1，学生的顺序为 2。
+ 基于优先级的布局：顺序值较低的 VIP 参与者将首先出现。
+ 动态布局：您可以将自定义排序与 `featuredParticipantAttribute` 和 `pipParticipantAttribute` 组合使用，以满足复杂场景的需要。
+ 跨舞台互动：在 VS 模式竞赛等场景中使用参与者复制功能时，来自不同舞台的主播将进行互动，您可以通过覆盖排序属性来控制目标舞台合成中的定位。

**注意：**对于参与者复制使用案例，您可以在开始复制时根据需要覆盖参与者属性（包括排序属性），以在目标舞台中实现所需的布局。

## 向后兼容
<a name="ssc-getting-started-custom-participant-ordering-backward-compatibility"></a>

自定义参与者排序是一项可选功能，并且完全向后兼容。没有 `participantOrderAttribute` 属性的现有合成会继续正常运行，按到达时间排序。将 `participantOrderAttribute` 设置为空字符串时，系统将完全忽略自定义排序并回退到默认行为。