Microsoft Graph 中的 Microsoft Teams 频道选取器ToolkitMicrosoft Teams Channel Picker component in the Microsoft Graph Toolkit

可以使用组件为与用户关联的 Microsoft Teams 频道 mgt-teams-channel-picker 启用搜索。A you can use the mgt-teams-channel-picker component to enable searches for Microsoft Teams channels associated with a user. 组件可以搜索用户已加入的所有团队,以及这些团队中的每个频道。The component can search all teams the user has joined, and each channel in those teams.

示例Example

以下示例显示 mgt-teams-channel-picker 组件。The following example shows the mgt-teams-channel-picker component. 开始搜索频道或团队以查看结果呈现。Start searching for a channel or team to see the results render.

在"打开"mgt.devOpen this example in mgt.dev

获取所选频道Getting the selected channel

使用 selectedItem 属性检索当前选定的频道和父团队。Use the selectedItem property to retrieve the currently selected channel and parent team. 如果未选择任何通道,则此值将为 null。This value will be null if no channel has been selected. selectedItem 包含两个 channel 属性: (MicrosoftGraph.Channel) 和 team (MicrosoftGraph.Team) 。selectedItem contains two properties: channel (MicrosoftGraph.Channel) and team (MicrosoftGraph.Team).

const channelPicker = document.querySelector('mgt-teams-channel-picker');
console.log(channelPicker.selectedItem.channel);
console.log(channelPicker.selectedItem.team);

选择频道Selecting a channel

使用 selectChannelById(channelId: string) 方法以编程方式选择通道。Use the selectChannelById(channelId: string) method to programmatically select a channel.

注意:Teams 频道选取器仅支持单一频道选择。Note: the Teams channel picker only supports single channel selection.

const channelPicker = document.querySelector('mgt-teams-channel-picker');
const channelId = 'some-channel-id';
channelPicker.selectChannelById(channelId);

注意: 提供的频道 (和后续 ID) 必须属于经过身份验证的用户已加入的团队。Note: The provided channel (and subsequent ID) must belong to a team that the authenticated user has joined.

CSS 自定义属性CSS custom properties

组件 mgt-teams-channel-picker 定义以下 CSS 自定义属性。The mgt-teams-channel-picker component defines the following CSS custom properties.

mgt-teams-channel-picker {
    --input-border: 2px rgba(255, 255, 255, 0.5) solid; /* sets all input area border */

      /* OR individual input border sides */
    --input-border-bottom: 2px rgba(255, 255, 255, 0.5) solid;
    --input-border-right: 2px rgba(255, 255, 255, 0.5) solid;
    --input-border-left: 2px rgba(255, 255, 255, 0.5) solid;
    --input-border-top: 2px rgba(255, 255, 255, 0.5) solid;

    --input-background-color: #1f1f1f; /* input area background color */
    --input-border-color--hover: #008394; /* input area border hover color */
    --input-border-color--focus: #0f78d4; /* input area border focus color */

    --dropdown-background-color: #1f1f1f; /* channel background color */
    --dropdown-item-hover-background: #333d47; /* channel or team hover background */
    --dropdown-item-selected-background: #0F78D4; /* selected channel background color */

    --color: white; /* input area border focus color */
    --arrow-fill: #ffffff;
    --placeholder-color: #f1f1f1; /* placeholder text color */
    --placeholder-color--focus: rgba(255, 255, 255, 0.8); /* place holder text focus color */
}

事件Events

事件Event 详情Detail 说明Description
selectionChangedselectionChanged 详细信息包含 {channel : MicrosoftGraph.Channel , team: MicrosoftGraph.Team 当前选定的项}The detail contains the currently selected item of {channel : MicrosoftGraph.Channel, team: MicrosoftGraph.Team} 当用户在选择频道时更改时触发。Fired when user makes a change in selection of a channel.

模板Templates

mgt-teams-channel-picker 支持 多个 模板,您可以使用这些模板替换组件的某些部分。mgt-teams-channel-picker supports several templates that you can use to replace certain parts of the component. 若要指定模板,请包含组件 <template> 中的元素,将值 data-type 设置为以下值之一。To specify a template, include a <template> element inside a component and set the data-type value to one of the following.

数据类型Data type 数据上下文Data context 说明Description
loadingloading null:无数据null: no data 向 Microsoft Graph 提出请求时用于呈现选取器状态的模板。The template used to render the state of the picker while the request to Microsoft Graph is being made.
errorerror null:无数据null: no data 当用户搜索未返回任何用户时所使用的模板。The template used if user search returns no users.

以下示例演示如何使用 error 模板。The following example shows how to use the error template.

<mgt-teams-channel-picker>
  <template data-type="error">
    <p>Sorry, no Teams or Channels were found</p>
  </template>
</mgt-teams-channel-picker>

Microsoft Graph 权限Microsoft Graph permissions

此组件使用下列 Microsoft Graph API 和权限。This component uses the following Microsoft Graph APIs and permissions.

APIAPI 权限Permission
/me/joinedTeams/me/joinedTeams User.Read.AllUser.Read.All
/teams/${id}/channels/teams/${id}/channels Group.Read.AllGroup.Read.All

身份验证Authentication

该控件使用身份验证文档中所述的全局 身份验证提供程序The control uses the global authentication provider described in the authentication documentation.

缓存Cache

mgt-teams-channel-picker组件不缓存任何数据。The mgt-teams-channel-picker component doesn't cache any data.

扩展以了解更多控件Extend for more control

对于更复杂的方案或真正自定义的 UX,此组件公开了多个在组件扩展 protected render* 中替代的方法:For more complex scenarios or a truly custom UX, this component exposes several protected render* methods for override in component extensions:

方法Method 说明Description
renderSelectedrenderSelected 在输入框中呈现选定的团队和频道。Renders the selected team and channel in the input box.
renderInputrenderInput 呈现输入框。Renders the input box.
renderDropdownrenderDropdown 呈现下拉列表。Renders the dropdown.
renderDropdownListrenderDropdownList 以递归方法呈现下拉列表中的项。Renders the items in the dropdown recursively.
renderItemrenderItem 在下拉列表中呈现团队或频道。Renders a team or a channel in the dropdown list.
renderHighlightedTextrenderHighlightedText 呈现通道文本,突出显示输入查询。Renders the channel text, highlighting the input query.
renderLoadingrenderLoading 呈现加载下拉列表状态。Renders the loading dropdown state.
renderErrorrenderError 呈现下拉列表错误状态。Renders the dropdown error state.