チュートリアル: コンポーネントで依存ライブラリを使用する

2025-04-15

[このトピックはプレリリースドキュメントであり、変更されることがあります。]

このチュートリアルでは、別のコンポーネントに含まれるライブラリに依存するモデル駆動型アプリのコードコンポーネントを構築する方法を示します。依存ライブラリのプレビューに関する詳細を見る

ゴール

このチュートリアルの手順に従って、ライブラリコントロールとそれに依存するコントロールを作成します。このチュートリアルには次の手順が含まれます。

ライブラリコンポーネントを構築する: 再利用可能なライブラリのみを含むコンポーネントを作成します。わかりやすくするために、このコントロールには再利用可能なライブラリのみが含まれています。十分機能を提供できます。
依存コントロールを構築する: ライブラリコントロールで定義されたライブラリを使用するコンポーネントを作成し、それをモデル駆動型アプリのフォームに追加して、動作を確認します。
依存ライブラリをオンデマンドで読み込む: この例を拡張して、コントロールの読み込み時にフレームワークがライブラリを読み込むのではなく、依存コンポーネントがオンデマンドでライブラリリソースを読み込むようにします。

前提条件

次の方法を既に知っている必要があります。

1. ライブラリコンポーネントをビルドする

このコンポーネント自体は機能を提供しません。これは単にライブラリのコンテナです。

最初のステップは、pac pcf init コマンドを使用して新しいコンポーネントを作成することです。

pac pcf init -n StubLibrary -ns SampleNamespace -t field -npm

ライブラリを定義する

ライブラリに含まれるオブジェクトと関数を記述するための新しい宣言ファイル (d.ts) が必要です。 myLib.d.ts という名前のプロジェクトのルートフォルダーに、新しいファイルを作成します:
```
declare module 'myLib' {
  export function sayHello(): string;
}
```
ライブラリをUMDモジュールとして公開し、変数をグローバルスコープに配置する必要があります。このためには、新しい宣言ファイル(d.ts)が必要です。 global.d.ts という名前のプロジェクトのルートフォルダーに、新しいファイルを作成します:
```
/* eslint-disable no-var */
declare global {
  var myLib: typeof import('myLib');
}

export { };
```

UMD モジュールと JavaScript コードを許可するようにtsconfig.jsonを次のように更新します。

{
    "extends": "./node_modules/pcf-scripts/tsconfig_base.json",
    "compilerOptions": {
        "typeRoots": ["node_modules/@types"]
    }
}

{
    "extends": "./node_modules/pcf-scripts/tsconfig_base.json",
    "compilerOptions": {
        "typeRoots": ["node_modules/@types"],
        "allowJs": true,
        "allowUmdGlobalAccess": true,
        "outDir": "dist"
    },
}

ライブラリを追加

新しいコントロールフォルダーに、ライブラリ libs を含む新しいフォルダーを追加し、この例で新しい JavaScript ファイルを作成します。この例では、myLib-v_0_0_1.js という名前のライブラリを使用します。このライブラリには sayHello 関数が 1 つあります。

// UMD module pattern
var myLib = (function (exports) {
"use strict";

function sayHello() {
   return "Hello from myLib";
}

exports.sayHello = sayHello;

return exports;
})(/** @type {import('myLib')}  */ ({}));

構成データの追加

プロジェクトのルートフォルダーに、featureconfig.json という名前のファイルを追加します。
次のテキストを featureconfig.json ファイルに追加します。
```
{
  "pcfAllowCustomWebpack": "on",
  "pcfAllowLibraryResources": "on"
}
```
featureconfig.json ファイルに関する詳細を見る
プロジェクトのルートフォルダーに、新しい webpack.config.js ファイルを追加します。この構成データにより、ライブラリがコントロール出力にバンドルされないことが保証されます。バンドルは、プロジェクトのビルド時に既に個別にパッケージ化されているため、バンドルする必要はありません。
```
/* eslint-disable */
"use strict";

module.exports = {
  externals: {
    "myLib": "myLib"
  },
}
```
webpack.config.js ファイルに関する詳細を見る
コントロールマニフェストの resources の下にライブラリへの参照を追加します。

<resources> 
  <code path="index.ts" order="1"/> 
</resources>

<resources> 
  <library name="myLib" version=">=1" order="1"> 
    <packaged_library path="libs/myLib-v_0_0_1.js" version="0.0.1" /> 
  </library> 
  <code path="index.ts" order="2"/> 
</resources>

ライブラリをウィンドウに追加する

最後のステップは、コントロールの index.ts を編集して、ライブラリをウィンドウにバインドすることです。

import { IInputs, IOutputs } from "./generated/ManifestTypes";

export class StubLibrary
implements ComponentFramework.StandardControl<IInputs, IOutputs>
{
 constructor() {
   // Empty
 }

 public init(
    context: ComponentFramework.Context<IInputs>,
    notifyOutputChanged: () => void,
    state: ComponentFramework.Dictionary,
    container: HTMLDivElement
 ): void {
   // Add control initialization code
 }

 public updateView(context: ComponentFramework.Context<IInputs>): void {
   // Add code to update control view
 }

 public getOutputs(): IOutputs {
    return {};
 }

  public destroy(): void {
    // Add code to cleanup control if necessary
  }
}

import * as myLib from 'myLib';
import { IInputs, IOutputs } from "./generated/ManifestTypes";

export class StubLibrary
implements ComponentFramework.StandardControl<IInputs, IOutputs>
{
 constructor() {
   // Empty
 }

 public init(
    context: ComponentFramework.Context<IInputs>,
    notifyOutputChanged: () => void,
    state: ComponentFramework.Dictionary,
    container: HTMLDivElement
 ): void {
   // Add control initialization code
 }

 public updateView(context: ComponentFramework.Context<IInputs>): void {
   // Add code to update control view
 }

 public getOutputs(): IOutputs {
    return {};
 }

  public destroy(): void {
    // Add code to cleanup control if necessary
  }
}

(function () {
   window.myLib = myLib;
})();

ライブラリプロジェクトは次のように表示されます:-

プロジェクトフォルダの表示

ライブラリコンポーネントをビルドしてパッケージ化する

ライブラリコンポーネントを完成させるには、通常どおり次の手順を実行します。

2. 依存コントロールを構築する

ライブラリコントロールができたので、それに依存するコントロールが必要です。

次のコマンドを使用して新しいコンポーネントを作成します。
```
pac pcf init -n DependencyControl -ns SampleNamespace -t field -fw react -npm
```
次のテキストを含む featureconfig.json というプロジェクトのルートフォルダーに、新しい機能コントロールファイルを追加します。
```
{
  "pcfResourceDependency": "on"
} 
```
コントロールマニフェストに依存リソースを追加します。

依存コンポーネントの solution.xml にある、依存コントロール [solution prefix]_[namespace].[control name] の schemaName を使用します。 solution.xml ファイル内の XML は、次のようになります。
```
<RootComponents>
  <RootComponent
   type="66"
   schemaName="samples_SampleNamespace.StubLibrary"
   behavior="0"
  />
</RootComponents>
```

<resources>
      <code path="index.ts"
         order="1" />
      <platform-library name="React"
         version="16.14.0" />
      <platform-library name="Fluent"
         version="9.46.2" />
</resources>

<resources>
      <dependency type="control"
         name="samples_SampleNamespace.StubLibrary"
         order="1" />
      <code path="index.ts"
         order="2" />
      <platform-library name="React"
         version="16.14.0" />
      <platform-library name="Fluent"
         version="9.46.2" />    
</resources>

Global.d.tsを追加する

StubLibrary は UMD モジュールとして公開されているため、変数をグローバルスコープに配置する必要があります。このためには、新しい宣言ファイル(d.ts)が必要です。 global.d.ts という名前のプロジェクトのルートフォルダーに、新しいファイルを作成します:

/* eslint-disable no-var */

interface MyLib {
      sayHello(): string;
}

declare global {
      var myLib: MyLib;
}

export { };

ライブラリ関数を使用する

コンポーネント HelloWorld.tsx ファイルを更新して、依存ライブラリの関数を使用するようにします。ライブラリは、Window オブジェクトに実行時にロードされます。

import * as React from 'react';
import { Label } from '@fluentui/react-components';

export interface IHelloWorldProps {
  name?: string;
}

export class HelloWorld extends React.Component<IHelloWorldProps> {
  public render(): React.ReactNode {
    return (
      <Label>
        {this.props.name}
      </Label>
    )
  }
}

import * as React from 'react';
import { Label } from '@fluentui/react-components';

export interface IHelloWorldProps {
  name?: string;
}

export class HelloWorld extends React.Component<IHelloWorldProps> {
  public render(): React.ReactNode {
    return (
      <Label>
        { window.myLib.sayHello() + " from Dependency" || "Hello World"}
      </Label>
    )
  }
}

依存コンポーネントをビルドしてパッケージ化する

依存コンポーネントを完成させるには、通常どおりに次の手順を実行します。

フォームにコンポーネントを追加する

モデル駆動型フォームにコンポーネントを追加します。
フォームに移動すると、コンポーネントにテキスト Hello from myLib from Dependency が表示されます。

3.オンデマンドで依存ライブラリをロードします

コンポーネントの読み込み時にフレームワークでライブラリを読み込むのではなく、依存コンポーネントを変更してオンデマンドでライブラリリソースを読み込むことで、この例を拡張できます。オンデマンド読み込み動作は、コントロールによって使用されているライブラリが大きく、フォームの読み込み時間が長くなる場合に便利です。

オンデマンドの読み込み動作を指定する

オンデマンド読み込み動作を指定するには、2. 依存コントロールを構築するで作成したコンポーネントのコントロールマニフェストを変更します。

<resources>
    <dependency type="control"
        name="samples_SampleNamespace.StubLibrary"
        order="1" />
    <code path="index.ts"
        order="2" />
    <platform-library name="React" version="16.14.0" />
    <platform-library name="Fluent" version="9.46.2" />
</resources>

<platform-action action-type="afterPageLoad" />
<feature-usage>
    <uses-feature name="Utility"
        required="true" />
</feature-usage>
<resources>
    <code path="index.ts"
        order="1" />
    <dependency type="control"
        name="samples_SampleNamespace.StubLibrary"
        load-type="onDemand" />
    <platform-library name="React" version="16.14.0" />
    <platform-library name="Fluent" version="9.46.2" />  
</resources>

依存コンポーネントを変更して、必要に応じてライブラリを読み込む

HelloWorld.tsx を変更して、状態とメソッドを追加し、依存関係が読み込まれたら更新するようにします。

import * as React from 'react';
import { Label } from '@fluentui/react-components';

export interface IHelloWorldProps {
  name?: string;
}

export class HelloWorld extends React.Component<IHelloWorldProps> {
  public render(): React.ReactNode {
    return (
      <Label>
        { window.myLib.sayHello() + " from Dependency" || "Hello World"}
      </Label>
    )
  }
}

import * as React from 'react';
import { Label } from '@fluentui/react-components';

export interface IHelloWorldProps {
  name?: string;
}

export class HelloWorld extends React.Component<IHelloWorldProps, { loaded: boolean }> {
  constructor(props: IHelloWorldProps) {
    super(props);
    this.state = {
      loaded: false
    };
  }

  public afterPageLoad() {
    this.setState({ loaded: true });
  }

  public render(): React.ReactNode {
    return (
      <Label>
          {this.state.loaded ? window.myLib.sayHello() + " Dependency On Demand Load" : 'Loading...'}
      </Label>
    )
  }
}

index.ts の更新

スクリプトがオンデマンドで読み込まれる場合は、コンポーネントの作成方法と初期化方法を若干調整する必要があります。たとえば、コンテキストへの参照や、状態を更新するためのコンテナーへの新しい変数などです。

最も重要なのは、getActions メソッドを追加して読み込み時に反応し、依存コントロールを読み込むように要求することです。

import { IInputs, IOutputs } from "./generated/ManifestTypes";
import { HelloWorld, IHelloWorldProps } from "./HelloWorld";
import * as React from "react";

export class DependencyControl implements ComponentFramework.ReactControl<IInputs, IOutputs> {
    private notifyOutputChanged: () => void;

    constructor() {
        // Empty
    }

    public init(
        context: ComponentFramework.Context<IInputs>,
        notifyOutputChanged: () => void,
        state: ComponentFramework.Dictionary
    ): void {
        this.notifyOutputChanged = notifyOutputChanged;
    }

    public updateView(context: ComponentFramework.Context<IInputs>): React.ReactElement {
        const props: IHelloWorldProps = { name: 'Power Apps' };
        return React.createElement(
            HelloWorld, props
        );
    }

    public getOutputs(): IOutputs {
        return { };
    }

    public destroy(): void {
        // Add code to cleanup control if necessary
    }
}

import { IInputs, IOutputs } from "./generated/ManifestTypes";
import { HelloWorld} from "./HelloWorld";
import * as React from "react";

export class DependencyControl implements ComponentFramework.ReactControl<IInputs, IOutputs> {
    private theComponent: ComponentFramework.ReactControl<IInputs, IOutputs>;
    private notifyOutputChanged: () => void;
    private context: ComponentFramework.Context<IInputs>;
    private mainContainerRef: React.RefObject<HelloWorld> = React.createRef<HelloWorld>();

    constructor() { 
        // Empty
    }

    public init(
        context: ComponentFramework.Context<IInputs>,
        notifyOutputChanged: () => void,
        state: ComponentFramework.Dictionary
    ): void {
        this.notifyOutputChanged = notifyOutputChanged;
        this.context = context;
    }

    public updateView(context: ComponentFramework.Context<IInputs>): React.ReactElement {
        return React.createElement(
            HelloWorld, {ref: this.mainContainerRef }
        );
    }

    public getOutputs(): IOutputs {
        return { };
    }

    public getActions(): {afterPageLoad: ()=>Promise<void>} {
        return {
            afterPageLoad: async () => {
                console.log("afterPageLoad");
                const loadedControl = await this.context.utils.loadDependency?.("samples_SampleNamespace.StubLibrary");
                if (loadedControl) {
                    this.mainContainerRef.current?.afterPageLoad();
                  } 
            },
        };
    }

    public destroy(): void {
        // Add code to cleanup control if necessary
    }
}

最終ステップ

ControlManifest.Input.xml のコントロールのバージョン番号と Solution.xml のバージョンを更新します
更新されたコントロールを使用して、ソリューションをリビルド、パッケージ化、展開、および発行します。

結果の確認

ページが読み込まれると、Loading... が表示され、コントロールが読み込まれているのを確認できます。

ページが読み込まれると、コントロールが更新されて Hello from myLib Dependency On Demand Load が表示されます。

依存ライブラリ (プレビュー)