SharePoint のクライアント側の最初の Web パーツを作成する (Hello World パート 1)

クライアント側の Web パーツは、SharePoint ページのコンテキスト内で実行されるクライアント側コンポーネントです。クライアント側の Web パーツは、SharePoint Framework をサポートする SharePoint 環境に展開することができます。また、最新の JavaScript Web フレームワーク、ツール、およびライブラリを使用して、それらを構築することもできます。

クライアント側の Web パーツは次をサポートします。

  • HTML と JavaScript を使用したビルド
  • SharePoint Online 環境とオンプレミス環境の両方。

注意

この資料の手順を実行する前に、必ず開発環境を設定します

SharePoint PnP YouTube チャンネルのビデオを見てこれらの手順に従うこともできます。

新しい Web パーツ プロジェクトの作成

  1. 自分の好みの場所に新しいプロジェクト ディレクトリを作成します。

    md helloworld-webpart
    
  2. プロジェクト ディレクトリへ移動します。

    cd helloworld-webpart
    
  3. Yeoman の SharePoint ジェネレーターを実行して、新しい HelloWorld の Web パーツを作成します。

    yo @microsoft/sharepoint
    
  4. ダイアログ ボックスが表示されたら、次の手順に従います。

    • ソリューション名は何ですか?: helloworld-webpart
    • どのベースライン パッケージをコンポーネントのターゲットにしたいですか?: SharePoint Online のみ (最新)
    • ファイルの配置場所: 現在のフォルダーを使用する
    • テナント管理者が、サイトで機能を展開したり、アプリを追加したりせず、すぐにすべてのサイトでソリューションを展開できるようにしたいですか?: N
    • ソリューションのコンポーネントには、テナント内の他のコンポーネントと共有されていない一意の Web API にアクセスするためのアクセス許可が必要ですか?: N
    • どの種類のクライアント側コンポーネントを作成しますか?: WebPart
  5. 次の一連のダイアログ ボックスでは、Web パーツの詳細情報について入力が求められます。

    • Web パーツ名は何ですか?: HelloWorld
    • Web パーツで何を行いますか?: HelloWorld の説明
    • どのフレームワークを使用しますか?: JavaScript フレームワークなし

この時点では、Yeoman はプロジェクトの基礎になるフォルダやファイルを作成し、npm install を実行して必要な依存関係をインストールします。 これは、通常インターネット接続に応じて 1 ~ 3 分かかります。

プロジェクトの基礎と依存関係のインストールプロセスが完了すると、Yeoman には正常に完了したことを示す次のようなメッセージに類似した内容が表示されます。

SharePoint のクライアント側ソリューションが正常にスキャフォールディングされました

重要

KPM は、npm install コマンドを実行している間、依存関係のインストール中に警告とエラーメッセージを表示することがあります。 これらのログの警告やエラー メッセージは無視してかまいません。

プロセスの最後には、KPM にnpm audit の実行についてメッセージが表示されることがあります。 SharePoint Framework によってテストされていない可能性のあるパッケージや入れ子にされた依存関係をアップグレードする場合は、このコマンドを実行しないでください。

エラーのトラブルシューティング方法の詳細については、既知の問題を参照してください。

お好みのコード エディターを使用する

SharePoint のクライアント側ソリューションは HTML や TypeScript に基づいているため、以下のような Web パーツを構築するのにクライアント側の開発をサポートしている任意のコード エディターを使用することができます。

SharePoint Framework のドキュメントでは、手順と例にある Visual Studio Code を使用します。Visual Studio Code (VS Code) は、デスクトップ上で実行される Microsoft からの軽量ながら強力なソース コード エディターです。VS Code は、Windows、Mac および Linux で使用できます。JavaScript、TypeScript と Node.js をサポートしており、他の言語 (C++、C#、Python、PHP など) とランタイムの拡張機能の豊富なエコシステムを持ちます。

Web パーツのプレビュー

クライアント側の Web パーツは、ローカルなワークステーション上でプレビューしたりテストしたりすることが可能です。 クライアント側のツール チェーンでは、既定で HTTPS エンドポイントが使用されます。 開発環境の設定 プロセスの一部には、ローカル環境のツールチェーンに含まれた開発 SSL 証明書を信頼することが含まれます。 これは、ブラウザーが証明書を信頼するために必要です。

重要

開発者用証明書を信頼する必要があります。 これは 1 回限りのプロセスであり、新しいワークステーション上で最初の SharePoint Framework プロジェクトを実行する場合にのみ必要です。 SharePoint Framework プロジェクトごとにこの操作を行う必要はありません。

開発者用証明書を信頼していない場合は、このページに記載されている、「開発環境の設定」、および「開発者用自己署名証明書の信頼」の手順に従います。

ここまでで開発者証明書をインストールできたので、コンソールに次のコマンドを入力して、Web パーツを構築しプレビューします。

gulp serve

このコマンドでは一連の gulp タスクが実行され、localhost:4321 および localhost:5432 エンドポイントをホストするローカル Web サーバーを作成し開始します。 これで、既定のブラウザーを開いてワークベンチを読み込み、ローカルの開発環境から Web パーツをプレビュー表示します。

注意

ブラウザー内の証明書に問題がある場合は、「開発環境の設定」、および「開発者用自己署名証明書の信頼」の開発者向け証明書のインストールに関する詳細を参照してください。

それでも問題が発生する場合は、「SharePoint Framework の既知の問題とよくあるご質問」を参照してください。

Gulp serve Web パーツ プロジェクト

SharePoint のクライアント側開発ツールは、gulp をタスク ランナーとして使用し、次のようなビルド プロセスのタスクを扱います。

  • TypeScript ファイルを JavaScript にコンパイルします。
  • SASS ファイルを CSS にコンパイルします。
  • JavaScript と CSS ファイルをバンドルし、縮小します。

VS Code には、gulp やその他のタスク ランナー用のサポートが組み込まれています。 Windows で CTRL+SHIFT+B を押すか、macOS で CMD+SHIFT+B を押して、Web パーツをデバッグしてプレビューできます。

SharePoint ワークベンチは、開発者のデザイン領域で、SharePoint で展開することなく Web パーツをすばやくプレビューし、テストすることができます。SharePoint ワークベンチには、クライアント側のページとクライアント側のキャンバスが含まれており、そこで開発中の Web パーツを追加、削除およびテストすることができます。

ローカルで実行中の SharePoint ワークベンチ

SharePoint ワークベンチを使用して、Web パーツのプレビューおよびテストを行う

  1. HelloWorld Web パーツを追加するには、[追加] アイコンを選択します (このアイコンは、上の図で示すようにセクション上にマウスを置くと表示されます)。 これにより、追加できる Web パーツのリストを表示できるツールボックスが開きます。 リストには、HelloWorld の Web パーツと、開発環境でローカルに使用できるその他の Web パーツが含まれます。

    localhost 内の SharePoint ワークベンチのツールボックス

  2. [HelloWorld] を選択して、ページに Web パーツを追加します。

    SharePoint ワークベンチ内の HelloWorld Web パーツ

    おめでとうございます。クライアント側のページに、最初のクライアント側の Web パーツを追加しました。

  3. Web パーツの一番左の鉛筆アイコンを選択し、Web パーツのプロパティ ウィンドウを表示します。

    HelloWorld Web パーツのプロパティ ウィンドウ

    プロパティ ウィンドウでは、Web パーツをカスタマイズするプロパティを定義することができます。プロパティ ウィンドウはクライアント側の主導で、SharePoint の間で一貫したデザインが用意されています。

  4. [説明] テキスト ボックス内のテキストを 「クライアント側の Web パーツはすばらしい!」 に変更します。

    すると、Web パーツ内のテキストも入力したとおりに変わるのがわかります。

プロパティ ウィンドウで使用できる機能の 1 つは更新動作を構成することで、反応性非反応性 に設定することができます。 既定では更新動作は反応性ですので、プロパティを編集すると、変更を知ることができます。 動作が反応性の場合、変更は即座に保存されます。

Web パーツ プロジェクトの構造

Visual Studio Code を使用して、Web パーツ プロジェクトの構造を調べるには

  1. コンソールで、プロセスを終了してローカル Web サーバーを停止します。 Windows または macOS で CTRL+C を押します。

  2. 次のコマンドを入力し、VS Code で Web パーツ プロジェクトを開きます (または、好みのエディターを使用)。

    code .
    

注意

このコマンドを実行するときにエラーが発生した場合、コード コマンドを PATH にインストールする ことが必要になる場合があります。

TypeScript は、SharePoint のクライアント側 Web パーツを構築するための主言語です。TypeScript は、プレーンな JavaScript にコンパイルされる JavaScript の型付けスーパーセットです。SharePoint のクライアント側開発ツールは、TypeScript のクラス、モジュール、およびインターフェイスを使用して構築されることで、開発者は信頼性の高いクライアント側 Web パーツを構築することができます。

プロジェクト内のいくつかのキー ファイルを次に示します。

Web パーツ クラス

src\webparts\helloworld フォルダーの HelloWorldWebPart.ts は、Web パーツのメイン エントリ ポイントを定義します。 Web パーツ クラスの HelloWorldWebPartBaseClientSideWebPart を拡張します。 クライアント側の Web パーツは、BaseClientSideWebPart クラスを拡張し、有効な Web パーツとして定義されます。

BaseClientSideWebPart は、Web パーツの構築に必要な最小限の機能を実装しています。 このクラスには、多くのパラメーターもあり、displayMode や Web パーツのプロパティ、Web パーツのコンテキスト、Web パーツ instanceId、Web パーツ domElement、その他の読み取り専用プロパティへのアクセスと検証を行います。

Web パーツのクラスはプロパティ タイプの IHelloWorldWebPartProps を受け入れるよう定義されています。

プロパティ タイプは、HelloWorldWebPart.ts ファイル内の HelloWorldWebPart クラスの前のインターフェイスとして定義されています。

export interface IHelloWorldWebPartProps {
  description: string;
}

このプロパティ定義を使用して、Web パーツのカスタム プロパティ タイプを定義します。これは後でプロパティ ウィンドウのセクションにて説明します。

Web パーツのレンダリング方法

Web パーツをレンダリングする必要がある DOM 要素は、render() メソッドで使用できます。 この方法を使用して DOM 要素内の Web パーツをレンダリングします。 HelloWorld の Web パーツでは、DOM の要素は、DIV に設定されています。

public render(): void {
  this.domElement.innerHTML = `
    <div class="${ styles.helloWorld }">
      <div class="${ styles.container }">
        <div class="${ styles.row }">
          <div class="${ styles.column }">
            <span class="${ styles.title }">Welcome to SharePoint!</span>
            <p class="${ styles.subTitle }">Customize SharePoint experiences using web parts.</p>
            <p class="${ styles.description }">${escape(this.properties.description)}</p>
            <a href="https://aka.ms/spfx" class="${ styles.button }">
              <span class="${ styles.label }">Learn more</span>
            </a>
          </div>
        </div>
      </div>
    </div>`;
}

このモデルには十分な柔軟性がありますので、Web パーツを任意の JavaScript フレームワークに組み込み、DOM 要素に読み込むことができます。

Web パーツのプロパティ ウィンドウの構成

プロパティ ウィンドウは、HelloWorldWebPart クラスで定義されています。 getPropertyPaneConfiguration プロパティでは、プロパティ ウィンドウを定義する必要があります。

プロパティを定義すると、render() メソッドで示されるように this.properties.<property-value> を使用して、Web パーツ内でアクセスできます。

<p class="${styles.description}">${escape(this.properties.description)}</p>

有効な文字列にするために、プロパティの値に対して HTML エスケープを実行していることに注意してください。 プロパティ ウィンドウとプロパティ ウィンドウのフィールドの種類の扱い方について詳しくは、「SharePoint のクライアント側 Web パーツを構成可能にする」を参照してください。

チェックボックス、ドロップダウンや切り替えなど、いくつかの他のプロパティをプロパティ ウィンドウに追加します。まず最初に、フレームワークからそれぞれのプロパティ ウィンドウのフィールドをインポートします。

  1. ファイルの先頭にスクロールし、@microsoft/sp-property-pane から次のものをインポート セクションに追加します。

    PropertyPaneCheckbox,
    PropertyPaneDropdown,
    PropertyPaneToggle
    

    完全なインポート セクションは、次のようになります。

    import {
      IPropertyPaneConfiguration,
      PropertyPaneTextField,
      PropertyPaneCheckbox,
      PropertyPaneDropdown,
      PropertyPaneToggle
    } from '@microsoft/sp-property-pane';
    
  2. 新しいプロパティを含むように Web パーツのプロパティを更新します。これにより、フィールドが型指定されたオブジェクトにマッピングされます。

  3. IHelloWorldWebPartProps インターフェイスを次のコードに置き換えます。

    export interface IHelloWorldWebPartProps {
      description: string;
      test: string;
      test1: boolean;
      test2: string;
      test3: boolean;
    }
    
  4. ファイルを保存します。

  5. getPropertyPaneConfiguration() メソッドを次のコードに置き換えます。これにより、新しいプロパティ ウィンドウ フィールドを追加し、それらを対応する型指定されたオブジェクトにマッピングします。

    protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
      return {
        pages: [
          {
            header: {
              description: strings.PropertyPaneDescription
            },
            groups: [
              {
                groupName: strings.BasicGroupName,
                groupFields: [
                PropertyPaneTextField('description', {
                  label: 'Description'
                }),
                PropertyPaneTextField('test', {
                  label: 'Multi-line Text Field',
                  multiline: true
                }),
                PropertyPaneCheckbox('test1', {
                  text: 'Checkbox'
                }),
                PropertyPaneDropdown('test2', {
                  label: 'Dropdown',
                  options: [
                    { key: '1', text: 'One' },
                    { key: '2', text: 'Two' },
                    { key: '3', text: 'Three' },
                    { key: '4', text: 'Four' }
                  ]}),
                PropertyPaneToggle('test3', {
                  label: 'Toggle',
                  onText: 'On',
                  offText: 'Off'
                })
              ]
              }
            ]
          }
        ]
      };
    }
    
  6. プロパティを Web パーツのプロパティに追加すると、以前にdescriptionのプロパティにアクセスした同じ方法で、プロパティにアクセスできるようになります。

    次の行を見つけます。

    <p class="${ styles.description }">${escape(this.properties.description)}</p>
    

    以前言及した行の直後に次のコードを追加します。

    <p class="${ styles.description }">${escape(this.properties.test)}</p>
    <p class="${ styles.description }">${this.properties.test1}</p>
    <p class="${ styles.description }">${escape(this.properties.test2)}</p>
    <p class="${ styles.description }">${this.properties.test3}</p>
    

    プロパティの既定値を設定するには、Web パーツのマニフェストの properties プロパティ バッグを更新する必要があります。

  7. HelloWorldWebPart.manifest.json を開き、properties を以下のとおり変更します。

    "properties": {
      "description": "HelloWorld",
      "test": "Multi-line text field",
      "test1": true,
      "test2": "2",
      "test3": true
    }
    

Web パーツのプロパティ ウィンドウは、これらのプロパティの既定値を持つようになります。

Web パーツのマニフェスト

HelloWorldWebPart.manifest.json ファイルでは、バージョン、ID、表示名、アイコン、説明など Web パーツのメタデータを定義します。 すべての Web パーツには、このマニフェストが含まれる必要があります。

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx/client-side-web-part-manifest.schema.json",
  "id": "fbcf2c6a-7df9-414c-b3f5-37cab6bb1280",
  "alias": "HelloWorldWebPart",
  "componentType": "WebPart",

  // The "*" signifies that the version should be taken from the package.json
  "version": "*",
  "manifestVersion": 2,

  // If true, the component can only be installed on sites where Custom Script is allowed.
  // Components that allow authors to embed arbitrary script code should set this to true.
  // https://support.office.com/article/Turn-scripting-capabilities-on-or-off-1f2c515f-5d7e-448a-9fd7-835da935584f
  "requiresCustomScript": false,
  "supportedHosts": ["SharePointWebPart"],

  "preconfiguredEntries": [{
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70", // Other
    "group": { "default": "Other" },
    "title": { "default": "HelloWorld" },
    "description": { "default": "HelloWorld description" },
    "officeFabricIconFontName": "Page",
    "properties": {
      "description": "HelloWorld",
      "test": "Multi-line text field",
      "test1": true,
      "test2": "2",
      "test3": true
    }
  }]
}

これで新しいプロパティが導入されました。次のコマンドを実行して、ローカルの開発環境から Web パーツをホストしていることを確認します。これにより、以前の変更が正しく適用されたことも確認できます。

gulp serve

SharePoint でホストされているワークベンチのWeb パーツをプレビューする

SharePoint ワークベンチは、SharePoint でもホストされ、開発中のローカル Web パーツをプレビューしテストします。主な利点は、SharePoint のコンテキストで実行していることと、SharePoint データを操作できることです。

  1. 次の URL に移動します。https://your-sharepoint-tenant.sharepoint.com/_layouts/workbench.aspx

    注意

    SPFx 開発者の証明書がインストールされていない場合、ワークベンチにより localhost からスクリプトを読み込まないように構成されていると通知を受けます。 コンソール ウィンドウで現在実行中のプロセスを停止し、gulp serve コマンドを再度実行する前に、gulp trust-dev-cert コマンドをプロジェクト ディレクトリ コンソールで実行して、開発者用証明書をインストールします。 詳細については、「開発者用自己署名証明書の信頼」を参照してください。

    SharePoint Online サイトで実行される SharePoint ワークベンチ

  2. SharePoint ワークベンチに Office 365 スイートのナビゲーション バーがあります。

  3. キャンバス内の [追加] アイコンを選択して、ツールボックスを表示します。 ツールボックスには、HelloWorldWebPart と併せて SharePoint ワークベンチがホストされているサイトで利用可能な Web パーツが表示されます。

    SharePoint Online サイトで実行される SharePoint ワークベンチ内のツールボックス

  4. ツールボックスから HelloWorld を追加します。 これで、SharePoint 内でホストされるページで、Web パーツを実行しています。

    SharePoint Online サイトで実行される SharePoint ワークベンチで実行される HelloWorld の Web パーツ

注意

Web パーツの色は、サイトの色に依存します。既定では、Web パーツがホストされているサイトで使用されている Office UI Fabric Core スタイルを動的に参照することにより、Web パーツはサイトのコア色を継承します。

Web パーツはまだ開発中でテスト段階のため、Web パーツをパッケージ化し SharePoint に展開する必要はありません。

次の手順

おめでとうございます。Hello World Web パーツを初めて実行できました。

Web パーツは実行していますので、次のトピック、「Web パーツを SharePoint に接続する」で、Hello World Web パーツのビルドを続けることができます。 同じ Hello World Web パーツ プロジェクトを使用して、SharePoint REST API と相互に操作する機能を追加します。 なお、gulp serve コマンドは、コンソール ウィンドウ内 (または、エディターとして使用している場合は Visual Studio Code 内) で引き続き実行中です。 それを実行しながら、次の記事に移動します。