Partilhar via

Usar o widget experimental Seletor de Pessoas nos suplementos do SharePoint

  • Artigo

Você pode usar o widget Pessoas Picker em qualquer página da Web, mesmo que a página não esteja hospedada no SharePoint. Use o widget Pessoas Picker em seus suplementos para ajudar os usuários a encontrar e selecionar pessoas e grupos.

Aviso

Os Widgets Web do Office – Experimental são fornecidos apenas para fins de pesquisa e comentários. Não use em cenários de produção. O comportamento do Office Web Widgets pode mudar significativamente em versões futuras. Leia e examine os Widgets web do Office – Termos de licença experimentais.

Você pode usar o widget experimental Pessoas Picker em suplementos para ajudar seus usuários a encontrar e selecionar pessoas e grupos em um locatário. Os usuários podem começar a digitar na caixa de texto e o widget recupera as pessoas cujo nome ou email corresponde ao texto.


Pessoas widget picker resolvendo uma consulta

Controle experimental do Seletor de Pessoas em uma página

Seu suplemento pode acessar as pessoas selecionadas lendo a propriedade selectedItems do widget. A propriedade selectedItems é uma matriz de objetos que representam pessoas ou grupos. A tabela a seguir mostra as propriedades disponíveis do objeto de usuário.


Propriedade Descrição
department O departamento do usuário ou grupo.
displayName O nome de exibição do usuário ou grupo.
email O endereço de email do usuário ou grupo.
isResolved Indica se o widget resolveu com êxito o texto no widget em relação a um usuário ou grupo no locatário.
jobTitle O título do trabalho do usuário.
Loginname O nome de entrada do usuário ou grupo.
Móvel O número de telefone celular do usuário ou grupo.
principalId A ID principal do usuário ou grupo.
principalType Indica se o item é um usuário ou um grupo. Ele tem um valor de 1 se for um usuário, 4 se for um grupo.
sipAddress O endereço sip do usuário ou grupo.
text O título de texto do usuário ou nome do grupo.

O widget Pessoas Picker tem um cache das entradas MRU (usadas mais recentemente). O cache armazena as cinco entradas mais recentes que o widget resolveu.

Pré-requisitos para usar os exemplos neste artigo

Para usar os exemplos neste artigo, você precisa do seguinte:

Use o widget Pessoas Picker em um suplemento do SharePoint hospedado pelo provedor

Neste exemplo, uma página simples é hospedada fora do SharePoint que declara um widget do Picker Pessoas usando marcação. Para manter as coisas simples, este exemplo não declara nenhuma opção, mas você pode ver um exemplo com opções na seção NextSteps .

Para usar o widget Pessoas Picker, você deve fazer o seguinte:

  • Crie um Suplemento do SharePoint e projetos da Web.

  • Crie um módulo na Web de suplemento. Esta etapa garante que um suplemento da Web seja criado quando os usuários implantam o suplemento.

    Observação

    A biblioteca entre domínios requer a existência de um suplemento da Web. O widget Pessoas Picker se comunica com o SharePoint usando a biblioteca entre domínios.

  • Crie uma página de suplemento que declare uma instância de widget do Picker Pessoas usando marcação.

Para criar um Suplemento do SharePoint e projetos da Web

  1. Abra o Visual Studio como administrador. (Para fazer isso, selecione o ícone do Visual Studio no menu Iniciar e selecione Executar como administrador.)

  2. Crie um novo projeto usando o modelo de suplemento do SharePoint. O modelo de suplemento do SharePoint está localizado em ModelosVisual C# ,Suplementos>do Office/SharePoint>.

  3. Forneça a URL do site do SharePoint que você deseja usar para depuração.

  4. Selecione Hospedado pelo provedor como a opção de hospedagem para o suplemento.

    Observação

    Você também pode usar o widget Pessoas Picker com outras opções de hospedagem ou até mesmo com suplementos do Office ou seu próprio site.

  5. Selecione ASP.NET Web Forms Aplicativo como o tipo de projeto de aplicativo Web.

  6. Selecione Serviço de Controle de Acesso do Windows Azure como a opção de autenticação.

Para criar um módulo na Web de suplemento

  1. Selecione o projeto de suplemento do SharePoint no Gerenciador de Soluções. Selecione Adicionar>Novo Item.

  2. Selecione Visual C# Items>Office/SharePoint>Module. Forneça um nome para o módulo.

    Observação

    Se você estiver criando um suplemento hospedado no SharePoint, não precisará criar um módulo extra.

Para adicionar uma nova página que usa o widget Pessoas Picker

  1. Selecione a pasta Páginas no projeto Web no Gerenciador de Soluções.

  2. Copie o código a seguir e cole-o em um arquivo ASPX no projeto. O código executa as seguintes tarefas:

    • Adiciona referências às bibliotecas e recursos necessários do Office.

    • Inicia o tempo de execução dos controles.

    • Executa o método renderAll do runtime do Office Controls.

    • Declara um espaço reservado para o widget Pessoas Picker.

    <!DOCTYPE html>
<html>
<head>
<!-- IE9 or superior -->
    <meta http-equiv="X-UA-Compatible" content="IE=9" >
    <title>People Picker HTML Markup</title>

    <!-- Widgets Specific CSS File -->
    <link 
        rel="stylesheet" 
        type="text/css" 
        href="../Scripts/Office.Controls.css" 
    />

<!-- Ajax, jQuery, and utils --> 
    <script 
        src=" https://ajax.aspnetcdn.com/ajax/4.0/1/MicrosoftAjax.js.js">
    </script>
    <script 
        src=" https://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.9.1.min.js">
    </script>
    <script type="text/javascript">
        // Function to retrieve a query string value.
        // For production purposes you may want to use
        //  a library to handle the query string.
        function getQueryStringParameter(paramToRetrieve) {
            var params =
                document.URL.split("?")[1].split("&amp;");
            var strParams = "";
            for (var i = 0; i < params.length; i = i + 1) {
                var singleParam = params[i].split("=");
                if (singleParam[0] == paramToRetrieve)
                    return singleParam[1];
            }
        }
    </script>

<!-- Cross-Domain Library and Office controls runtime -->
    <script type="text/javascript">
        //Register namespace and variables used through the sample
        Type.registerNamespace("Office.Samples.PeoplePickerBasic");
        //Retrieve context tokens from the querystring
        Office.Samples.PeoplePickerBasic.appWebUrl =
            decodeURIComponent(getQueryStringParameter("SPAppWebUrl"));
        Office.Samples.PeoplePickerBasic.hostWebUrl =
            decodeURIComponent(getQueryStringParameter("SPHostUrl"));

        //Pattern to dynamically load JSOM and and the cross-domain library
        var scriptbase =
            Office.Samples.PeoplePickerBasic.hostWebUrl + "/_layouts/15/";

        //Get the cross-domain library
        $.getScript(scriptbase + "SP.RequestExecutor.js",
            //Get the Office controls runtime and 
            //  continue to the createControl function
            function () {
                $.getScript("../Scripts/Office.Controls.js", createControl)
            }
        );
    </script>

<!--People Picker -->
    <script 
        src="../Scripts/Office.Controls.PeoplePicker.js" 
        type="text/javascript">
    </script>
</head>
<body>
    Basic People Picker sample (HTML markup declaration):
    <div 
            id="PeoplePickerDiv" 
            data-office-control="Office.Controls.PeoplePicker">
    </div>

    <script type="text/javascript">
        function createControl() {
            //Initialize Controls Runtime
            Office.Controls.Runtime.initialize({
                sharePointHostUrl: Office.Samples.PeoplePickerBasic.hostWebUrl,
                appWebUrl: Office.Samples.PeoplePickerBasic.appWebUrl
            });

            //Render the widget, this must be executed after the
            //placeholder DOM is loaded
            Office.Controls.Runtime.renderAll();
        }
    </script>
</body>
</html>

Observação

O exemplo de código anterior especifica explicitamente as URLs Web do host e do suplemento da Web para inicializar o runtime de controles do Office. No entanto, se as URLs Web do suplemento e do host forem especificadas nos parâmetros de cadeia de caracteres de consulta SPAppWebUrl e SPHostUrl , respectivamente, você poderá passar um objeto vazio e o código tentar obter os parâmetros automaticamente. Os parâmetros SPAppWebUrl e SPHostUrl são incluídos na cadeia de caracteres de consulta quando você usa o token {StandardTokens} .

O exemplo a seguir mostra como passar um objeto vazio para o método de inicialização:

// Initialize with an empty object and the code 
// will attempt to get the tokens from the
// query string directly.
Office.Controls.Runtime.initialize({});

Para compilar e executar a solução

  1. Pressione a tecla F5.

    Observação

    Ao pressionar F5, o Visual Studio compila a solução, implanta o suplemento e abre a página de permissões do suplemento.

  2. Selecione o botão Confiar.

  3. Selecione o ícone de suplemento na página Conteúdo do Site.

Para baixar esse exemplo da galeria de códigos, consulte o widget experimental Use o Pessoas Picker em um exemplo de código de suplemento.

Próximas etapas

Este artigo mostra como usar o widget Pessoas Picker em seu suplemento usando HTML. Você também pode explorar os seguintes cenários e detalhes sobre o widget.

Usar JavaScript para declarar o widget do Picker Pessoas

Dependendo da sua preferência, talvez você queira usar JavaScript em vez de HTML para declarar o widget. Se esse for o caso, você poderá usar a marcação a seguir como espaço reservado para o widget.

<div id="PeoplePickerDiv"></div>

Use o código JavaScript a seguir para instanciar o seletor de Pessoas.

new Office.Controls.PeoplePicker(
    document.getElementById("PeoplePickerDiv"), {});

Para obter um exemplo de código que mostra como executar as tarefas, consulte a página JSSimple.html no widget experimental Use o Pessoas Picker em um exemplo de código de suplemento.

Especificar opções para o widget

Você pode especificar opções para o widget usando o atributo data-office-options na declaração de widget. O HTML a seguir mostra como especificar opções para o widget PeoplePicker.

<div id="PeoplePickerDiv"
        data-office-control="Office.Controls.PeoplePicker"
        data-office-options='{
        "allowMultipleSelections" : true,
        "onChange" : handleChange,
        "placeholder" : "Check the count message, it changes when you add names..."
    }'>
</div>

O código a seguir mostra como especificar opções ao declarar o widget PeoplePicker usando JavaScript.

new Office.Controls.PeoplePicker(
    document.getElementById("PeoplePickerDiv"), {
        allowMultipleSelections: true,
        placeholder: "Check the count message, it changes when you add names...",
        onChange: function (ctrl) {
            document.getElementById("count").textContent = 
ctrl.selectedItems.length.toString();
        }
    });

Você também pode especificar manipuladores de eventos para os eventos onChange, onAdded e onRemoved . Observe no código anterior que o manipulador de eventos do evento onChange recebe um único parâmetro ctrl, que é uma referência ao widget.

Para obter um exemplo de como especificar opções, consulte as páginas MarkupOptions.html e JSOptions.html no widget experimental Use o Pessoas Picker em um exemplo de código de suplemento.

Recuperar as pessoas ou grupos selecionados no widget

Para recuperar as pessoas no widget, você deve executar as seguintes tarefas:

  • Obtenha uma referência ao widget.

  • Acesse a propriedade selectedItems do widget.

Você pode obter uma referência ao widget usando a sintaxe a seguir.

var pplPicker = document.getElementById("PeoplePickerDiv")._officeControl;

Você também pode salvar uma referência ao instanciar o widget.

var pplPicker = new Office.Controls.PeoplePicker(
                        document.getElementById("PeoplePickerDiv"), {});

A propriedade selectedItems é uma matriz de objetos que representam pessoas ou grupos. Pessoas ou grupos na matriz selectedItems podem ser resolvidos ou não resolvidos, que você pode verificar na propriedade isResolved. O exemplo a seguir mostra como acessar o elemento i na matriz e usar o nome da pessoa ou grupo.

var principal = pplPicker.selectedItems[i];
$("#msg").text(principal.text + " is selected in the control.");

Para obter um exemplo de como recuperar as pessoas ou grupos selecionados do widget, consulte a página demo.html do exemplo de código de demonstração experimental do Office Web Widgets .

Personalizar o estilo do widget

Como desenvolvedor, talvez você queira personalizar a aparência do widget. A imagem a seguir mostra a hierarquia HTML no widget depois que ele foi renderizado. O widget define muitas classes prefixadas pelo office-peoplepicker, que você pode encontrar e personalizar na folha de estilos Office.Controls.css .

Hierarquia HTML no widget do Picker Pessoas

Hierarquia HTML no controle Seletor de Pessoas

Você pode usar o widget experimental Pessoas Picker para selecionar pessoas e grupos em seu locatário e seu suplemento pode usar as entidades selecionadas pelos usuários. Forneça ideias e comentários no site UserVoice da Plataforma do Desenvolvedor do Office.

Confira também