SharePoint ホスト型の SharePoint アドインでクライアント側のユーザー選択コントロールを使用する

SharePoint のクライアント側のユーザー選択コントロールとは

クライアント側のユーザー選択ウィンドウ コントロールを使用すると、ユーザーは、組織内の人、グループ、クレームの有効なユーザー アカウントをすばやく検索し、選択できます。 この選択ウィンドウは、クロスブラウザー サポートを提供する HTML および JavaScript コントロールです。

アドインに選択ウィンドウを追加するのは簡単です。

1. マークアップに、コントロール、コントロール参照、およびその依存関係の参照を含めるコンテナー要素を追加します。

2. 次にスクリプトで、SPClientPeoplePicker_InitStandaloneControlWrapper グローバル関数を呼び出し、選択ウィンドウの表示および初期化を行います。

選択ウィンドウは SPClientPeoplePicker オブジェクトで表されます。このオブジェクトを使用することで、他のクライアント側コントロールは、選択ウィンドウから情報を取得したり、他の操作を実行したりできます。 SPClientPeoplePicker プロパティを使用して、複数ユーザーの許可、キャッシュ オプションの指定など、コントロールに特有の設定で選択ウィンドウを構成できます。

選択ウィンドウは、Active Directory ドメイン サービスのパラメーター、対象のフォレストなど、Web アプリケーション構成設定も使用します。 Web アプリケーション構成設定は、(SPWebApplication.PeoplePickerSettings プロパティから) 自動的に取得されます。

選択ウィンドウは、次のコンポーネントで構成されます。

• ユーザー、グループ、およびクレームの名前を入力する入力テキスト ボックス。
• 解決されたユーザー、グループ、および要求の名前を表示するスパン コントロール。
• 一致するクエリ結果でドロップダウン ボックスを自動入力する非表示の div 要素。
• オートフィル コントロール。

SharePoint アドインでクライアント側のユーザー選択ウィンドウ コントロールを使用するための開発環境をセットアップする場合の前提条件

この記事では、Office 365 開発者向けサイトで Napa を使用して SharePoint アドインを作成するものとしています。 この開発環境を使用している場合は、既に前提条件を満たしています。

開発者向けサイトで Napa を使用しない場合は、以下が必要です。

• 少なくとも 1 名の対象ユーザーを持つ SharePoint
• Visual Studio 2012 または Visual Studio 2013
• Office Developer Tools for Visual Studio 2013

以下のセクションでは、アドインに選択ウィンドウを追加し、別のクライアント側コントロールからユーザー情報を取得する手順の概要を説明します。 対応するコードについては、「コード例: クライアント側ユーザー選択ウィンドウを使用する」を参照してください。

SharePoint ホスト型の SharePoint アドインでクライアント側のユーザー選択コントロールを使用できますが、プロバイダー向けのホスト型アドインではできません。

SharePoint ホスト型アドインでクライアント側のユーザー選択コントロールを使用する

ページ マークアップで

1. クライアント側のユーザー選択コントロールのスクリプト依存関係への参照を追加します。

2. ページ UI の HTML タグを追加します。 この例のアドインでは、2 つの div 要素を定義します。1 つはピッカーでレンダリングし、もう 1 つは UI 用です。1 つは、ピッカーにクエリを実行するスクリプトを呼び出すボタンと、ユーザー情報を表示する要素です。

スクリプト内で

1. AllowMultipleValues、 MaximumEntitySuggestions など、選択ウィンドウに特有のプロパティを保存するスキーマとして使用する JSON 辞書を作成します。

2. SPClientPeoplePicker_InitStandaloneControlWrapper グローバル関数を呼び出します。

3. ページから選択オブジェクトを取得します。

4. 選択ウィンドウへのクエリを実行します。 この例のアドインでは、GetAllUserInfo メソッドを呼び出して、解決済みユーザーのユーザー情報をすべて取得し、GetAllUserKeys メソッドを呼び出して、解決済みユーザーのキーを取得します。

5. JavaScript オブジェクト モデルを使用してユーザー ID を取得します。 選択ウィンドウによって返される情報にはユーザー ID が含まれていないため、アドインは SP.Web.ensureUser メソッドを呼び出し、返された SP.User オブジェクトから ID を取得します。

選択ウィンドウの表示、初期化、その他の機能は、SharePoint 認証プロバイダーに対するユーザー入力の検索、解決を含め、サーバーで処理されます。

コード例: SharePoint ホスト型アドインで、クライアント側のユーザー選択ウィンドウを使用する

次の HTML と JavaScript コードの例は、クライアント側のユーザー選択コントロールを SharePoint ホスト型アドインに追加します。

最初の例では、Default.aspx ページの PlaceHolderMain asp:Content タグのページ マークアップを示しています。 このコードは、選択ウィンドウのスクリプト依存関係を参照し、選択ウィンドウが表示される DOM 要素に一意の ID を与え、アドインの UI を定義します。

<asp:Content ContentPlaceHolderId="PlaceHolderMain" runat="server">
    <SharePoint:ScriptLink name="clienttemplates.js" runat="server" LoadAfterUI="true" Localizable="false" />
    <SharePoint:ScriptLink name="clientforms.js" runat="server" LoadAfterUI="true" Localizable="false" />
    <SharePoint:ScriptLink name="clientpeoplepicker.js" runat="server" LoadAfterUI="true" Localizable="false" />
    <SharePoint:ScriptLink name="autofill.js" runat="server" LoadAfterUI="true" Localizable="false" />
    <SharePoint:ScriptLink name="sp.js" runat="server" LoadAfterUI="true" Localizable="false" />
    <SharePoint:ScriptLink name="sp.runtime.js" runat="server" LoadAfterUI="true" Localizable="false" />
    <SharePoint:ScriptLink name="sp.core.js" runat="server" LoadAfterUI="true" Localizable="false" />
    <div id="peoplePickerDiv"></div>
    <div>
        <br/>
        <input type="button" value="Get User Info" onclick="getUserInfo()"></input>
        <br/>
        <h1>User info:</h1>
        <p id="resolvedUsers"></p>
        <h1>User keys:</h1>
        <p id="userKeys"></p> 
        <h1>User ID:</h1>
        <p id="userId"></p>
    </div>
</asp:Content>

次の例は、App.js ファイルのスクリプトを示しています。 このスクリプトでは、選択ウィンドウの初期化および表示を行った後、ユーザー情報のクエリを実行し、JavaScript オブジェクト モデルを使用してユーザー ID を取得します。

// Run your custom code when the DOM is ready.
$(document).ready(function () {

    // Specify the unique ID of the DOM element where the
    // picker will render.
    initializePeoplePicker('peoplePickerDiv');
});

// Render and initialize the client-side People Picker.
function initializePeoplePicker(peoplePickerElementId) {

    // Create a schema to store picker properties, and set the properties.
    var schema = {};
    schema['PrincipalAccountType'] = 'User,DL,SecGroup,SPGroup';
    schema['SearchPrincipalSource'] = 15;
    schema['ResolvePrincipalSource'] = 15;
    schema['AllowMultipleValues'] = true;
    schema['MaximumEntitySuggestions'] = 50;
    schema['Width'] = '280px';

    // Render and initialize the picker. 
    // Pass the ID of the DOM element that contains the picker, an array of initial
    // PickerEntity objects to set the picker value, and a schema that defines
    // picker properties.
    this.SPClientPeoplePicker_InitStandaloneControlWrapper(peoplePickerElementId, null, schema);
}

// Query the picker for user information.
function getUserInfo() {

    // Get the people picker object from the page.
    var peoplePicker = this.SPClientPeoplePicker.SPClientPeoplePickerDict.peoplePickerDiv_TopSpan;

    // Get information about all users.
    var users = peoplePicker.GetAllUserInfo();
    var userInfo = '';
    for (var i = 0; i < users.length; i++) {
        var user = users[i];
        for (var userProperty in user) { 
            userInfo += userProperty + ':  ' + user[userProperty] + '<br>';
        }
    }
    $('#resolvedUsers').html(userInfo);

    // Get user keys.
    var keys = peoplePicker.GetAllUserKeys();
    $('#userKeys').html(keys);

    // Get the first user's ID by using the login name.
    getUserId(users[0].Key);
}

// Get the user ID.
function getUserId(loginName) {
    var context = new SP.ClientContext.get_current();
    this.user = context.get_web().ensureUser(loginName);
    context.load(this.user);
    context.executeQueryAsync(
         Function.createDelegate(null, ensureUserSuccess), 
         Function.createDelegate(null, onFail)
    );
}

function ensureUserSuccess() {
    $('#userId').html(this.user.get_id());
}

function onFail(sender, args) {
    alert('Query failed. Error: ' + args.get_message());
}

関連項目

• SharePoint で UX コンポーネントを作成する
• ユーザー選択ウィンドウとクレーム プロバイダーの概要 (SharePoint)
• SharePoint でユーザー選択ウィンドウを構成する