SharePoint Framework ソリューションで CSS を使用する際の推奨事項

SharePoint Framework ソリューションを作成する際には、CSS を使用してカスタマイズの外観と動作を定義できます。この記事では、SharePoint Framework に用意された機能を最大限に活用し、堅牢な方法で CSS スタイルを構築する方法について説明します。

SharePoint Framework のカスタマイズはページの一部

アドインモデルを使用して SharePoint のカスタマイズを作成する場合、ソリューションはページ上の他の要素から分離されます。コードは iframe 内でアドインの部分として実行されるか、ページ全体を制御するイマーシブアプリケーションとして実行されます。どちらの場合も、コードはページ上で定義されている他の要素やスタイルの影響を受けません。

SharePoint Framework ソリューションはページの一部であり、ページの DOM と完全に統合されています。これにより、アドインモデルに付随するいくつかの制限事項がなくなりますが、ソリューションはリスクにさらされます。ページの一部であるため、明示的に分離されていない限り、ページにあるすべての CSS スタイルが適用され、意図しないエクスペリエンスが生じる可能性があります。このようなリスクを回避するために、CSS スタイルを定義して、ページ上のカスタマイズ以外のものに影響を与えないようにする必要があります。

ソリューションで CSS ファイルを整理する

ソリューションの UI は、多くの場合、複数の構成要素で構成されています。多くの JavaScript ライブラリでは、これらの構成要素をコンポーネントと呼びます。コンポーネントは、簡素なものでプレゼンテーションのみを定義したり、より複雑なもので状態やその他のコンポーネントを含めたりすることもできます。ソリューションを複数のコンポーネントに分割することにより、開発プロセスを簡素化し、ソリューションでのテストと再利用を容易にできます。

コンポーネントにはプレゼンテーションがあるため、多くの場合、CSS スタイルが必要になります。コンポーネントは、分離して単独で使用できるのが理想的です。その点を考慮すると、特定のコンポーネントの CSS スタイルを、コンポーネントの隣にある他のすべてのアセットファイルと共に保存することは適切といえます。以下は、コンポーネントが多数存在し、各コンポーネントがそれぞれの CSS ファイルを持つ、React アプリケーションのサンプル構造です。

todoWebPart\components
                      \todoList
                               \todoList.tsx
                               \todoList.module.scss
                      \todoItem
                               \todoItem.tsx
                               \todoItem.module.scss

Sass を使用する

SharePoint Framework では、CSS と Sass の両方を使用できます。 Sass は CSS のスーパーセットであり、変数、セレクターの入れ子、mixin など、さまざまな機能を提供します。これらの機能はすべて、長期的に CSS スタイルの操作と管理を簡素化します。

機能の完全なセットについては、「Sass の Web サイト」を参照してください。有効な CSS はすべて有効な Sass です。これは、以前 Sass で作業をしたことがなく、その機能を少しずつ習得しようと考えている場合に大変役立ちます。

マークアップでの ID の使用を回避する

SharePoint Framework を使用して、エンドユーザーが SharePoint に追加するカスタマイズを作成します。特定のカスタマイズがページ上で 1 回だけ使用されるのか、複数のインスタンスが存在するのかを前もって知ることはできません。

問題を回避するために、カスタマイズのインスタンスは同じページ上に複数存在するものと常に想定しておく必要があります。この点を考慮して、マークアップで ID を使用することは避ける必要があります。 ID はページ上で一意である必要があり、ユーザーが Web パーツをページに 2 回追加すると、この前提条件が崩れてしまい、エラーが発生する可能性があります。

悪い例

// ...

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {

  public render(): void {
    this.domElement.innerHTML = `
      <div id="helloWorld">
        Hello world
      </div>`;
  }

  // ...
}

良い例

// ...

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {

  public render(): void {
    this.domElement.innerHTML = `
      <div class="${styles.helloWorld}">
        Hello world
      </div>`;
  }

  // ...
}

CSS モジュールを使用してスタイル設定の競合を回避する

SharePoint Frameworkソリューションはページの一部です。 1 つのコンポーネントの CSS スタイルがページ上の他の要素に影響しないようにするには、ソリューションの DOM にのみ適用されるように CSS セレクターを定義する必要があります。これは面倒でエラーが発生しやすいですが、SharePoint Framework自動的に行うことができます。

スタイルの競合を回避するために、SharePoint Framework では CSS モジュールを使用します。プロジェクトの作成時に、SharePoint Framework ツールチェーンは .module.scss 拡張子を持つすべてのファイルを処理します。ファイルごとに、すべてのクラスセレクターを読み込み、一意のハッシュ値を追加します。終了後、生成された Web パーツのバンドルに含まれる中間 CSS ファイルに、更新されたセレクターを書き込みます。

前述の例を踏まえて、次の 2 つの Sass ファイルを持っていたとします。

todoList.module.scss

.todoList {
  margin: 1em 0;

  .text {
    font-weight: bold;
    font-size: 1.5em;
  }
}

todoItem.module.scss

.todoItem {
  padding: 0.5em 1em;

  .text {
    font-size: 0.9em;
  }
}

プロジェクトを作成した後、次に示す 2 つの CSS ファイルが lib フォルダーに生成されます (読みやすさを考慮して、改行とインデントを追加してあります)。

todoList.module.css

.todoList_3e9d35f0 {
  margin:1em 0
}

.todoList_3e9d35f0 .text_3e9d35f0 {
  font-weight:700;
  font-size:1.5em
}

todoItem.module.css

.todoItem_f7081cc4 {
  padding:.5em 1em
}

.todoItem_f7081cc4 .text_f7081cc4 {
  font-size:.9em
}

両方の Sass ファイルで .text クラスが定義されていますが、生成された CSS ファイルに 2 つの異なるハッシュが追加され、各コンポーネントに固有の一意のクラス名になることに注意してください。

CSS モジュールの CSS クラス名は動的に生成されるため、コードで直接参照することはできません。代わりに、CSS モジュールを処理するときに、SharePoint Framework ツールチェーンによって、生成されたクラス名への参照を含む JavaScript ファイルが生成されます。

todoList.module.scss.js

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
/* tslint:disable */
require('./todoList.module.css');
var styles = {
    todoList: 'todoList_3e9d35f0',
    text: 'text_3e9d35f0',
};
exports.default = styles;
/* tslint:enable */

//# sourceMappingURL=todoList.module.scss.js.map

生成されたクラス名をコードで使用するには、まずコンポーネントのスタイルをインポートし、次に特定のクラスを示すプロパティを使用します。

import styles from './todoList.module.scss';
// ...

export default class TodoList extends React.Component<ITodoListProps, void> {
  public render(): React.ReactElement<ITodoListProps> {
    return (
      <div className={styles.todoList}>
        <div className={styles.text}>Hello world</div>
      </div>
    );
  }
}

CSS モジュールが正しく動作するためには、次の条件を満たす必要があります。

Sass ファイルには .module.scss 拡張子が必要になります。 .module なしで .scss 拡張子を使用すると、ビルドプロセスで警告が表示されます。 Sass ファイルは中間 CSS ファイルにトランスパイルされますが、クラス名は一意にはなりません。サードパーティの CSS スタイルを上書きする必要があるようなケースでは、意図的にこのようにするかもしれません。
CSS クラス名は有効な JavaScript 変数名である必要があります。たとえば、ハイフンを含めることはできません。todoList は適切ですが、todo-list は適切ではありません。
キャメルケースでクラスに命名することが推奨されていますが、強制ではありません。

コンポーネントにちなんで名前が付けられたクラスで CSS スタイルをラップする

CSS モジュールと Sass のルールセットの入れ子のサポートを結合することで、CSS スタイルを簡略化し、ページ上の他の要素に影響を与えないようにすることができます。

コンポーネントの CSS スタイルを作成するときは、そのスタイルをコンポーネントにちなんだ名前のクラスでラップします。コンポーネントでは、そのクラスをコンポーネントのルート要素に割り当てます。

todoList.module.scss

.todoList {
  a {
    display: block;
  }
}

TodoList.tsx

// ...

export default class TodoList extends React.Component<ITodoListProps, void> {
  public render(): React.ReactElement<ITodoListProps> {
    return (
      <div className={styles.todoList}>
        ...
      </div>
    );
  }
}

トランスパイル後、生成された CSS ファイルは次のようになります。

.todoList_3e9d35f0 a {
  display: block;
}

セレクターはコンポーネントに固有の一意のクラス名で始まるため、代替プレゼンテーションはコンポーネント内のハイパーリンクにのみ適用されます。

CSS ベンダープレフィックスの処理

SharePoint Framework では、プロジェクトの Sass または CSS ファイルにベンダープレフィックスのスタイルプロパティは必要ありません。一部の SharePoint Framework サポート対象のブラウザーでは、Sass から CSS への自動コンパイルの後に追加されたプレフィックスが必要です。このメソッドは、自動プレフィックスとも呼ばれ、SharePoint Framework での CSS ビルドチェーンの基本的な部分になります。

display: flex 宣言で定義した新しいフレックスボックスモデルを Web パーツで使用する必要がある場合には、一部の古い WebKit ベースバージョンおよび Internet Explorer バージョンでは、CSS で定義された特定のベンダープレフィックスが必要です。

.container{
  display: flex;
}

SharePoint Framework アーティファクトの Sass コードでは、ベンダープレフィックスが含まれている必要はありません。 CSS から SASS へのコンパイルが完了したら、それらは自動的に追加され、次の CSS 宣言のような結果になります。

.container_7e976ae1 {
  display: -webkit-box; // older Safari on MacOS and iOS
  display: -ms-flexbox; // IE 10 - 11
  display: flex;
}

既に適用されているプレフィックスを削除すると、アーティファクトのコードが明確になるだけでなく、読みやすくなり、今後も使用できるようになります。このプロセスは SharePoint Framework に対応するブラウザーのみをサポートするようにも構成されており、さらにエラーが減少します。

Web パーツで不要になったベンダープレフィックスが既に SASS ファイルに含まれている場合、それらの宣言は同じプロセスによって自動的に削除されます。

次の例では、サポートされているシステムでベンダープレフィックスを必要としない、border-radius プロパティを利用します。

.container {
  /* Safari 3-4, iOS 1-3.2, Android 1.6- */
  -webkit-border-radius: 7px;
  /* Firefox 1-3.6 */
  -moz-border-radius: 7px;
  /* Opera 10.5, IE 9, Safari 5, Chrome, Firefox 4, iOS 4, Android 2.1+ */
  border-radius: 7px;
}

パッケージ内で結果として得られる CSS は、次のコードに変換されます。

.container_9e54c0b0 {
  border-radius: 7px
}

自動プレフィックスの詳細については、「autoprefixer GitHub リポジトリ」を参照してください。このプロセスのデータベースは、Can I use__? で使用できます。

Office UI Fabric を統合する

カスタマイズを SharePoint や Office 365 の標準機能のように見せ、動作させることで、エンドユーザーが簡単に作業できるようになります。 Office UI Fabric は、既存のユーザーエクスペリエンスとシームレスに統合するために、カスタマイズに使用する一連のコントロールとスタイルを提供します。

SharePoint Framework での Office UI Fabric の使用の詳細については、「SharePoint Framework での Office UI Fabric Core および Fabric React の使用」を参照してください。

テーマの色を使用する

SharePoint では、ユーザーのサイトのテーマの色をユーザーが選択できます。 SharePoint Framework のカスタマイズでは、ユーザーが選択したテーマに沿って、カスタマイズを必要以上に目立たせることなく、サイトの不可欠な部分のように見せることができます。

テーマはユーザーによってサイト内で設定されるため、カスタマイズで使用する色を事前に指定することはできませんが、SharePoint Framework では自動的に、現在アクティブな配色を動的に読み込むことができます。

この機能の詳細については、「SharePoint Framework のカスタマイズでテーマの色を使用する」を参照してください。

Last updated on 2023-04-08

次の方法で共有

SharePoint Framework ソリューションで CSS を使用する際の推奨事項

SharePoint Framework のカスタマイズはページの一部

ソリューションで CSS ファイルを整理する

Sass を使用する

マークアップでの ID の使用を回避する

悪い例

良い例

CSS モジュールを使用してスタイル設定の競合を回避する

todoList.module.scss

todoItem.module.scss

todoList.module.css

todoItem.module.css

todoList.module.scss.js

コンポーネントにちなんで名前が付けられたクラスで CSS スタイルをラップする

todoList.module.scss

TodoList.tsx

CSS ベンダー プレフィックスの処理

Office UI Fabric を統合する

テーマの色を使用する

その他のリソース

CSS ベンダープレフィックスの処理