List Filter Online での SharePoint 列の書式設定 JSON の使用

はじめに

列の書式設定は、SharePoint Online の機能で、JSON の記述によって列の表示方法を変更します。たとえば、ステータスを色付きのピルで表示したり、数値をその値に応じて色分けしたり、ユーザーをメールを開始するリンクとして表示したりできます。この記述は列自体に保存され、SharePoint はリストのすべてのビューにそれを適用します。

List Filter Online は、これらの記述に対応できます。このオプションを有効にすると、Web パーツは、書式が設定されている各列の列の書式設定 JSON を読み取り、それに基づいてテーブルのセルを描画します。そのため、ページ上のテーブルは元のリストと同じ見た目になります。この Web パーツは、列の書式設定言語のうち、よく使われるサブセットを実装しています。この記事では、何がサポートされ、何がサポートされないか、そして書式がサブセットを超えた場合にどうなるかを正確に説明します。

列の書式設定の有効化

ページを編集し、Web パーツのプロパティ ペインを開いて、Appearance (外観) グループを展開します。Use column formatting from the list (リストの列の書式設定を使用する) をオンにします。このオプションは既定でオフです。

JSON 自体を Web パーツに入力することはありません。JSON は、ソース リストの列の定義から取得されます。これは、リストで列の設定 → この列を書式設定を開いて書式を保存したときに SharePoint が編集するものと同じ定義です。Web パーツは、列の他のプロパティと一緒にそれを読み込むため、別のサイトにあるリストの列に設定された書式も適用されます。書式は列ごとに設定されます。書式を持つすべての列はその書式に基づいて描画され、書式のない列は、列コンフィギュレーターで選択された表示形式のままになります (KB10258. List Filter Online での列の構成: 見出し、形式、表示オプションを参照してください)。

列に書式が適用されると、その列の Linked to item (アイテムへのリンク) オプションを含め、セルが完全に置き換えられます。値をクリック可能なままにしたい場合は、書式自体にリンクを含めてください。

サポートされる機能

要素

書式は要素のツリーです。各要素は、次のキーを持つオブジェクトです。

• elmType — div、span、a、img、button、p のいずれかです。後述のサポートされない値を除き、それ以外の値は div として描画されます。
• txtContent — 要素のテキストです。リテラル文字列、フィールド トークン、または式を指定できます。
• style — 要素の CSS プロパティです (後述)。
• attributes — 要素の HTML 属性です (後述)。
• children — 子要素の配列で、順番に描画されます。

$schema や debugMode など、Web パーツが認識しないキーは無視されます。

スタイル

style オブジェクトでは次の CSS プロパティを設定できます。すべての値は、リテラルまたは式にできます。

background, background-color, border, border-top, border-right, border-bottom, border-left, border-color, border-style, border-width, border-radius, box-shadow, color, cursor, direction, display, fill, flex-direction, flex-wrap, align-items, justify-content, font-family, font-size, font-style, font-weight, letter-spacing, line-height, text-align, text-decoration, text-overflow, text-transform, white-space, word-break, overflow, opacity, visibility, padding, padding-top, padding-right, padding-bottom, padding-left, margin, margin-top, margin-right, margin-bottom, margin-left, width, min-width, max-width, height, min-height, max-height.

この一覧にないプロパティ (たとえば、テーブルのレイアウトを崩す可能性のある position や z-index) は、通知なくスキップされます。url( を含む値もスキップされるため、スタイルを通じて背景画像を読み込むことはできません。

属性

role、aria-*、d、data-interception を含むその他の属性は無視されます。

フィールド トークン

トークンは単独で使用できます ("txtContent": "@currentField")。また、より長い文字列の中にも記述できます ("txtContent": "Owner: [$Owner.title]")。複数値の列 (複数のユーザー、参照、またはターム) は、コンマ区切りの一覧として表示されます。複数値の列に対する [$Owner.email] のようなプロパティ アクセスは、最初の値のプロパティを返します。ユーザーと参照の値は名前が表示され、日付はローカライズされた日付として表示されます。

式

式は、演算子ツリー (operator と operands を持つオブジェクト) として、または SharePoint の Excel に似た構文を使用して = で始まる文字列として記述できます。どちらの形式も、同じ一連の演算をサポートしています。

• 算術: + (文字列の連結も可)、-、*、/、%。
• 比較: ==、!=、>、<、>=、<= — 日付はタイム スタンプで比較されます。
• 論理: &&、||、!、条件演算子 ? : (ツリーでは、3 つのオペランドを持つ演算子 ? または :)、および関数 if(condition, whenTrue, whenFalse)。
• 変換: toString()、Number()、Date()。
• 数値: abs()、floor()、ceiling()。
• 文字列: toLowerCase()、toUpperCase()、indexOf()、substring()、length()。

= で始まる文字列では、文字列リテラルは単一引用符または二重引用符で記述し、数値は数字で、ブール値は true と false で記述します。かっこで部分式をグループ化でき、フィールド トークンはそのまま使用します: =if([$Priority] == 'High', '#a4262c', '#323130')。

サポートされない機能

Web パーツは、列の書式設定言語の次の部分を実装していません。

• forEach — 複数値の列の各値に対して要素を繰り返す機能。
• customRowAction — フローの開始、パネルの表示、フィールド値の設定を行うボタン。
• elmType: "filepreview" — ドキュメントのプレビュー。
• elmType: "svg" と path — インライン ベクター グラフィックス。
• トークン @rowIndex、@window、@thumbnail、@currentWeb、およびこの記事に記載されていないその他のトークン。
• toLocaleString()、toLocaleDateString()、startsWith()、padStart()、replace()、split()、join()、getDate()、addDays()、getUserImage()、cos()、sin() など、この記事に記載されていない演算子と関数。

forEach、customRowAction、filepreview、svg、不明な演算子や関数、不明な @ トークン、または = 式の構文エラーを使用する書式は、描画できません。その場合、Web パーツはその書式を断念し、あたかもその列でオプションがオフであるかのように、列を既定の表示 (列コンフィギュレーターで選択された形式) で描画します。他の列には影響しません。一方、不明な属性やスタイル プロパティは単にスキップされ、書式の残りの部分は適用されます。

サンプル

次の書式は、サポートされるサブセットの範囲内に収まっています。

ステータス ピル。 選択肢の値が、値に応じて色が変わる丸みのある背景の上に表示されます。

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "div",
  "txtContent": "@currentField",
  "style": {
    "display": "inline-block",
    "padding": "2px 10px",
    "border-radius": "12px",
    "font-weight": "600",
    "color": "#ffffff",
    "background-color": "=if(@currentField == 'Approved', '#107c10', if(@currentField == 'Rejected', '#a4262c', '#8a8886'))"
  }
}

値に応じて色分けされた数値 (演算子ツリーで記述)。1000 を超える金額は赤の太字で表示されます。

{
  "elmType": "span",
  "txtContent": "@currentField",
  "style": {
    "color": {
      "operator": "?",
      "operands": [
        { "operator": ">", "operands": [ { "operator": "Number()", "operands": [ "@currentField" ] }, 1000 ] },
        "#a4262c",
        "#107c10"
      ]
    },
    "font-weight": "=if(Number(@currentField) > 1000, '700', '400')"
  }
}

アイコン付きのリンク。 Assigned To 列のユーザーが、封筒のアイコン付きのメール リンクとして表示されます。この書式は Assigned To 列自体に設定され、ユーザー値のプロパティを使用します。

{
  "elmType": "a",
  "attributes": {
    "href": "='mailto:' + @currentField.email",
    "title": "=@currentField.title",
    "iconName": "Mail",
    "target": "_blank"
  },
  "txtContent": "@currentField.title",
  "style": {
    "color": "#0078d4",
    "text-decoration": "none"
  }
}

パフォーマンス

列の JSON は、その列のセルが初めて描画されるときに 1 回だけ解析され、解析されたツリーは、その列の他のすべてのセルと、以降のすべてのアイテムのページで再利用されます。セルごとに評価されるのは、トークンと式のみです。そのため、このオプションを有効にしても、長いページでもテーブルが表示されるまでの時間はほとんど増えません。

関連記事