SharePoint Framework での Office UI Fabric Core および Fabric React の使用

[アーティクル]
03/21/2023

Office UI Fabric は、Office 365と SharePoint でエクスペリエンスを構築するための公式のフロントエンドフレームワークです。 SharePoint は、最新のチームサイト、モダンページ、モダンリストなど、さまざまな SharePoint エクスペリエンスにわたって堅牢で一貫性のある設計言語を提供できるようにする Fabric とのシームレスな統合を提供します。さらに、Office UI Fabricは、カスタム SharePoint ソリューションをビルドするときに、SharePoint Frameworkの開発者が使用できます。

Microsoft は、SharePoint では Fabric Core および Fabric React を使用します。 Microsoft は SharePoint Online へ更新プログラムを定期的にプッシュしているため、Fabric Core と Fabric React のバージョンも更新される可能性があります。これらの更新プログラムは、以前のバージョンの Fabric Core と Fabric React で構築されたサードパーティの顧客ソリューションと競合する可能性があり、これらのカスタマイズで例外が発生する可能性があります。こういった種類の障害の主な理由としては、両方の Fabric ライブラリでのグローバル CSS スタイルの使用が考えられます。このような競合は、必ず回避する必要があります。

グローバル CSS スタイルの課題については、次のプレゼンテーション「React CSS in JS」の React と JavaScript に関する話題で詳しく説明しています。

信頼性を高めるために解決すべき主要な問題の 1 つとして、グローバル CSS スタイルの問題があります。この問題に対処するには、HTML マークアップ内でのグローバルクラス名の使用を避け、代わりに Sass 宣言ファイルで Fabric Core mixin と変数を使用する必要があります。これには、SASS ファイルで Fabric Core の SASS 宣言をインポートした後、変数と mixin を適切に使用することが含まれます。

目標

SharePoint Framework の目標は、Microsoft とお客様の両方が、SharePoint 上で、豊富で快適な、一貫性のあるユーザーエクスペリエンスを構築できるようにすることです。

これらの目標に調和した、以下の重要なデザインの原則があります。

お客様がソリューション内で Fabric Core と Fabric React をスムーズかつ確実に使用できるようにします。
Microsoft は、お客様のソリューションと競合することなく、SharePoint 内で Fabric Core と Fabric React の更新されたバージョンを使用する更新されたエクスペリエンスをロールアウトします。
お客様は、ソリューションのニーズに合わせて、既定のスタイル、デザイン、コンポーネントをカスタマイズしオーバーライドすることができます。

開発者が使用できる Office UI Fabric は、2 つの部分に分けられます。

Office UI Fabric Core コアスタイル、文字体裁、レスポンシブグリッド、アニメーション、アイコン、デザイン言語全体の他の基本的な文書パーツのセット。
Office UI Fabric React React ベースのプロジェクトで使用する、Fabric デザイン言語上に構築された React コンポーネントのセット。

Office UI Fabric Core パッケージ

SharePoint Framework Fabric Core npm パッケージ (@microsoft/sp-office-ui-fabric-core) には、SharePoint Framework コンポーネント内で安全に使用できる、サポートされている Fabric Core スタイルのサブセットが含まれています。

このパッケージでは、以下のコアスタイルがサポートされています。

文字体裁
レイアウト
色
テーマ
ローカライズ

このパッケージでは以下のものはまだサポートされていません。

アニメーション
アイコンの場合

SharePoint Framework Yeoman ジェネレーターのバージョン 1.3.4 以降、既定のプロジェクト (Web パーツと拡張機能) テンプレートは、新しい @microsoft/sp-office-ui-fabric-core パッケージでセットアップされ、グローバル CSS スタイルを使用する代わりに、パッケージからコアスタイルを使用します。

既存のプロジェクトの更新

既存のプロジェクトで Fabric Core パッケージを使用するには、パッケージを依存関係としてインストールします。

npm install @microsoft/sp-office-ui-fabric-core --save

インストール後、Sass 定義ファイル内の Fabric Core Sass 宣言をインポートし、以下のセクションで説明するように mixin と変数を使用することができます。

Fabric Core スタイルの使用

Fabric Core スタイルを使用するには、Sass ファイルに SPFabricCore 宣言をインポートする必要があります。

注:

@microsoft/sp-office-ui-fabric-core npm パッケージがインストールされていることを確認してください。

@import '~@microsoft/sp-office-ui-fabric-core/dist/sass/SPFabricCore.scss';

そうすることで、コアスタイルを mixin および変数として使用できます。

.row {
  @include ms-Grid-row;
  @include ms-fontColor-white;
  background-color: $ms-color-themeDark;
  padding: 20px;
}

Office UI Fabric React

SharePoint Framework の Yeoman ジェネレーターのプロジェクトに含まれているバージョンの Office UI Fabric React パッケージを使用することをお勧めします。たとえば、SharePoint Framework v1.7.0 リリースでは、Fabric React v5.131.0 を使用します。

注:

SharePoint Framework では、Fabric React バージョン 2.x 以前はサポートされていません。

Fabric React パッケージのインストール後、Fabric React バンドルから必要なコンポーネントをインポートできます。

//import Button component from Fabric React Button bundle
import { Button } from 'office-ui-fabric-react/lib/Button';

//use it in your component
render() {
  ...
  <div>
    <Button>click me</Button>
  </div>
  ...
}

Fabric React パッケージには、Fabric React コンポーネントで使用される、サポートされている Fabric Core スタイルが含まれています。 @microsoft/sp-office-ui-fabric-core パッケージからではなく、Fabric React パッケージから Fabric Core スタイルをインポートし、コンポーネントで正しいスタイルを使用するようにしてください。

@microsoft/sp-office-ui-fabric-core パッケージは Yeoman ジェネレーターによってソリューションに既にインストールされているため、Fabric コンポーネントを使用してコンポーネントバンドルのサイズを小さくしたい場合は、そのパッケージをアンインストールすることをお勧めします。

npm uninstall @microsoft/sp-office-ui-fabric-core --save

これで、Fabric React パッケージで使用可能な Sass 宣言からコアスタイルをインポートできます。

@import '~office-ui-fabric-react/dist/sass/_References.scss';

このアプローチとその短所について

ソリューション内の Fabric コンポーネントは、インストールした Fabric React の特定のバージョンにロックされます。新しいコンポーネントがパッケージの新しいバージョンで利用できる場合は、Fabric React パッケージを更新して、新しいコンポーネントを取得する必要があります。 Fabric コンポーネントはコンポーネントバンドルに含まれているため、コンポーネントバンドルのサイズが大きくなる可能性があります。ただし、このアプローチは、Office UI Fabric React が SharePoint Framework ソリューションで使用されている場合に公式にサポートされている唯一のアプローチとなります。

Office UI Fabric での CSS の課題

次に示す概念とリファレンスでは、クライアント側 Web パーツで Office UI Fabric を使用する場合の課題を考察しています。

CSS スタイルを追加する

グローバル CSS スタイルの回避方法は、非常に重要な課題です。現在、Fabric Core と Fabric React の両方にグローバルスタイルが含まれています。スタイルのスコープを管理するためのネイティブソリューションがブラウザーにないと、非常に大きな問題になります。

CSS のスコープは、現在、初期のディスカッション段階にあります。
iframe は、スタイルの特定には適していません。
Web コンポーネントは、スコープ設定したスタイルについて検討する別の基準ですが、これはまだディスカッション段階にあります。
React: CSS in JS のディスカッションで、問題を詳しく説明します。

グローバル名前空間の脅威に対する解決策については、この他にも Web 上にさまざまな文書があります。

CSS の特定性

CSS の特定性の Web UI への適用方法。特定性の高いスタイルは、低いスタイルをオーバーライドしますが、特定性の規則がどのように適用されるかを理解することが重要です。最上位から最下位への優先順位は、通常、次のようになります。

スタイル属性 (例: style="background:red;")
ID セレクター (#myDiv { })
クラスセレクター (.myCssClass{})、属性セレクター ([type="radio"])、擬似クラス (:hover)
型セレクター (h1)

読み込み順序。 2 つのクラスが 1 つの要素に適用され、その特定性が同じ場合、後から読み込まれたクラスが優先されます。次のコードに示すとおり、ボタンは赤で表示されます。スタイルタグの順序が変更されると、ボタンは緑で表示されます。これは重要な概念であり、正しく使用しないと、ユーザーエクスペリエンスが読み込み順序に依存し、整合性が保たれなくなります。

<style>
  .greenButton { color: green; }
</style>
<style>
  .redButton { color: red; }
</style>
<body>
  <button class="greenButton redButton"></button>
</body>

検討されて破棄されたその他のアプローチ

以下は、サードパーティ開発者が安全に Office UI Fabric スタイルを使用するという主要目的を達成できないため、検討されながらも破棄されたその他のアプローチについての追加の説明になります。

Office UI Fabric Core

スコープ設定を明示的に実行するための、Web パーツ開発者に必要な作業は特にありません。この問題は、CSS の特定性と子孫セレクターによって解決する予定です。 Fabric Core チームから、fabric-6.css、fabric-6-scoped.css、fabric-6.0.0.css、fabric-6.0.0-scoped.css など、Fabric Core css のコピーが複数出荷されます。

スコープ設定された CSS ファイルのスタイルはすべて、.ms-Fabric--v6-0-0 .ms-Icon--List のように、子孫セレクターの内部にあります。コンパイル時には、ツールによって、Web パーツがビルドされた Office UI Fabric Core のバージョンが収集されます。このバージョンは SharePoint Framework に付属しているものです。また、Web パーツ開発者は、その package.json ファイルで、Office UI Fabric Core の特定バージョンで明示的な依存関係を指定することもできます。

Web パーツ div はこのスコープで <div data-sp-webpart class="ms-Fabric--v6-0-0"> のように割り当てられます。 Framework は、Fabric Core でスコープ設定された CSS ファイルの特定のメジャーバージョンを読み込みます。 Web パーツが Fabric Core CSS のバージョン 6.0.0 でビルドされた場合には、Framework は Web パーツの読み込み時に fabric-6-scoped.css をダウンロードします。

ページの残りの部分には、スコープのない Office UI Fabric Core スタイルが含まれることになります。このように、CSS の特定性の規則により、スコープ設定されている CSS が Web パーツ div 内で優先されます。 Web パーツとそのコンテンツは、開発者が選択した特定のバージョンの Office UI Fabric Core に揃えられます。

Fabric Core スタイルのオーバーライドはサポートされません。

// Sample of how the scoping would work.
import { SPComponentLoader } from '@microsoft/sp-loader';

export default class MyWebPart {
    constructor() {
        super();

        SPComponentLoader.loadCss('https://static2.sharepointonline.com/files/fabric/office-ui-fabric-core/6.0.0/css/fabric-6.0.0.scoped.css');
    }
}

protected render(): void {
  <div className="ms-Fabric--v6-0-0">
    { // Rest of the web part UI }
  </div>
}

この戦略の短所

この戦略を一定期間分析した後、子孫セレクターアプローチには、中断しない Web パーツをビルドできなくする 2 つの重大な欠点があることが判明しました。

信頼できるネストサポートがない

このアプローチは、上述のように、Microsoft ユーザーエクスペリエンス (ページとファーストパーティの Web パーツ) で Office UI Fabric Core のスコープ設定されていないバージョン (ms-Icon--List など) を使用しており、サードパーティ Web パーツがスコープ設定されている Office UI Fabric Core CSS だけを使用している場合にのみ有効です。

その理由は、スコープ設定された CSS が Web パーツに適用される特定性により、ページ上のスコープ設定されていない CSS がオーバーライドされるためです。前述のとおり、2 つのクラスの CSS の特定性が同じであれば、CSS クラスの適用方法は、その読み込み順序に左右されるということに留意してください。優先されるのは、後で読み込まれるクラスになります。このため、スコープ設定された CSS の特定性を高くすることは、エクスペリエンスに一貫性を持たせる上で重要です。

さらに、拡張機能が複数あり、ある拡張機能が別の拡張機能を包含している場合、異なる Fabric Core バージョンを使用することはできません。次の例では、ms-Fabric--v6-0-0 のみが適用されます。

<div className="ms-Fabric--v6-0-0">
  { // Rest of the web part UI }
    { // inside of this SPExtension trying to use different Fabric core version does not work }
    <div className="ms-Fabric--v8-0-0">
    </div>
</div>

この問題について、さらに簡単なサンプルを示します。

<html>
<head>
  <title>CSS specifity test</title>
  <style>
  .myButton {
      background-color: brown;
      color: brown;
      height: 20px;
      width: 40px;
  }
  </style>
  <style>
  .scope2 .myButton {
      background-color: green;
      color: green;
  }
  </style>
  <style>
  .scope3 .myButton {
      background-color: yellow;
      color: yellow;
  }
  </style>
  <style>
  .scope1 .myButton {
      background-color: red;
      color: red;
  }
  </style>
</head>
<body>
  <div>
    <span>These tests demonstrate descendant selectors, nesting and load order problems.</span>

    <div>
      <br/>
      <span>This test depicts that a descendant selector with the same specificity does not allow nesting.
      All buttons below do not take the innermost scope (i.e. they should be different colors), but they are all red.
      Further, if you change the ordering of the style tags, the colors will change. (i.e. the UI is load order dependant.)</span>
      <div class='scope1'>
        <button class='myButton'</button>
        <div class='scope2'>
          <button class='myButton'></button>
          <div class='scope3'>
            <button class='myButton'></button>
          </div>
        </div>
      </div>
    </div>
  </div>
</body>
</html>

スコープ設定されていないクラスからの漏えい

子孫セレクターには、別の問題もあります。前述の例では、スコープ設定されていない myButton クラスからの高さと幅のスタイルがすべてのボタンに適用されています。これは、スコープ設定されたマークアップを使用すると、そのスタイルの変更が、HTML の予期しない中断を引き起こす可能性があることを示しています。

たとえば、アプリレベルの何らかの理由により、myButton クラスで高さを 0px にするとします。その結果として、myButton クラスを使用するすべてのサードパーティの Web パーツの高さも 0 になってしまいます (ユーザーエクスペリエンスに重大な不具合が発生します)。

従来の Office UI Fabric スタイルを安全に使用 (SPFx v1.8.2 以降)

重要

次のガイダンスは、SharePoint Framework >= 1.8.2 に適用されます

Web パーツマニフェストで従来の Fabric Core スタイルをページに読み込む必要があることを確認します。これを行うには、ソリューションマニフェストで loadLegacyFabricCss: true を指定します。

SPFx v1.8.2 のリリース前は、従来の Fabric Core スタイルが対象範囲外で読み込まれるホストページのバグが存在していました。したがって、別のソリューションでスタイルが要求された場合、ページ上の他のすべてのソリューションでスタイルを使用できます。これにより、ソリューションが単独で提供されない場合に「偶然」動作するようになりました。

このバグに対処するため、スタイルの対象範囲を .ms-SPLegacyFabricBlock クラスに設定し、Fabric Core スタイルシートを読み込む必要がある SPFx ソリューションに適用しました。上記の副作用に依存するソリューションの移行パスを提供するために、.ms-SPLegacyFabricBlock クラスはサードパーティのソリューションに公開されているすべての <div> に適用されます。その間に、影響を受けるソリューションを変更して、従来の Fabric Core スタイルへの依存を宣言します。

重要

最終的に、への.ms-SPLegacyFabricBlock明示的な参照は、依存関係を宣言しないソリューションの DOM から削除されます。この変更は、このクラスを削除する前に、既存のチャネルを介して広く通知される予定です。

SPFx によって提供されない DOM 要素 (通常はサポートされていない) で実行されているソリューションの場合は、.ms-SPLegacyFabricBlock クラスを自分で適用する必要があります。

SPFx コンポーネントでの Office UI Fabric アイコンの使い方

SharePoint Framework v1.8.2 以降では、SharePoint のフレームワークの解決策のレンダリングにおいて Office UI Fabric アイコンの使い方に変更があります。

従来のアイコン使用方法 (SPFx 1.8.2 以前)

<i className={css('ms-Icon', 'ms-Icon--RecurringEvent')}></i>

更新されたアイコンの使用方法 (SPFx 1.8.2以降)

ソリューションの構築には JavaScript フレームワークのオプションはありません。

@uifabric/stylingにパッケージを追加package.jsonします。
必要なアイコンをコード中に取得するには、次のようにコードの変更を行います。

import { getIconClassName } from '@uifabric/styling';

return `<i class="${getIconClassName('Mail')}" />`;

ソリューションの構築には React オプションを使用するか、一般的な React を使用します。

まだ追加されていない場合は、office-ui-fabric-reactにパッケージを追加package.jsonします。
必要なアイコンをコード中に取得するには、次のようにコードの変更を行います。

import { Icon } from 'office-ui-fabric-react/lib/Icon';

<Icon iconName='Mail' />

次の方法で共有

SharePoint Framework での Office UI Fabric Core および Fabric React の使用

目標

Office UI Fabric Core パッケージ

既存のプロジェクトの更新

Fabric Core スタイルの使用

Office UI Fabric React

このアプローチとその短所について

Office UI Fabric での CSS の課題

CSS スタイルを追加する

CSS の特定性

検討されて破棄されたその他のアプローチ

Office UI Fabric Core

この戦略の短所

信頼できるネストサポートがない

スコープ設定されていないクラスからの漏えい

従来の Office UI Fabric スタイルを安全に使用 (SPFx v1.8.2 以降)

SPFx コンポーネントでの Office UI Fabric アイコンの使い方

従来のアイコン使用方法 (SPFx 1.8.2 以前)

更新されたアイコンの使用方法 (SPFx 1.8.2以降)

関連項目

その他のリソース

次の方法で共有

SharePoint Framework での Office UI Fabric Core および Fabric React の使用

目標

Office UI Fabric Core パッケージ

既存のプロジェクトの更新

Fabric Core スタイルの使用

Office UI Fabric React

このアプローチとその短所について

Office UI Fabric での CSS の課題

CSS スタイルを追加する

CSS の特定性

検討されて破棄されたその他のアプローチ

Office UI Fabric Core

この戦略の短所

信頼できるネスト サポートがない

スコープ設定されていないクラスからの漏えい

従来の Office UI Fabric スタイルを安全に使用 (SPFx v1.8.2 以降)

SPFx コンポーネントでの Office UI Fabric アイコンの使い方

従来のアイコン使用方法 (SPFx 1.8.2 以前)

更新されたアイコンの使用方法 (SPFx 1.8.2以降)

関連項目

その他のリソース

信頼できるネストサポートがない