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