共用方式為

PeoplePicker 控制 (預覽版)

  • 發行項

[本文章是發行前版本文件，且隨時可能變更。]

用來建立下載體驗的控制項。

Note

完整文件和原始程式碼可在 GitHub 程式碼元件存放庫中找到。

PeoplePicker 控制項。

重要

  • 這是預覽功能。
  • 預覽功能不供生產時使用，而且可能功能受限。 這些功能是在正式發行前先行推出，讓客戶能夠搶先體驗並提供意見反應。

描述

人員選擇器 (PeoplePicker) 是用來從清單中選取一或多個實體，例如人員或群組。 它能撰寫電子郵件給某些人，或將他們新增至群組，即使您不知道他們的全名或電子郵件地址也無妨。

此程式碼元件為 Fluent UI PeoplePicker 控制項提供了一個包裝函式，以便在畫布和自訂頁面中使用。 如需最佳做法，請參閱元件文件。

索引鍵屬性

屬性 描述
Items 預選的角色 (成員) 會出現在 Peoplepicker 上
Suggestions_Items 要從中挑選的建議成員清單。 這是必要的資料集屬性
PeoplePickerType 要使用的 Peoplepicker 類型。
MaxPeople 可選的使用者數目上限
NoResultFoundMesage 如果根據指定的搜尋文字找不到結果時，要顯示的訊息。
MinimumSearchTermLength 在提供建議前，要輸入的最短搜尋字詞長度。
SearchTermToShortMessage 當搜尋文字短於 MinimumSearchTermLength 時，要顯示的自訂訊息。
Error 將人員選擇器突出顯示為紅色，以表示發生特定錯誤，需要進行驗證。
ShowSecondaryText 根據是否要顯示次要文字 (例如，JobTitle)，指定 「是」或「否」。

Items 性能

屬性 描述
PersonaName 角色的顯示名稱。
PersonaKey 金鑰會識別特定項目。 金鑰必須是唯一的。
PersonaImgUrl 角色圖像 (設定檔圖片) 的 Url 或 Base64 內容。
PersonaRole 次要文字，最好是角色的 JobTitle
PersonaPresence 選用 - 要顯示人員的出席狀態 - 如果未定義，將不會顯示出席狀態。 值應該是下列其中一項：away、blocked、busy、dnd、none、offline 和 online
PersonaOOF 選用 - True 或 False，根據角色是否在辦公室而定。

Suggestions_Items 性能

屬性 描述
SuggestionName 角色的顯示名稱。
SuggestionKey 金鑰會識別特定項目。 金鑰必須是唯一的。
SuggestionImgUrl 角色圖像 (設定檔圖片) 的 Url 或 Base64 內容。
SuggestionRole 次要文字，最好是角色的 JobTitle
SuggestionPresence 選用 - 要顯示人員的出席狀態 - 如果未定義，將不會顯示出席狀態。 值應該是下列其中一項：away、blocked、busy、dnd、none、offline 和 online
SuggestionOOF 選用 - True 或 False，根據角色是否在辦公室而定。

其他屬性

屬性 描述
Theme 接受使用 Fluent UI Theme Designer (windows.net) 產生的 JSON 字串。 將此留空將使用 Power Apps 定義的預設主題。
AccessibilityLabel 螢幕助讀程式 aria-label
InputEvent 要傳送到控制項的事件。 支援將 SetFocus 視為 InputEvent。

範例

PeoplePicker 支援可從中檢索 Input 集合的其他源。 以下是關於如何使用 PeoplePicker 元件的範例。

Office 365 使用者連接器

  1. 將 Office 365 使用者連接器新增為資料來源。

  2. 將下列 Power Fx 公式指派給控制項的 On Search 屬性，以建立名為 UserCollection 的集合。

    ClearCollect(
    UserCollection,
    AddColumns(
        Filter(
            Office365Users.SearchUser(
                {
                    searchTerm: Self.SearchText,
                    top: 500
                }
            ),
            !(Mail in Self.SelectedPeople.PersonaKey)
        ),
        "SuggestionImgUrl",
        Substitute(
            JSON(
                Office365Users.UserPhotoV2(Id),
                JSONFormat.IncludeBinaryData
            ),
            """",
            ""
        ),
        "SuggestionKey",
        Mail,
        "SuggestionName",
        DisplayName,
        "SuggestionRole",
        JobTitle,
        "SuggestionPresence",
        "away"
    )
)

  3. 將 Suggestions_Items 屬性設為 UserCollection。

    Note

    上述公式包括連續要求以取得 UserPhoto，這會增加載入時間。 如果您不需要照片，且想要減少搜尋時間，請在控制項的 Suggestions_Items 屬性，而非 UserCollection 屬性中，使用下列公式，：

    AddColumns(
    Office365Users.SearchUser({ searchTerm: Self.SearchText, top: 500 }),
    "SuggestionKey", Mail, 
    "SuggestionName", DisplayName,
    "SuggestionRole", JobTitle
)

此時，控制項可正常運作，並可從 SelectedPeople 屬性中取得選取的成員。

PeoplePicker1.SelectedPeople

包含 Dataverse 資料表 - Microsoft Entra 使用者或使用者

  1. 若要設定 Suggestions_Items 屬性，請指定下列程式碼片段。

    將使用者或特定使用者 (使用下列程式碼) 從表格新增至 PeoplePicker 的項目集合(位於 Suggestions_Items 屬性下方 )。

    -AAD Users 桌子

    Search('AAD Users', Self.SearchText,"displayname" ,"mail")

    -Users 桌子

    Search('Users', Self.SearchText,"fullname","internalemailaddress")

  2. 根據您的使用 AddColumns() 的需求來對應欄。 下面是欄屬性對應的範例：

    屬性名稱 AADUser 表格欄 使用者表格欄
    建議索引鍵 「電子郵件」 「內部電子郵件地址」
    建議名稱 「顯示名稱」 「全名」
    建議角色 「職稱」 「職稱」

此時，人員選擇器應可正常運作，而且可從 SelectedPeople 屬性中取得選取的成員。

PeoplePicker1.SelectedPeople

限制

此畫布元件只能在畫布應用程式和自訂頁面中使用。