試験的なユーザー選択ウィンドウのウィジェットを SharePoint アドインで使用する

[アーティクル]
04/08/2023

ページが SharePoint でホストされていない場合でも、任意の Web ページでユーザー選択のウィジェットを使用できます。アドインでユーザー選択のウィジェットを使用すると、ユーザーやグループの検索と選択がしやすくなります。

警告

Office Web ウィジェット - 試験段階は、研究とフィードバックの目的のみに使用します。運用シナリオでは使用しません。今後のリリースで、Office Web ウィジェットの動作が大幅に変更される可能性があります。「Office Web ウィジェット - 試験段階のライセンス条項」をご確認ください。

アドインでユーザーの選択ウィンドウの実験用ウィジェットを使用することにより、テナント内のユーザーやグループの検索と選択を簡単に行えます。テキストボックスに入力をすると、ウィジェットは名前か電子メールがテキストと合致するユーザーを取得します。

クエリを解決するユーザー選択のウィジェット

ページ上のユーザー選択ウィンドウの試験的なコントロール

アドインはウィジェットの selectedItems プロパティを読み取ることによって、選択されたユーザーにアクセスできます。 selectedItems プロパティはユーザーまたはグループを表すオブジェクトの配列です。ユーザーオブジェクトで使用可能なプロパティを以下の表に示します。

プロパティ	説明
department	ユーザーまたはグループの部門。
displayName	ユーザーまたはグループの表示名。
email	ユーザーまたはグループのメールアドレス。
isResolved	ウィジェットがテナント内のグループまたはユーザーに対してウィジェットのテキストを正常に解決したかどうかを示します。
jobTitle	ユーザーの役職名。
loginName	ユーザーまたはグループのサインイン名。
mobile	ユーザーまたはグループの携帯電話番号。
principalId	ユーザーまたはグループのプリンシパル ID。
principalType	項目がユーザーかグループかを示します。ユーザーであれば値は 1、グループであれば値は 4 です。
sipAddress	ユーザーまたはグループの SIP アドレス。
text	ユーザーまたはグループのテキストのタイトル。

ユーザー選択ウィンドウのウィジェットには、最近使用した (MRU) エントリのキャッシュがあります。ウィジェットが解決した過去 5 件のエントリがキャッシュに格納されます。

この記事の手順を行う上での前提条件

この記事に示されている例を使用するには、次のものが必要です。

Visual Studio 2013 以降。
NuGet パッケージマネージャー。詳細については「NuGet をインストールする」を参照してください。
SharePoint 開発環境 (オンプレミスシナリオではアプリの分離が必要)。
Office Web ウィジェット - 試験段階の NuGet パッケージ。 NuGet パッケージのインストールの方法の詳細については、「NuGet パッケージマネージャーの UI」を参照してください。また、「NuGet ギャラリーページ」も参照できます。

この例では、SharePoint の外部でホストされるシンプルなページでマークアップを使用して、ユーザー選択のウィジェットを宣言します。複雑にならないよう、この例ではオプションを宣言しませんが、オプションの例は NextSteps セクションで確認することができます。

ユーザー選択ウィジェットを使用するには、次の操作を行う必要があります。

SharePoint アドインと Web プロジェクトを作成します。
アドイン Web でモジュールを作成します。この手順を実行すると、ユーザーがアドインを展開する時にアドイン Web が作成されるようになります。

注:

クロスドメインライブラリを使用するには、アドイン Web が存在している必要があります。ユーザー選択のウィジェットは、クロスドメインライブラリを使用して SharePoint と通信します。
マークアップを使用して、ユーザー選択ウィジェットのインスタンスを宣言しているアドインページを作成します。

SharePoint アドインと Web プロジェクトを作成する方法

管理者として Visual Studio を開きます (これを行うには、[スタート] メニューの [Visual Studio] アイコンを選択し、[管理者として実行] を選択します)。
SharePoint アドインのテンプレートを使用して新しいプロジェクトを作成します。SharePoint アドイン テンプレートは、[テンプレート]>[Visual C#]、[Office/SharePoint]>[アドイン]にあります。
デバッグに使用する SharePoint Web サイトの URL を入力します。
アドインのホスティングオプションとして [プロバイダー向けのホスト型] を選択します。

注:

他のホストオプションを指定してユーザー選択のウィジェットを使用することもできます。また、Office アドインや独自の Web サイトで使用することもできます。
Web アプリケーションプロジェクトの種類として、[ASP.NET Web フォームアプリケーション] を選択します。
認証オプションとして [ Windows Azure アクセス制御サービス] を選択します。

アドイン Web 上でモジュールを作成する方法

ソリューションエクスプローラーで SharePoint アドインプロジェクトを選択します。 [追加]>[新しいアイテム] を選択します。
[Visual C# アイテム]>[Office/SharePoint]>[モジュール] の順に選択します。モジュールの名前を指定します。

注:

SharePoint ホスト型アドインを作成する場合、付加的なモジュールを作成する必要はありません。

ソリューションエクスプローラーで Web プロジェクト内の [ページ] フォルダーを選択します。

以下のコードをコピーし、プロジェクトの ASPX ファイルに貼り付けます。このコードは以下のタスクを実行します。

必要な Office ライブラリおよびリソースに、参照を追加します。
コントロールランタイムを初期化します。
Office コントロールランタイムの renderAll メソッドを実行します。
ユーザー選択ウィジェット用のプレースホルダーを宣言します。

<!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>

注:

前述のコードの例では、ホスト Web とアドイン Web の URL を明示的に指定して Office コントロールランタイムを初期化しています。ただし、アドイン Web とホスト Web の URL がそれぞれ SPAppWebUrl クエリ文字列パラメーターと SPHostUrl クエリ文字列パラメーターで指定されている場合は、空のオブジェクトを渡すことができ、コードによってパラメーターが自動的に取得されます。 SPAppWebUrl パラメーターと SPHostUrl パラメーターは、{StandardTokens} トークン使用時にクエリ文字列に組み込まれます。

次の例は、初期化メソッドに空のオブジェクトを渡す方法を示しています。

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

ソリューションをビルドして実行するには

F5 キーを選択します。

注:

F5 キーを押すと、Visual Studio がソリューションをビルドして、アドインを展開し、アドインのアクセス許可ページを開きます。
[信頼する] ボタンを選択します。
[サイトコンテンツ] ページのアドインアイコンを選択します。

このサンプルをコードギャラリーからダウンロードするには、「ユーザー選択の試験的なウィジェットをアドインで使用する」のコードサンプルを参照してください。

次の手順

この記事では、HTML を使用してアドインでユーザーの選択ウィンドウのウィジェットを使用する方法を示します。以下のシナリオとウィジェットの詳細を調べることもできます。

好みに応じて、HTML ではなく JavaScript を使用してウィジェットを宣言することもできます。その場合は、以下のマークアップをウィジェットのプレースホルダーとして使用できます。

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

ユーザー選択ウィンドウを開始するには、次の JavaScript コードを使用します。

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

作業の実行方法を示すコードサンプルについては、「ユーザーの選択ウィンドウの実験用ウィジェットをアドインで使用する」のコードサンプルの JSSimple.html ページを参照してください。

ウィジェット宣言で data-office-options 属性を使用して、ウィジェットのオプションを指定することができます。以下の HTML は、ユーザーの選択ウィンドウのウィジェットのオプションを指定する方法を示しています。

<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>

次のコードは、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();
        }
    });

onChange イベント、onAdded イベント、onRemoved イベントのイベントハンドラーを指定することもできます。上記のコードでは、onChange イベントのイベントハンドラーは、ウィジェットへの参照となる単一のパラメーター、ctrl を受信します。

オプションの指定方法の例については、「ユーザーの選択ウィンドウの実験用ウィジェットをアドインで使用する」のコードサンプルの MarkupOptions.html ページと JSOptions.html ページを参照してください。

ウィジェット内でユーザーを取得するには、次のタスクを実行する必要があります。

ウィジェットへの参照を取得します。
ウィジェットの selectedItems プロパティにアクセスします。

次の構文を使用して、ウィジェットへの参照を取得できます。

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

ウィジェットのインスタンスを作成するときに参照を保存することもできます。

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

selectedItems プロパティはユーザーまたはグループを表すオブジェクトの配列です。 selectedItems 配列内のユーザーまたはグループは、解決済みでも未解決でも構いません。解決済みかどうかは、isResolved プロパティで確認できます。次の例は、配列内の要素 i にアクセスし、ユーザーまたはグループの名前を使用する方法を示しています。

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

選択されたユーザーまたはグループをウィジェットから取得する方法の例については、「 Office Web Widgets - Experimental デモ」のコードサンプルの demo.html ページを参照してください。

開発者はウィジェットの外観をカスタマイズできます。次の図は、レンダリングされた後のウィジェットの HTML 階層を示しています。ウィジェットは office-peoplepicker というプレフィックスが付いたクラスを多数定義しています。これを Office.Controls.css スタイルシートで見つけて、カスタマイズすることができます。

ユーザー選択のウィジェットの HTML 階層

ユーザー選択コントロールの HTML 階層

ユーザー選択の試験的なウィジェットを使用して、テナント内のユーザーとグループを選択できます。選択後、アドインはユーザーが選択したプリンシパルを使用できます。「Office デベロッパープラットフォーム UserVoice サイト」に、アイディアやコメントをお寄せください。

Share via

試験的なユーザー選択ウィンドウのウィジェットを SharePoint アドインで使用する

この記事の手順を行う上での前提条件

プロバイダー向けのホスト型 SharePoint アドインでユーザー選択ウィジェットを使用する

SharePoint アドインと Web プロジェクトを作成する方法

アドイン Web 上でモジュールを作成する方法

ユーザー選択ウィジェットを使用する新しいページを追加する方法

ソリューションをビルドして実行するには

次の手順

JavaScript を使用してユーザー選択のウィジェットを宣言する

ウィジェットのオプションを指定する

ウィジェットで選択されているユーザーまたはグループを取得します。

ウィジェットのスタイルをカスタマイズする

関連項目

その他のリソース