你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
UI 库用例
使用 Azure 通信服务 UI 库中的组件和复合组件在应用程序中创建通话和聊天体验。
在复合组件中，通话和聊天功能是直接内置的，并在你将复合组件集成到应用程序中时公开。 在 UI 组件中，通话和聊天功能通过组合 UI 功能和基础的有状态库来公开。 为了充分利用这些功能，建议将 UI 组件与有状态的通话和聊天客户端库结合使用。
请在 UI 库 Storybook 中获取更多概念文档、快速入门和示例。
通话用例
| 区域 | 用例 |
|---|---|
| 通话类型 | 加入 Microsoft Teams 会议 |
| 使用组 ID 加入 Azure 通信服务通话 | |
| 加入 Azure 通信服务会议室 | |
| 向另一名 Azure 通信服务用户发起出站呼叫 | |
| 向一个电话号码发起出站呼叫 | |
| Teams 互操作性 | 加入通话大厅 |
| 显示听录和录制警报横幅 | |
| 通话控件 | 对通话进行静音和取消静音 |
| 在通话期间打开和关闭视频 | |
| 打开屏幕共享 | |
| 结束呼叫 | |
| 参与者库 | 在网格上显示远程参与者 |
| 本地用户可在整个通话期间进行视频预览 | |
| 视频关闭时默认头像可用 | |
| 在参与者库中显示共享屏幕内容 | |
| 通话配置 | 管理麦克风设备 |
| 管理相机设备 | |
| 管理扬声器设备 | |
| 为用户提供本地预览以查看视频 | |
| 参与者 | 显示参与者名单 |
聊天用例
| 区域 | Azure Communication Services Chat | Teams 互操作性聊天 |
|---|---|---|
| 聊天类型 | 加入 Azure 通信服务聊天线程 | 加入 Microsoft Teams 会议聊天 |
| 聊天操作 | 发送和接收文本消息 | 发送和接收文本消息 |
| 发送和接收富文本消息* | 发送和接收富文本消息* | |
| - | 接收内联图像 | |
| 发送和接收文件附件 | 接收文件附件* | |
| 聊天事件 | 发送和接收键入指示符 | 发送和接收键入指示符** |
| 发送和接收已读回执 | 发送和接收已读回执 | |
| 显示添加或移除参与者的时间 | 显示添加或移除参与者的时间 | |
| 参与者 | 显示参与者名单 | 显示参与者名单 |
*发送富文本消息和文件附件支持目前为公共预览版。 预览版 API 和 SDK 在没有服务级别协议的情况下提供。 建议不要将它们用于生产工作负荷。 某些功能可能不受支持或者已受限。 有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。
**无法正确显示 Teams 用户键入事件的显示名称。
支持的标识
若要初始化复合并对服务进行身份验证，用户必须具有 Azure 通信服务标识。 有关详细信息，请参阅对 Azure 通信服务进行身份验证和快速入门：创建和管理访问令牌。
Teams 互操作性
对于 Teams 互操作性方案，可以使用 UI 库复合通过通信服务将用户添加到 Teams 会议。 若要启用 Teams 互操作性，请使用通话复合组件或聊天复合组件中的默认功能，或使用 UI 组件生成自定义体验。
在同时将通话和聊天添加到应用程序时，请务必记住，在参与者获得许可加入通话后才可初始化聊天客户端。 参与者获得许可后，便可以初始化聊天客户端以加入会议聊天线程。 下图中展示了此模式：
如果使用 UI 组件实现 Teams 互操作性体验，请首先使用 UI 库示例创建体验的关键部分：
- 大厅示例。 参与者等待获得许可加入通话的示例大厅。
- 合规性横幅。 向用户显示是否正在录制通话的示例横幅。
- Teams 主题。 使 UI 库看起来像 Microsoft Teams 的示例主题。
- 图像共享*。 示例：Azure 通信服务最终用户可以接收 Teams 用户发送的图像。
- 文件共享。 示例：Azure 通信服务最终用户可以接收 Teams 用户发送的文件附件。
自定义
使用 UI 库模式修改组件，使其匹配应用程序的外观。 自定义是通信服务中复合组件和 UI 组件之间的一个关键区别。 复合组件提供的自定义选项较少，可实现更简单的集成体验。
下表比较了复合组件和 UI 组件的自定义用例：
| 使用案例 | 复合物 | UI 组件 |
|---|---|---|
| 使用基于 Fluent 的主题 | X | X |
| 编写体验布局 | X | |
| 使用 CSS 样式修改样式属性 | X | |
| 替换图标 | X | |
| 修改参与者库布局 | X | |
| 修改通话控件布局 | X | X |
| 插入数据模型来修改用户元数据 | X | X |
可观察性
UI 库的状态管理体系结构已分离，因此你可以直接访问有状态的通话和聊天客户端。 可以连接到有状态客户端来读取状态、处理事件并替代传入 UI 组件的行为。
下表比较了复合组件和 UI 组件的可观测性用例：
| 使用案例 | 复合物 | UI 组件 |
|---|---|---|
| 访问通话和聊天客户端状态 | X | X |
| 访问和处理客户端事件 | X | X |
| 访问和处理 UI 事件 | X | X |
建议体系结构
使用 Azure 通信服务访问令牌初始化复合组件和基本组件。 请务必通过你所管理的受信任服务从通信服务获取访问令牌。 有关详细信息，请参阅快速入门：创建和管理访问令牌以及受信任的服务教程。
通话和聊天客户端库必须具有其加入的通话或聊天的上下文。 与用户访问令牌一样，使用你自己的受信任服务将上下文传播给客户端。
下表汇总了将上下文添加到客户端库所需的初始化和资源管理功能：
| Contoso 责任 | UI 库责任 |
|---|---|
| 从 Azure 提供访问令牌 | 传递提供的访问令牌来初始化组件 |
| 提供刷新功能 | 使用开发人员提供的功能刷新访问令牌 |
| 检索和传递用于通话或聊天的加入信息 | 传递通话和聊天信息以初始化组件 |
| 检索和传递任何自定义数据模型的用户信息 | 将自定义数据模型传递到要呈现的组件 |
平台支持
| SDK 中 IsInRole 中的声明 | Windows | macOS | Ubuntu | Linux | Android | iOS |
|---|---|---|---|---|---|---|
| UI SDK | Chrome*、Microsoft Edge | Chrome*、Safari** | Chrome* | Chrome* | Chrome* | Safari** |
* 支持当前版本的 Chrome 和上述两个版本。
** 支持 Safari 13.1 版及更高版本。 尚不支持 Safari macOS 的传出视频，但它在 iOS 上受支持。 仅桌面 iOS 支持传出屏幕共享。
可访问性
辅助功能设计是 Microsoft 产品的一项原则。 UI 库遵循这一原则，且所有 UI 组件都是完全可访问的。
本地化
本地化是制造可由世界各地说不同语言的人使用的产品的关键。 UI 库为某些语言和功能（包括从右到左书写的语言）提供默认支持。 可以提供自己的本地化文件，与 UI 库结合使用。
已知问题
- 目前，在编辑现有消息时，UI 库不支持更新消息类型。 将格式文本格式设置添加到现有消息会将 HTML 样式设置添加到文本内容。 由于这不会更改消息类型，因此可能会导致在消息线程中将 HTML 内容显示为纯文本。
使用 Azure 通信服务 UI 库中的 CallComposite 和 ChatComposite 在 iOS 和 Android 应用程序中创建通话体验。 通过使用几行代码，可以轻松地在应用程序中集成整个通话和聊天体验。 通信服务中的复合管理通话和聊天的整个生命周期（从设置到通话和聊天结束）。
通话用例
可以使用通信服务中的通话复合来创建这些用例：
| 区域 | 用例 |
|---|---|
| 通话类型 | 加入 Microsoft Teams 会议 |
| 使用会议 ID 和密码加入 Microsoft Teams 会议 | |
| 使用组 ID 加入通话 | |
| 使用会议室 ID 加入通话 | |
| 拨打和接收 1:1 通话 | |
| Teams 互操作性 | 加入通话大厅 |
| 显示听录和录制警报横幅 | |
| 允许/拒绝大厅参与者 | |
| 隐藏式字幕 | Teams 互操作性 |
| 群组通话、会议室通话和一对一通话 | |
| 参与者库 | 在网格上显示远程参与者 |
| 本地用户可在整个通话期间进行视频预览 | |
| 视频关闭时默认头像可用 | |
| 在参与者库中显示共享屏幕内容 | |
| 启用参与者头像自定义 | |
| 显示参与者名单 | |
| 通话管理 | 管理麦克风设备 |
| 管理相机设备 | |
| 管理扬声器设备（有线或蓝牙） | |
| 用户可使用本地预览来查看视频 | |
| 订阅事件 | |
| 通话控件 | 对通话进行静音和取消静音 |
| 在通话期间打开或关闭视频 | |
| 结束呼叫 | |
| 暂停通话以及在音频中断后恢复通话 | |
| CallKit 和 TelecomManager 支持 | |
| 自定义体验 | 按钮栏自定义 |
| 标题和副标题配置 | |
| 启用终止呼叫确认对话 | |
| 跳过设置屏幕 |
通话集成
Teams 互操作性
对于 Teams 互操作性方案，可以使用 UI 库复合通过通信服务将用户添加到 Teams 会议。 若要启用 Teams 互操作性，请使用通话复合。 复合管理加入 Teams 互操作性通话的整个生命周期。
下图显示了在将呼叫方添加到 Teams 会议之前用户体验的示例：
会议室集成
Azure 通信服务为正在构建结构化对话（如虚拟约会或虚拟事件）的开发人员提供会议室的概念。 会议室当前允许进行语音和视频通话。
聊天室是管理 Azure 通信服务最终用户之间活动的容器。 通过聊天室，应用程序开发人员可以更好地控制谁可以加入通话、何时见面以及如何协作。 若要详细了解聊天室，请参阅概念文档。
用会议室 API 邀请用户到会议室中担任以下 3 个角色中的 1 个：
- 演示者（默认）
- 与会者
- 使用者
每个角色之间的区别在于他们在进行会议室通话时使用 CallComposite 所拥有的功能。 此处详细介绍了与每个角色关联的具体功能。
注意
会议室 API 用于创建聊天室、管理用户和调整会议室的生存期。 请务必注意，会议室 API 是独立于 UI 库的后端服务。
一对一通话和推送通知支持
UI 库支持一对一 VoIP 通话，通过通信标识符拨打给用户。 若要接收传入呼叫，UI 库还支持注册推送通知。 要详细了解 Android 和 iOS 平台的集成以及 API 的使用，请参阅如何进行一对一通话和接收推送通知。
通话功能
辅助功能
可访问性是通话库的重点。 可以使用屏幕阅读器来发布有关通话状态的重要公告，并帮助确保视力受损的用户能够在使用应用程序时实现有效参与。
隐藏式字幕
隐藏式字幕支持各种方案，包括与 Teams 进行互操作、Azure 通信服务群组通话、会议室通话和一对一通话。 此功能确保用户可以跟踪各种通话环境中的对话，从而增强辅助功能和用户体验。 但请务必注意，用户需要使用现成的 UI 库手动选择字幕语言，因为系统不会自动检测口语。
注意
隐藏式字幕在其公共预览版初期并不收费。 但免费时间有限，从 6 月开始，使用字幕可能会收费。
如果要查找有关隐藏式字幕的更多详细信息，请随时访问文档，查看说明和使用指南。 此外，如果想要直接跳转到 UI 库中隐藏式字幕的配置，可以按照我们的教程轻松进行设置。
事件
开发人员现在可以订阅 Call Composite 中的事件，使他们能够在整个通话生命周期中将侦听器附加到特定事件。 此增强功能提供了更大的控制和自定义机会，允许开发人员根据事件（例如参与者加入或参与者退出通话）触发自定义操作。 无论是记录交互、动态更新用户界面，还是增强整体功能。
有关详细信息，请参阅如何处理事件。
本地化
本地化是制造可由世界各地说不同语言的人使用的产品的关键。 UI 库支持 12 种语言：英语、西班牙语、法语、德语、意大利语、日语、韩语、荷兰语、葡萄牙语、俄语、土耳其语和中文。 它还支持从右到左书写的语言。 有关详细信息，请参阅如何为应用添加本地化。
多任务和画中画
UI 库支持通话屏幕的画中画模式。 在通话期间，用户可以单击通话屏幕上的“后退”按钮启用多任务，这会使用户返回到上一个屏幕。 如果启用了画中画，通话时将显示系统画中画。 要详细了解 Android 和 iOS 平台的多任务和画中画以及 API 的使用，请参阅如何使用画中画。
屏幕方向
UI 库支持在启动库体验之前单独为每个屏幕设置屏幕方向。 这样，应用程序开发人员就可以为通话体验设置固定方向，使其应用程序方向保持一致。 若要详细了解 Android 和 iOS 平台的支持方向列表以及 API 的使用，请参阅如何使用方向功能。
屏幕大小
你可以调整 Azure 通信服务通话复合，以适应从 5 英寸大小到平板电脑大小的屏幕。 在通话复合中使用拆分模式和平板电脑模式获取动态参与者的名单布局，提供清晰的视图，并专注于对话。
| 拆分模式 | 平板模式 |
|---|---|
|
|
查看数据注入
使用适用于移动本机平台的 UI 库为本地和远程参与者提供选项，用于自定义他们在通话中显示为用户的方式。 呼叫开始时，本地参与者可以在“设置”屏幕上选择本地头像、自定义显示名称、导航标题和副标题。 远程用户可以在加入会议时创建自定义头像。 有关详细信息，请参阅如何自定义会议前视图。
查看共享内容
通过适用于移动本机平台的 UI 库，当其他参与者在 Teams 通话期间共享屏幕时，通话参与者可以查看共享内容。 远程参与者可以使用拉伸和收缩手势放大或缩小通话中的共享内容。
OS 集成
CallKit 支持
UI 库支持 CallKit 集成，以处理与 CallKit 的通话交互。 要详细了解 iOS 平台的集成和 API 的使用，请参阅如何使用 CallKit。
TelecomManager 支持
UI 库现在支持与 TelecomManager 的集成，允许处理呼叫保留和恢复函数。 若要详细了解 Android 平台的集成和 API 的使用，请参阅“如何使用 TelecomManager”。
自定义通话体验
仅音频模式
UI 库中的仅音频模式允许参与者仅使用音频加入通话，而无需共享或接收视频。 此功能用于节省带宽并最大程度保护隐私。 激活后，仅音频模式会自动禁用发送和接收数据流的视频功能，并通过移除与视频相关的控件来调整 UI 以反映此更改。 可以通过 CallComposite 配置启用此模式，详细信息请参阅仅音频快速入门。
禁用结束呼叫提示
开发集成呼叫功能的应用程序时，确保无缝直观的用户体验至关重要。 可以简化 UX 的一个领域是在呼叫终止过程中。 具体而言，开发人员可能会发现禁用用户要结束呼叫时出现的左侧呼叫确认提示会很有帮助。 此功能虽然在阻止意外呼叫终止方面很有用，但有时可能会阻碍用户体验，尤其是在速度和效率至关重要的环境中。 如何禁用呼叫确认
快速节奏的通信环境：在必须快速执行决策和操作的环境（例如，交易大厅、紧急呼叫中心或客户服务中心）中，确认呼叫终止的其他步骤可能会妨碍工作流效率。
按钮栏自定义
借助此功能，开发人员可以将新操作添加到上下文菜单中，或删除按钮栏中的当前按钮，从而灵活地引入自定义操作并根据特定应用程序需求定制用户界面。
- 添加自定义按钮：开发人员可以将新按钮引入上下文按钮栏中以触发自定义操作。
- 删除现有按钮：可以删除不必要的默认按钮以简化界面：相机、麦克风或音频选择。
在此功能的实现过程中，请考虑以下约束条件：
- 图标和标签：仅针对新操作添加图标。 按钮栏图标保留预定义图标，并且标签应当简洁，以适应菜单维度。
- 辅助功能注意事项：开发人员应确保所有自定义按钮都可访问，包括屏幕阅读器的相应标签。
| 删除按钮 | 添加自定义操作 |
|---|---|
|
|
用例
- 自定义通话中操作：业务应用程序可以添加自定义的“报告问题”按钮，允许用户在呼叫期间直接报告技术问题。
- 品牌打造和用户体验：企业应用可以移除与其用例无关的按钮，并添加可增强用户体验的品牌按钮。
为了确保调用体验一致，建议将 Fluent UI 图标集成到项目中；可在 Fluent UI GitHub 存储库中获取。 这样做后，自定义图标将匹配通话复合体的设计，从而创建一个一致且专业的外观。
最佳做法
- 简洁设计：避免过度拥挤的上下文菜单栏。 仅添加对用户体验至关重要的按钮。
- 用户测试：进行用户测试以确保自定义满足了用户需求，而不会使用户感到困惑或不知所措。
- 添加反馈机制：如果为“报告问题”之类的操作添加按钮，请确保有可靠的后端系统来处理收集到的反馈，则可以重复使用 UI 库默认提供的机制。
有关详细信息，请参阅如何自定义按钮栏。
跳过设置屏幕
UI 库提供加入通话的功能，可跳过通话加入体验的设置屏幕。 默认情况下，用户通过设置屏幕加入通话。 在这里，用户在加入通话之前设置通话配置，例如打开或关闭相机、打开或关闭麦克风和选择音频设备。 此屏幕需要用户交互才能加入通话，这对某些用户来说可能没有必要。 因此，我们提供了可跳过设置屏幕并提供调用配置 API 来加入通话的功能。 有关详细信息，请参阅如何使用跳过设置屏幕功能。
主题设置和颜色
可以使用适用于 iOS 和 Android 的 UI 库通话复合来创建呼叫方体验的自定义主题。 你可以灵活地自定义主色。 此功能使你可以定制配色方案，以满足特定的品牌需求。 通过调整主色，可以确保界面与品牌的视觉标识无缝集成，从而增强用户体验，同时保持应用程序的一致性。 有关详细信息，请参阅如何创建主题。
| Android | iOS |
|---|---|
|
|
标题和副标题
UI 库允许你输入自定义字符串，以便更轻松地定制通话界面以满足你的特定需求。 在设置阶段和通话过程中，你都可以自定义通话的标题和副标题。
例如，在企业环境中，你可以设置标题来反映会议的议程和副标题以指示公告，对于客户支持，代理可以使用标题来显示问询的性质，从而提高清晰度并促进沟通。
此外，在通话中进行有时间限制的讨论时，你可以使用副标题显示通话持续时间，确保所有参与者都知道时间限制。
有关详细信息，请参阅以下教程：如何设置标题和副标题。
聊天用例
重要
Azure 通信服务的这一功能目前以预览版提供。
预览版 API 和 SDK 在没有服务级别协议的情况下提供。 建议不要将它们用于生产工作负荷。 某些功能可能不受支持或者已受限。
有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。
| 区域 | 用例 |
|---|---|
| 聊天类型 | 加入 Azure 通信服务聊天线程 |
| 聊天操作 | 发送聊天消息 |
| 接收聊天消息 | |
| 聊天事件 | 显示键入指示符 |
| 显示阅读回执 | |
| 显示添加或移除参与者的时间 | |
| 显示对聊天标题的更改 |
灵活性
ChatComposite 旨在适应应用程序中的不同布局和视图。 例如，可以选择将“聊天”置于导航视图、模式视图或其他视图中。 ChatComposite 会自行调整并确保用户具有无缝体验。
| 在导航视图中 | 在模式视图中 |
|---|---|
|
|
支持的标识
若要初始化复合并对服务进行身份验证，用户必须具有 Azure 通信服务标识。 有关详细信息，请参阅对 Azure 通信服务进行身份验证和快速入门：创建和管理访问令牌。
建议体系结构
使用 Azure 通信服务访问令牌初始化复合。 请务必通过你所管理的受信任服务从 Azure 通信服务获取访问令牌。 有关详细信息，请参阅快速入门：创建和管理访问令牌以及受信任的服务教程。
通话和聊天客户端库必须具有其加入的通话的上下文。 与用户访问令牌一样，使用你自己的受信任服务将上下文传播给客户端。 下表汇总了将上下文添加到客户端库所需的初始化和资源管理功能：
| Contoso 责任 | UI 库责任 |
|---|---|
| 从 Azure 提供访问令牌 | 传递提供的访问令牌来初始化组件 |
| 提供刷新功能 | 使用开发人员提供的功能刷新访问令牌 |
| 检索和传递用于通话或聊天的加入信息 | 传递通话和聊天信息以初始化组件 |
| 检索和传递任何自定义数据模型的用户信息 | 将自定义数据模型传递到要呈现的组件 |
平台支持
| 平台 | 版本 |
|---|---|
| iOS | iOS 14 及更高版本 |
| Android | API 21 及更高版本 |
故障排除指南
对语音或视频呼叫进行故障排除时，系统可能会要求你提供 CallID；此 ID 用于标识通信服务调用。
可通过通话屏幕底部的操作栏检索此 CallID。你会看到一个省略号按钮；一旦用户执行点击操作，就会看到一个“共享诊断信息”选项。用户可以共享支持团队跟踪任何问题所需的诊断信息。
有关对 CallID 的编程访问，请参阅“如何以编程方式获取调试信息”。
可以在此处了解有关故障排除指南的详细信息：“在Azure 通信服务中排除故障”页面。
| 呼叫屏幕 | 诊断信息菜单 | 共享 CallID |
|---|---|---|
|
|
|