列の書式設定で SharePoint をカスタマイズするUse column formatting to customize SharePoint

列の書式設定を使用して、SharePoint のリストやライブラリのフィールドの表示方法をカスタマイズできます。You can use column formatting to customize how fields in SharePoint lists and libraries are displayed. それには、フィールドがリストビューに入ったときに表示する要素を記述し、加えて、要素に適用するスタイルを記述した JSON オブジェクトを作成します。To do this, you construct a JSON object that describes the elements that are displayed when a field is included in a list view, and the styles to be applied to those elements. 列の書式設定は、リスト アイテムまたはファイルのデータを変更しません。リストを閲覧しているユーザーへの表示の方法が変わるだけです。The column formatting does not change the data in the list item or file; it only changes how it’s displayed to users who browse the list. リスト内でビューを作成および操作できるすべてのユーザーが、列の書式設定を使ってビューのフィールドの表示方法を設定できます。Anyone who can create and manage views in a list can use column formatting to configure how view fields are displayed.

たとえば、タイトル、取り組み、任命先、状態というフィールドをもつリストは、カスタマイズがなければ次のように表示されます。For example, a list with the fields Title, Effort, Assigned To, and Status with no customizations applied might look like this:

4 つの書式設定されていない列を含む SharePoint リスト

列の書式設定により、取り組み任命先状態の各フィールドの外観をカスタマイズしたリストは、次のように表示されます。A list with the appearance of the Effort, Assigned To, and Status fields customized via column formatting might look like this:

3 つのフィールドが書式設定された SharePoint リスト

ヒント

この記事や他の多数のコミュニティ サンプルで例示されているサンプルは、オープン ソースの列フォーマット定義専用の GitHub リポジトリから入手できます。Samples demonstrated in this article and numerous other community samples are available from a GitHub repository dedicated for open-sourced column formatting definitions. これらのサンプルは、SharePoint GitHub 組織の sp-dev-column-format-format リポジトリから検索できます。You can find these samples from the sp-dev-column-formatting repository at SharePoint GitHub organization.

列の書式設定とフィールド カスタマイザーの違いとはHow is column formatting different than the Field Customizer?

列の書式設定も、SharePoint Framework のフィールド カスタマイザー拡張機能も、SharePoint リスト内のフィールドの表示方法をカスタマイズします。Both column formatting and SharePoint Framework Field Customizer extensions enable you to customize how fields in SharePoint lists are displayed. フィールド カスタマイザーを使用すると、フィールドの表示を制御する任意のコードを記述できるため、フィールド カスタマイザーの方がより強力です。The Field Customizer is more powerful because you can use it to write any code that you want to control how a field is displayed.

列の書式設定はより簡単で、幅広く応用されています。Column formatting is more easily and broadly applied. 一方で、柔軟性は低く、カスタムコードには対応していません。あらかじめ限定された一部の要素や属性のみが使用できます。However, it is less flexible, because it does not allow for custom code; it only allows for certain predefined elements and attributes.

次の表では、列の書式設定とフィールド カスタマイザーを比較しています。The following table compares column formatting and the Field Customizer.

フィールドの種類Field type 列の書式設定Column formatting フィールド カスタマイザーField Customizer
アイテムの値と値の範囲に基づく条件付きの書式設定Conditional formatting based on item values and value ranges サポートSupported サポートSupported
アクション リンクAction links スクリプトを起動しない静的なハイパーリンクのサポートSupport for static hyperlinks that do not launch script カスタム スクリプトを呼び出すものも含む、すべてのハイパーリンクのサポートSupport for any hyperlink, including those that invoke custom script
データ可視化Data visualizations HTML と CSS を使用して表現できるシンプルな可視化のサポートSupport for simple visualizations that can be expressed using HTML and CSS 任意のデータの可視化のサポートSupport for arbitrary data visualizations

列の書式設定で達成できるシナリオでは、多くの場合、フィールド カスタマイザーより列の書式設定のほうが速く、簡単です。If you can accomplish your scenario by using column formatting, it’s typically quicker and easier to do that than to use a Field Customizer. リスト内でビューを作成および操作できるすべてのユーザーが、列の書式設定を使用して、カスタマイズを作成および公開できます。Anyone who can create and manage views in a list can use column formatting to create and publish customizations. フィールド カスタマイザーは、書式設定がサポートしていない、より高度なシナリオで使用します。Use a Field Customizer for more advanced scenarios that column formatting does not support.

列の書式設定をはじめて使用するGet started with column formatting

[列の書式設定] ウィンドウを開くには、列の下のドロップダウン メニューを開きます。To open the column formatting pane, open the drop-down menu under a column. [列の設定] で、[この列の書式を設定する] を選択します。Under Column Settings, choose Format this column.

選択した列の書式設定が未使用なら、次のようなウィンドウが表示されます。If no one has used column formatting on the column you selected, the pane will look like the following.

空欄に列の書式設定を指定した JSON を入力またはペーストし、プレビュー、保存または取り消しを選択します。

書式を指定しないフィールドでは、既存の表示が使用されます。A field with no formatting specified uses the default rendering. 列の書式を設定するには、ボックスに書式を指定した JSON を入力します。To format a column, enter the column formatting JSON in the box.

書式設定をプレビューするには、[プレビュー] を選択します。To preview the formatting, select Preview. 変更内容を確定するには、[保存] を選択します。To commit your changes, select Save. 保存すると、リストはカスタム設定に従って表示されます。When you save, anyone who views the list will see the customization that you applied.

列の書式設定を使用する最も簡単な方法は、例をひな形として、特定のフィールドに応用できるように編集する方法です。The easiest way to use column formatting is to start from an example and edit it to apply to your specific field. 次のセクションに、シナリオに合わせてコピー、貼り付け、編集して活用できる例を示します。The following sections contain examples that you can copy, paste, and edit for your scenarios. SharePoint/sp-dev-column-formatting リポジトリでも、いくつかのサンプルを使用できます。There are also several samples available in the SharePoint/sp-dev-column-formatting repository.

フィールドの値を表示する (基本)Display field values (basic)

列の最も簡単な書式設定は、<div /> 要素の中にフィールドの値を挿入するものです。The simplest column formatting is one that places the value of the field inside a <div /> element. この例では、数値、テキスト、選択肢、および日付フィールドを操作します。This example works for number, text, choice, and date fields:

{
   "elmType": "div",
   "txtContent": "@currentField"
}


フィールドの種類によっては、値を取得する追加の作業が必要です。Some field types require a bit of extra work to retrieve their values. 人物フィールドは、システム内ではオブジェクトとして表され、その表示名はオブジェクトの title プロパティに入っています。Person fields are represented in the system as objects, and a person’s display name is contained within that object’s title property. これは同じ例で、人物フィールドを使用できるように変更されたものです。This is the same example, modified to work with the person field:

{
   "elmType": "div",
   "txtContent": "@currentField.title"
}


ルックアップ フィールドもオブジェクトとして表されます。表示されるテキストは、lookupValue プロパティに入っています。Lookup fields are also represented as objects; the display text is stored in the lookupValue property. この例では、ルックアップ フィールドを扱います。This example works with a lookup field:

{
   "elmType": "div",
   "txtContent": "@currentField.lookupValue"
}

条件付き書式の適用Apply conditional formatting

列の書式設定により、フィールドの中の値によってフィールドにスタイル、クラス、アイコンを適用できます。You can use column formatting to apply styles, classes, and icons to fields, depending on the value inside those fields.

数の範囲に基づく条件付き書式設定 (基本)Conditional formatting based on a number range (basic)

次の図は、数値の範囲に適用される条件付き書式設定の例を示しています。The following image shows an example of conditional formatting applied to a number range.

値が 70 になると、オレンジ色の背景で重大度を警告

この例では、条件付き演算子 ? を使用し、現在のフィールドの値が 70 以下のとき、クラス (sp-field-severity--warning) を親の <div /> 要素に適用します。This example uses the conditional operator ? to apply a class (sp-field-severity--warning) to the parent <div /> element when the value in the current field is less than or equal to 70. これにより、フィールドの値が 70 以下なら強調表示され、70 を超える場合は通常表示されます。This causes the field to be highlighted when the value is less than or equal to 70, and appear normally if it's greater than 70.

{
    "$schema": "https://developer.microsoft.com/en-us/json-schemas/sp/column-formatting.schema.json",
    "debugMode": true,
    "elmType": "div",
    "attributes": {
       "class": {
          "operator": "?",
          "operands": [
             {
                "operator": "<=",
                "operands": [
                   "@currentField",
                   70
                ]
             },
             "sp-field-severity--warning",
             ""
          ]
       }
    },
    "children": [
        {
            "elmType": "span",
            "style": {
                "display": "inline-block",
                "padding": "0 4px"
            },
            "attributes": {
                "iconName": {
                    "operator": "?",
                    "operands": [
                        {
                            "operator": "<=",
                            "operands": [
                                "@currentField",                  
                                70
                            ]
                        },
                        "Error",
                        ""
                    ]
                }
            }
        },
        {
            "elmType": "span",
            "txtContent": "@currentField"
        }
    ]
}

テキストまたは選択肢のフィールドの値に基づく条件付き書式設定 (高度)Conditional formatting based on the value in a text or choice field (advanced)

次の図は、テキストまたは選択肢のフィールドに適用される条件付き書式設定の例を示しています。The following image shows an example of conditional formatting applied to a text or choice field:

状態フィールドは、完了では緑に、ブロック状態では赤、レビュー中ではオレンジになります。

固定値のセットを含む可能性があるテキストや任意のフィールドに条件付き書式を適用することができます。You can apply conditional formatting to text or choice fields that might contain a fixed set of values. 次の例では、フィールドの値が完了、レビュー中、ブロックのどれに該当するか、または他の値であるかにより、さまざまなクラスが適用されます。The following example applies different classes depending on whether the value of the field is Done, In Review, Blocked, or another value. この例では、フィールドの値に基づいて、CSS クラス (sp-field-severity--low, sp-field-severity--good, sp-field-severity--warning, sp-field-severity--blocked) を <div /> に適用します。This example applies a CSS class (sp-field-severity--low, sp-field-severity--good, sp-field-severity--warning, sp-field-severity--blocked) to the <div /> based on the field's value. 次に、属性 IconName を持つ要素 <span /> を出力します。It then outputs a <span /> element with an IconName attribute. この属性は別の CSS クラスを、Office UI Fabric アイコンをその要素の内に表示する <span /> に適用します。This attribute applies another CSS class to that <span /> that shows an Office UI Fabric icon inside that element. 最後に、フィールド内に値が含まれた別の <span /> 要素が出力されます。Finally, another <span /> element is output that contains the value inside the field.

このパターンは、緊急性または重要度のさまざまなレベルにマップした別の値を表示する場合に便利です。This pattern is useful when you want different values to map to different levels of urgency or severity. この例をひな形として編集し、かかる値にマップされるフィールドの値、スタイル、アイコンを指定します。You can start from this example and edit it to specify your own field values and the styles and icons that should map to those values.

{
    "$schema": "https://developer.microsoft.com/en-us/json-schemas/sp/column-formatting.schema.json",
    "debugMode": true,
    "elmType": "div",
    "attributes": {
        "class": {
            "operator": "?",
            "operands": [
                {
                    "operator": "==",
                    "operands": [
                        {
                            "operator": "toString()",
                            "operands": [
                                "@currentField"
                            ]
                        },
                        "Done"
                    ]
                },
                "sp-field-severity--good",
                {
                    "operator": "?",
                    "operands": [
                        {
                            "operator": "==",
                            "operands": [
                                {
                                    "operator": "toString()",
                                    "operands": [
                                        "@currentField"
                                    ]
                                },
                                "In progress"
                            ]
                        },
                        "sp-field-severity--low",
                        {
                            "operator": "?",
                            "operands": [
                                {
                                    "operator": "==",
                                    "operands": [
                                        {
                                            "operator": "toString()",
                                            "operands": [
                                                "@currentField"
                                            ]
                                        },
                                        "In review"
                                    ]
                                },
                                "sp-field-severity--warning",
                                {
                                    "operator": "?",
                                    "operands": [
                                        {
                                            "operator": "==",
                                            "operands": [
                                                {
                                                    "operator": "toString()",
                                                    "operands": [
                                                        "@currentField"
                                                    ]
                                                },
                                                "Blocked"
                                            ]
                                        },
                                        "sp-field-severity--severeWarning",
                                        "sp-field-severity--blocked"
                                    ]
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    },
    "children": [
        {
            "elmType": "span",
            "style": {
                "display": "inline-block",
                "padding": "0 4px"
            },
            "attributes": {
                "iconName": {
                    "operator": "?",
                    "operands": [
                        {
                            "operator": "==",
                            "operands": [
                                {
                                    "operator": "toString()",
                                    "operands": [
                                        "@currentField"
                                    ]
                                },
                                "Done"
                            ]
                        },
                        "CheckMark",
                        {
                            "operator": "?",
                            "operands": [
                                {
                                    "operator": "==",
                                    "operands": [
                                        {
                                            "operator": "toString()",
                                            "operands": [
                                                "@currentField"
                                            ]
                                        },
                                        "In progress"
                                    ]
                                },
                                "Forward",
                                {
                                    "operator": "?",
                                    "operands": [
                                        {
                                            "operator": "==",
                                            "operands": [
                                                {
                                                    "operator": "toString()",
                                                    "operands": [
                                                        "@currentField"
                                                    ]
                                                },
                                                "In review"
                                            ]
                                        },
                                        "Error",
                                        {
                                            "operator": "?",
                                            "operands": [
                                                {
                                                    "operator": "==",
                                                    "operands": [
                                                        {
                                                            "operator": "toString()",
                                                            "operands": [
                                                                "@currentField"
                                                            ]
                                                        },
                                                        "Has issues"
                                                    ]
                                                },
                                                "Warning",
                                                "ErrorBadge"
                                            ]
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                }
            }
        },
        {
            "elmType": "span",
            "txtContent": "@currentField"
        }
    ]
}

日付の範囲に基づいて書式を設定するApply formatting based on date ranges

多くの場合、日付は期限やプロジェクトの重要な節目の追跡に使用されるため、日付/時刻フィールドの値に従って書式設定を行うシナリオは多く見られます。Because dates are often used to track deadlines and key project timelines, a common scenario is to apply formatting based on the value in a date/time field. 日付/時刻フィールドの値に基づいて書式を適用するには、次のパターンを適用します。To apply formatting based on the value in a date/time field, apply the following patterns.

日付の列が今日の日付以前または以降の場合にアイテムの書式を設定する (高度)Formatting an item when a date column is before or after today's date (advanced)

次の図は、日付による条件付き書式が適用されたフィールドを示しています。The following image shows a field with conditional date formatting applied:

状態フィールドが期限切れの場合はテキストを赤で表示

この例では、アイテムの期限が現在の日付/時刻以前である場合、フィールドを赤で表示します。This example colors the current field red when the value inside an item's DueDate is before the current date/time. これまでのいくつかの例と異なり、この例では、フィールドの書式を他のフィールドを参照して決定しています。Unlike some of the previous examples, this example applies formatting to one field by looking at the value inside another field. 期限は [$FieldName] 構文を使用して参照することに注意してください。Note that DueDate is referenced using the [$FieldName] syntax. フィールド名は、フィールドの内部名であると見なされます。FieldName is assumed to be the internal name of the field. この例は、日付/時刻フィールドで使用できる特殊な値 - @now も活用しています。この値には、ユーザーがリスト ビューを読み込むときの現在の日付/時刻が代入されます。This example also takes advantage of a special value that can be used in date/time fields - @now, which resolves to the current date/time, evaluated when the user loads the list view.

注意

フィールド名にスペースがある場合は、フィールド名が _x0020_ として定義されます。If you have spaces in the field name, those are defined as _x0020_. たとえば、「Due Date」という名前のフィールドは、$Due_x0020_Date として参照される必要があります。For example, a field named "Due Date" should be referenced as $Due_x0020_Date.

{

   "elmType": "div",
   "txtContent": "@currentField",
   "style": {
      "color": {
         "operator": "?",
         "operands": [
            {
               "operator": "<=",
               "operands": [
                  "[$DueDate]",
                  "@now"
               ]
            },
            "#ff0000",
            ""
         ]
      }
   }
}

任意の日付に基づいてアイテムの書式を設定 (高度)Formatting items based on arbitrary dates (advanced)

日付/時刻フィールドの値を @now 以外の日付と比較するには、次のパターンに従います。To compare the value of a date/time field against a date that's not @now, follow the pattern in the following example. 次の例は、期限が明日以前であれば、現在のフィールドを赤く表示します。い場合は、The following example colors the current field red if the due date was <= tomorrow. これには日付の演算を使用します。This is accomplished using date math. すべての日付にミリ秒単位の数値を加算でき、その結果は別の日付になります。You can add milliseconds to any date and the result will be a new date. たとえば、日付に 1 日を追加するには、(24*60*60*1000 = 86,400,000) を追加します。For example, to add a day to a date, you'd add (24*60*60*1000 = 86,400,000).

{
   "elmType": "div",
   "txtContent": "@currentField",
   "style": {
      "color": {
         "operator": "?",
         "operands": [
            {
               "operator": "<=",
               "operands": [
                  "[$DueDate]",
                  {
                     "operator": "+",
                     "operands": [
                        "@now",
                        86400000
                     ]
                  }
               ]
            },
            "#ff0000",
            ""
         ]
      }
   }
}


日付/時刻フィールドを日付の定数と比較するには、Date() メソッドを使用して文字列を日付に変換します。To compare a date/time field value against another date constant, use the Date() method to convert a string to a date. 次の例は、期限が 2017 年 3 月 22 日以前の場合に、現在のフィールドを赤で表示します。The following example colors the current field red if the value in the DueDate field is before 3/22/2017.

{
   "elmType": "div",
   "txtContent": "@currentField",
   "style": {
      "color": {
         "operator": "?",
         "operands": [
            {
               "operator": "<=",
               "operands": [
                  "[$DueDate]",
                  {
                     "operator": "Date()",
                     "operands": [
                        "3/22/2017"
                     ]
                  }
               ]
            },
            "#ff0000",
            ""
         ]
      }
   }
}

クリック可能なアクションを作成するCreate clickable actions

列の書式設定を使用して、他の Web ページに移動するハイパーリンクや、独自の機能を起動するハイパーリンクを提供できます。You can use column formatting to provide hyperlinks that go to other webpages, or start custom functionality. この機能は、リストのフィールドの値からパラメーターを生成できる、静的なリンクに限られます。This functionality is limited to static links that can be paramaterized with values from fields in the list. https://、または mailto: 以外のプロトコルへのリンクを出力する場合、列の書式設定は使用できません。http://You can't use column formatting to output links to protocols other than http://, https://, or mailto:.

この例では、株価の銘柄コードを含むテキスト フィールドを yahoo ファイナンスのリアルタイム株価ページの該当銘柄へのハイパーリンクに変える方法を示します。This example shows how to turn a text field that contains stock ticker symbols into a hyperlink that targets the Yahoo Finance real-time quotes page for that stock ticker. この例では、+ 演算子を使い、現在のフィールドの値を静的なハイパーリンク http://finance.yahoo.com/quote/ に追加します。The example uses a + operator that appends the current field value to the static hyperlink http://finance.yahoo.com/quote/. さまざまなシナリオでこのパターンを拡張し、アイテムに関連するコンテキスト情報を表示できます。また、リスト アイテムの値からパラメーターが生成可能なハイパーリンクで情報やプロセスへアクセスできるのであれば、現在のアイテムと関連するビジネスプロセスを起動できます。You can extend this pattern to any scenario in which you want users to view contextual information related to an item, or you want to start a business process on the current item, as long as the information or process can be accessed via a hyperlink parameterized with values from the list item.

銘柄コードからハイパーリンクを生成した銘柄一覧

{
   "elmType": "a",
   "txtContent": "@currentField",
   "attributes": {
      "target": "_blank",
      "href": {
         "operator": "+",
         "operands": [
            "http://finance.yahoo.com/quote/",
            "@currentField"
         ]
      }
   }
}

フィールドにアクション ボタンを追加する (高度)Add an action button to a field (advanced)

次の図は、フィールドに追加されたアクション ボタンを示しています。The following image shows action buttons added to a field.

名前にメールのボタンが追加された任命フィールド

列の書式を使い、フィールドの横にクイック アクション リンクを表示することができます。You can use column formatting to render quick action links next to fields. 次の例では、人物のフィールドで、親の要素である <div /> の中に 2 つの要素を表示します。The following example, intended for a person field, renders two elements inside the parent <div /> element:

  • 人物の表示名が含まれている <span /> 要素A <span /> element that contains the person’s display name.
  • 件名と本文をアイテムのメタデータから動的に生成したメールを作成するリンクである mailto: リンクを開く <a /> 要素An <a /> element that opens a mailto: link that creates an email with a subject and body populated dynamically via item metadata. 要素のスタイルは ms-Iconms-Icon—Mailms-QuickAction Fabric クラスを使用して設定され、クリック可能なメール アイコンのように見えるようになっています。<a />The <a /> element is styled using the ms-Icon, ms-Icon—Mail, and ms-QuickAction Fabric classes to make it look like a clickable email icon.
{
    "elmType": "div",
    "children": [
        {
            "elmType": "span",
            "style": {
                "padding-right": "8px"
            },
            "txtContent": "@currentField.title"
        },
        {
            "elmType": "a",
            "attributes": {
                "iconName": "Mail",
                "class": "sp-field-quickAction",
                "href": {
                    "operator": "+",
                    "operands": [
                        "mailto:",
                        "@currentField.email",
                        "?subject=Task status&body=Hey, how is your task coming along?.\r\n---\r\n",
                        "@currentField.title",
                        "\r\nClick this link for more info. http://contoso.sharepoint.com/sites/ConferencePrep/Tasks/Prep/DispForm.aspx?ID=",
                        "[$ID]"
                    ]
                }
            }
        }
    ]
}

単純なデータの視覚エフェクトを作成するCreate simple data visualizations

列の書式設定を使い、条件と算術演算を組み合わせて基本的なデータ視覚化を実現します。Use column formatting to combine conditional and arithmetical operations to achieve basic data visualizations.

数値の列をデータ バーに整形する (高度)Format a number column as a data bar (advanced)

次の図は、データ バーとして書式設定された数値の列を示しています。The following image shows a number column formatted as a data bar.

リストの数値アイテムがバーとして表示された取り組みリスト

この例ではスタイル background-colorborder-top を適用し、数値フィールドである @currentField のデータ バー視覚エフェクトを作成しています。This example applies background-color and border-top styles to create a data bar visualization of @currentField, which is a number field. バーのサイズは width 属性の設定方法に応じて変わります。値が 20 を超えると 100% に設定され、10 以下の場合は (@currentField * 5)% に設定されます。The bars are sized differently for different values based on the way the width attribute is set - it's set to 100% when the value is greater than 20, and (@currentField * 5)% when the value is less than 10. データ バーの値が 1 の場合は幅の 5%、2 の場合は幅の 10% になります。This achieves a width of 5% for the data bar for values of 1, 10% for values of 2, and so on. この例を各種の応用に対応させるには、フィールドで想定される最大値に境界条件 (20) を調整します。そして、フィールド内の値に応じてバーをどれだけ拡大するかを決める係数 (5) を指定します。To fit this example to your number column, you can adjust the boundary condition (20) to match the maximum anticipated value inside the field, and the multiplier (5) to specify how much the bar should grow depending on the value inside the field.

{
  "debugMode": true,
  "elmType": "div",
  "txtContent": "@currentField",
  "attributes": {
   "class": "sp-field-dataBars"
  },
  "style": {
    "width": {
      "operator": "?",
      "operands": [
        {
          "operator": ">",
          "operands": [
            "@currentField",
            "20"
          ]
        },
        "100%",
        {
          "operator": "+",
          "operands": [
            {
              "operator": "toString()",
              "operands": [
                {
                  "operator": "*",
                  "operands": [
                    "@currentField",
                    5
                  ]
                }
              ]
            },
            "%"
          ]
        }
      ]
    }
  }
}

次の図は、上昇傾向、降下傾向のアイコンが付加されたリストを示しています。The following image shows a list with trending up/trending down icons added:

リストの横に表示された上昇傾向、降下傾向のアイコン

この例では、比較可能な 2 つの数値フィールド BeforeAfter が重要です。This example relies on two number fields, Before and After, for which the values can be compared. この例では、After フィールドの横に、このフィールドの値と Before の値との比較に従って適切な傾向アイコンを表示します。表示は、It shows the appropriate trending icon next to the After field, depending on that field's value compared to the value in Before. sp-field-trending--up 2 つの値のうち、Afterの値が高ければ、sp-field-trending--up が使用され、Afterの値が低ければ sp-field-trending--down が使用されます。sp-field-trending--up is used when After's value is higher; sp-field-trending--down is used when After's value is lower.

{
    "debugMode": true,
    "elmType": "div",
    "children": [
        {
            "elmType": "span",
            "attributes": {
                "class": {
                    "operator": "?",
                    "operands": [
                        {
                            "operator": ">",
                            "operands": [
                                "[$After]",
                                "[$Before]"
                            ]
                        },
                        "sp-field-trending--up",
                        "sp-field-trending--down"
                    ]
                },
                "iconName": {
                    "operator": "?",
                    "operands": [
                        {
                            "operator": ">",
                            "operands": [
                                "[$After]",
                                "[$Before]"
                            ]
                        },
                        "SortUp",
                        {
                            "operator": "?",
                            "operands": [
                                {
                                    "operator": "<",
                                    "operands": [
                                        "[$After]",
                                        "[$Before]"
                                    ]
                                },
                                "SortDown",
                                ""
                            ]
                        }
                    ]
                }
            }
        },
        {
            "elmType": "span",
            "txtContent": "[$After]"
        }
    ]
}

フローを起動するためのボタンを作成するCreate a button to launch a Flow

次のスクリーンショットは、[アクション] 列に追加する [フロー] ボタンが含まれるリストを示しています。The following screenshot shows a list with a Flow button added to the Action column:

サンプルのスクリーンショット

列の書式設定を使用することで、選択されると対応するリスト項目のフローを実行するボタンを作成できます。You can use column formatting to create buttons that, when selected, run Flows on the corresponding list item. 実行前にエンド ユーザーからデータを収集するようフローが構成されている場合、ボタンを選択すると、[フローの起動パネル] が表示されます。If the Flow is configured to gather data from the end user before running, the Flow Launch Panel will be displayed after choosing the button. その他の場合には、すぐにフローが実行されます。Otherwise, the Flow will just run.

下にあるサンプルを使用するには、実行するフローの ID に置き換える必要があります。To use the sample below, you must substitute the ID of the Flow you want to run. この ID は、button 要素内にある customRowAction 属性に含まれています。This ID is contained within the customRowAction attribute inside the button element. フローの ID を取得するには、次のようにします。To obtain a Flow's ID:

  1. [フロー] をクリックして、フローが構成されている SharePoint リスト内のフローを表示します。Choose Flow > See your flows in the SharePoint list where the Flow is configured.
  2. 実行するフローを選択します。Choose the Flow you want to run.
  3. URL の末尾にある ID をコピーします。Copy the ID from the end of the URL.
{
    "$schema": "https://developer.microsoft.com/en-us/json-schemas/sp/column-formatting.schema.json",
    "elmType": "span",
    "style": {
        "color": "#0078d7"
    },
    "children": [
    {
        "elmType": "span",
        "attributes": {
            "iconName": "Flow"
        }
    },
    {
        "elmType": "button",
        "style": {
            "border": "none",
            "background-color": "transparent",        
            "color": "#0078d7",    
            "cursor": "pointer"
        },
        "txtContent": "Send to Manager",
        "customRowAction": {
            "action": "executeFlow",
            "actionParams": "{\"id\": \"183bedd4-6f2b-4264-855c-9dc7617b4dbe\"}"
        }          
    }        
  ]
}

サポートされている列の種類Supported column types

次の種類の列は、列の書式設定をサポートしています。The following column types support column formatting:

  • 1 行テキストSingle line of text
  • 数値Number
  • 選択肢Choice
  • 人物またはグループPerson or Group
  • はい/いいえYes/No
  • ハイパーリンクHyperlink
  • 画像Picture
  • 日付/時刻Date/Time
  • 参照Lookup
  • (リスト内の) タイトルTitle (in Lists)

現在、以下はサポートされていません。The following are not currently supported:

  • 管理されたメタデータManaged Metadata
  • ファイル名 (ドキュメント ライブラリ内)Filename (in Document Libraries)
  • 集計値Calculated
  • 保持ラベルRetention Label

スタイル ガイドラインStyle guidelines

定義済みのクラスPredefined classes

いくつかの一般的なシナリオでは、次の定義済みのクラスを使用できます。You can use the following predefined classes for several common scenarios.

クラス名Class name スクリーンショットScreenshot
sp-フィールド-customFormatBackgroundsp-field-customFormatBackground 背景を使用するすべてのクラスのパディングとマージンを指定します。Specifies the padding and margins for all classes that use backgrounds.
sp-フィールド‐深刻度--良sp-field-severity--good 「完了」のテキストとチェック マークをもつ緑のボックス
sp-フィールド‐深刻度--低sp-field-severity--low 「進行中」のテキストと矢印を含む白いボックス
sp-フィールド-深刻度--警告sp-field-severity--warning 「レビュー中」のテキストと危険のアイコンを含む黄色のボックス
sp-フィールド-深刻度--severeWarningsp-field-severity--severeWarning 「問題あり」のテキストと危険のアイコンを含むオレンジのボックス
sp-フィールド-深刻度--ブロックsp-field-severity--blocked 「ブロック」のテキストと X アイコンを含む赤いボックス
sp-フィールド-dataBarssp-field-dataBars 数値 4 を含む青いバー
sp-フィールド-トレンド--上昇sp-field-trending--up 数値 500 と緑色の矢印
sp-フィールド-トレンド--下降sp-field-trending--down 数値 100 と赤の矢印
sp-フィールド-quickActionsp-field-quickAction メール アイコンと名前

定義済みのアイコンPredefined icons

Office UI ファブリックの定義済みアイコンを使用できます。You can use predefined icons from Office UI Fabric. 詳しくは、ファブリック Web サイト を参照してください。For details, see the Fabric website.

カスタム JSON の作成Creating custom JSON

スキーマを理解すれば、列の書式設定のための JSON を簡単に一から作成できます。Creating custom column formatting JSON from scratch is simple if you understand the schema. 独自の書式設定を指定するには、To create your own custom column formatting:

  1. Visual Studio Code をダウンロードしますDownload Visual Studio Code. 無料で、手早くダウンロードできます。It's free and fast to download.

  2. Visual Studio Code で新しいファイルを作成し、空のままのファイルを、ファイル拡張子 .json を付けて保存します。In Visual Studio Code, create a new file, and save the empty file with a .json file extension.

  3. 空のファイルに次のコードを貼り付けます。Paste the following lines of code into your empty file.

     {
     "$schema": "https://developer.microsoft.com/en-us/json-schemas/sp/column-formatting.schema.json"
     }
    

    JSON 作成のための検証機能とオートコンプリートが使えるようになりました。You now have validation and autocomplete to create your JSON. JSON の追加は、スキーマの場所を定義する最初の行の後からはじめます。You can start adding your JSON after the first line that defines the schema location.

ヒント

任意の場所で Ctrl+スペース キーを押すと、Visual Studio Code はプロパティと値の提案を表示します。At any point, select Ctrl+Space to have Visual Studio Code offer suggestions for properties and values. 詳細については、「Editing JSON with Visual Studio Code」を参照してください。For more information, see Editing JSON with Visual Studio Code.

詳しい構文のリファレンスDetailed syntax reference

elmTypeelmType

作成する要素の種類を指定します。Specifies the type of element to create. 有効な要素は次のとおりです。Valid elements include:

  • divdiv
  • スパンspan
  • aa
  • imgimg
  • svgsvg
  • パスpath
  • ボタンbutton

その他の値を指定すると、エラーが発生します。Any other value will result in an error.

ボタン要素Button elements

Button 要素を使用して、親アイテムに対して特定のアクションを開始することができます。Button elements can be used to launch a specific action on the parent item. すべて button 要素には 必要とされるプロパティがあり、 customRowActionこれが、 action ボタンがクリックされたときに何が実行されるかを特定します。Every button element has a requred property, customRowAction, that specifies an action that's taken when the button is clicked. この操作は、次のいずれかの値でなければなりません。The type must be one of the following values:

  • defaultClick:このアクションのボタンは、カスタマイズされていないビューでリスト アイテムをクリックするのと同じことを行います。defaultClick: buttons with this action will do the same thing as clicking the list item in an uncustomized view. 下の例は、クリックすると、アイテムのクリックをシミュレートするボタンの例です。その結果、詳細ペインが開きます。Below is an example of a button that, when clicked, simulates a click on the item, which results in the details pane being opened.
{
  "elmType": "button",
  "txtContent": "Open this item",
  "customRowAction": {
    "action": "defaultClick"
  }
}
  • 共有:ボタンをクリックすると、共有ダイアログが開きます。share: Clicking the button will open the sharing dialog. 以下は、このタイプのボタンの例です。Below is an example of this type of button.
{
  "elmType": "button",
  "txtContent": "Share this item",
  "customRowAction": {
    "action": "share"
  }
}
  • 削除:ボタンをクリックすると、削除確認ダイアログが開きます。delete: Clicking the button will open the delete confirmation dialog.
  • editProps:ボタンをクリックすると、編集モードでアイテムプロパティ ページが開きます。editProps: Clicking the button will open the item properties page in edit mode.
  • executeFlow:ボタンをクリックすると、 actionParams 属性内の ID によって指定された Flow が起動します。executeFlow: Clicking the button will launch the specified Flow, specified by ID inside the actionParams attribute. この例については、この文書のセクションである「 フローを起動するボタンを作成する 」をご参照ください。For an example of this, see the Create a button to launch a Flow section in this document.

txtContenttxtContent

で指定した要素のテキスト コンテンツを任意に指定するプロパティ。elmTypeAn optional property that specifies the text content of the element specified by elmType. このプロパティの値には、文字列 (特殊な文字列を含む) または式オブジェクトを指定できます。The value of this property can either be a string (including special strings) or an Expression object.

スタイルstyle

で指定した要素に適用するスタイル属性を任意に指定するプロパティ。elmTypeAn optional property that specifies style attributes to apply to the element specified by elmType. これは、CSS の名前と値に対応する名前と値のペアを持つオブジェクトです。This is an object with name-value pairs that correspond to CSS names and values. スタイル オブジェクトの各属性の値には文字列 (特殊な文字列を含む) または式オブジェクトを指定できます。The values of each property in the style object can either be a string (including special strings) or an Expression object. 次のスタイル属性を使用できます。The following style attributes are allowed.

'background-color'
'fill'
'background-image'
'border'
'border-bottom'
'border-bottom-color'
'border-bottom-style'
'border-bottom-width'
'border-color'
'border-left'
'border-left-color'
'border-left-style'
'border-left-width'
'border-right'
'border-right-color'
'border-right-style'
'border-right-width'
'border-style'
'border-top'
'border-top-color'
'border-top-style'
'border-top-width'
'border-width'
'outline'
'outline-color'
'outline-style'
'outline-width'
'border-bottom-left-radius'
'border-bottom-right-radius'
'border-radius'
'border-top-left-radius'
'border-top-right-radius'
'box-decoration-break'
'box-shadow'
'box-sizing'

'overflow-x'
'overflow-y'
'overflow-style'
'rotation'
'rotation-point'

'opacity'

'height'
'max-height'
'max-width'
'min-height'
'min-width'
'width'

'align-items'
'box-align'
'box-direction'
'box-flex'
'box-flex-group'
'box-lines'
'box-ordinal-group'
'box-orient'
'box-pack'

'font'
'font-family'
'font-size'
'font-style'
'font-variant'
'font-weight'
'font-size-adjust'
'font-stretch'

'grid-columns'
'grid-rows'

'margin'
'margin-bottom'
'margin-left'
'margin-right'
'margin-top'

'column-count'
'column-fill'
'column-gap'
'column-rule'
'column-rule-color'
'column-rule-style'
'column-rule-width'
'column-span'
'column-width'
'columns'

'padding'
'padding-bottom'
'padding-left'
'padding-right'
'padding-top'

'bottom'
'clear'
'clip'
'display'
'float'
'left'
'overflow'
'position' 
'right'
'top'
'visibility'
'z-index'

'border-collapse'
'border-spacing'
'caption-side'
'empty-cells'
'table-layout'

'color'
'direction'
'letter-spacing'
'line-height'
'text-align'
'text-decoration'
'text-indent'
'text-transform'
'unicode-bidi'
'vertical-align'
'white-space'
'word-spacing'
'hanging-punctuation'
'punctuation-trim'
'text-align-last'
'text-justify'
'text-outline'
'text-shadow'
'text-wrap'
'word-break'
'word-wrap'

次の例は、スタイル オブジェクトの値を示します。The following example shows the value of a style object. この例では、2 つのスタイルのプロパティ (paddingbackground-color) が適用されます。In this example, two style properties (padding and background-color) will be applied. の値は、ハード コーディングされた文字列値です。paddingThe padding value is a hard-coded string value. の値は、現在のフィールド (@currentField で指定) の値が 40 未満かどうかに応じて赤 (#ff0000) または緑 (#00ff00) のいずれかに評価される式です。background-colorThe background-color value is an Expression that is evaluated to either red (#ff0000) or green (#00ff00) depending on whether the value of the current field (specified by @currentField) is less than 40. 詳細については、式オブジェクトのセクションを参照してください。For more information, see the Expression object section.

{
   "padding": "4px",
   "background-color": {
      "operator": "?",
      "operands": [
         {
            "operator": "<",
            "operands": [
               "@currentField",
               40
            ]
         },
         "#ff0000",
         "#00ff00"
      ]
   }
}

属性attributes

で指定した要素に追加するさらなる属性を任意に指定するプロパティ。elmTypeAn optional property that specifies additional attributes to add to the element specified by elmType. これは、名前と値のペアを持つオブジェクトです。This is an object with name-value pairs. この属性の名前は、次のいずれかである必要があります。Attribute names must be one of the following:

  • hrefhref
  • relrel
  • srcsrc
  • クラスclass
  • ターゲットtarget
  • タイトルtitle
  • ロールrole
  • iconNameiconName
  • dd
  • ariaaria

その他の属性を指定すると、エラーが発生します。Any other attribute name will result in an error. 属性の値は式オブジェクトまたは文字列とすることができます。Attribute values can either be Expression objects or strings. 次の例では、2 つの属性 (targethref) を elmType により指定された要素に追加します。The following example adds two attributes (target and href) to the element specified by elmType. 属性は、文字列にハードコードされています。targetThe target attribute is hard-coded to a string. 属性は、実行時に http://finance.yahoo.com/quote/ + 現在のフィールド値 (@currentField) に評価される式です。hrefThe href attribute is an expression that will be evaluated at runtime to http://finance.yahoo.com/quote/ + the value of the current field (@currentField).

{
   "target": "_blank",
   "href": {
      "operator": "+",
      "operands": [
         "http://finance.yahoo.com/quote/",
         "@currentField"
      ]
   }
}

children

で指定した要素の子要素を任意に指定するプロパティ。elmTypeAn optional property that specifies child elements of the element specified by elmType. この値は elm オブジェクトの配列として指定します。The value is specified as an array of elm objects. 任意のレベルの入れ子にすることができます。There can be an arbitrary level of nesting. 要素に txtContent プロパティがある場合、子のプロパティは無視されます。If an element has the txtContent property, the child properties are ignored.

debugModedebugMode

デバッグで使用する、任意のプロパティです。An optional property that is meant for debugging. エラー メッセージを出力し、コンソールに警告を記録します。It outputs error messages and logs warnings to the console.

式オブジェクトExpression object

実行時に、現在のフィールド (または行) のコンテキストに基づき、実行時に評価できるよう、txtContent の値、スタイルのプロパティ、および属性のプロパティを式として表現します。Values for txtContent, style properties, and attribute properties can be expressed as expressions, so that they are evaluated at runtime based on the context of the current field (or row). 式オブジェクトは、別の式オブジェクトを入れ子にできます。Expression objects can be nested to contain other Expression objects.

次の例は、次の式を実行する式オブジェクトを示しています。The following example shows an Expression object that performs the following expression:

(@currentField > 40) ? '100%' : (((@currentField * 2.5).toString() + '%')

{
   "operator": "?",
   "operands": [
      {
         "operator": ">",
         "operands": [
            "@currentField",
            "40"
         ]
      },
      "100%",
      {
         "operator": "+",
         "operands": [
            {
               "operator": "toString()",
               "operands": [
                  {
                     "operator": "*",
                     "operands": [
                        "@currentField",
                        2.5
                     ]
                  }
               ]
            },
            "%"
         ]
      }
   ]
}

演算子Operators

演算子は、実行する演算の種類を指定します。Operators specify the type of operation to perform. 有効な値は次のとおりです。The following operators are valid values:

  • +
  • -
  • /
  • *
  • <
  • >
  • ==
  • !=!=
  • <=
  • >=
  • ||
  • &&
  • toString()toString()
  • 数()Number()
  • 日付()Date()
  • coscos
  • sinsin
  • ??
  • toLocaleString()toLocaleString()
  • toLocaleDateString()toLocaleDateString()
  • toLocaleTimeString()toLocaleTimeString()

二項演算子 - 2 つのオペランドを必要とする標準的な算術二項演算子を次に示します。Binary operators - The following are the standard arithmetic binary operators that expect two operands:

  • +
  • -
  • /
  • *
  • <
  • >
  • <=
  • >=

単項演算子 - 1 つのみのオペランドを必要とする標準的な算術単項演算子を次に示します。Unary operators - The following are standard unary operators that expect only one operand:

  • toString()toString()
  • 数()Number()
  • 日付()Date()
  • coscos
  • sinsin
  • toLocaleString()toLocaleString()
  • toLocaleDateString()toLocaleDateString()
  • toLocaleTimeString()toLocaleTimeString()

条件演算子-条件演算子は以下のとおりです。Conditional operator - The conditional operator is:

  • ??

?This is to achieve an expression equivalent to a ? b: c と等価な式を実装します。a の評価が true の場合、結果は b、それ以外の場合、結果は c になります。b : c, where if the expression a evaluates to true, then the result is b, else the result is c.

オペランドoperands

式のパラメーターやオペランド指定します。Specifies the parameters, or operands for an expression. これは、式のオブジェクトまたは基本的な値の配列です。This is an array of Expression objects or base values.

特別な文字列値Special string values

、スタイル、および属性の値には文字列または式オブジェクトを指定できます。txtContentThe values for txtContent, styles, and attributes can be either strings or Expression objects. リストと、ユーザーのコンテキスト内のフィールドから値を取得するためのいくつかの特別な文字列パターンがサポートされています。A few special string patterns for retrieving values from the fields in the list and the user's context are supported.

"@currentField""@currentField"

現在のフィールドの値として評価されます。Will evaluate to the value of the current field.

一部のフィールドの種類はオブジェクトとして表されます。Some field types are represented as objects. オブジェクトから値を出力するには、そのオブジェクト内の特定のプロパティを参照してください。To output a value from an object, refer to a particular property inside that object. たとえば、現在のフィールドが人物/グループのフィールドであれば、担当者の名前を取得するには @currentField.title を指定します。通常、これはリスト ビューに表示されます。For example, if the current field is a person/group field, specify @currentField.title to retrieve the person's name, which is normally displayed in list views. プロパティのリストを持つオブジェクトとして表されるフィールドの種類を次に示します。The following are the field types that are represented as objects with a list their properties.

注意

は既定で個人の名前を返します。@currentField.titleThe @currentField.title returns a person's name by default. ただし、個人フィールドの Show Field が調整されている場合は、title プロパティの値が変更されることがあります。However, if the person field's Show Field has been adjusted, it may change the value of the title property. たとえば、Department として構成された Show Field がある個人フィールドには、title プロパティの個人の部署があります。For example, a person field with the Show Field configured as Department will have the person's department for the title property.

人物フィールドPeople fields

人物フィールド オブジェクトには、次のプロパティ (例の値) があります。The people field object has the following properties (with example values):

{
   "id": "122",
   "title": "Kalya Tucker",
   "email": "kaylat@contoso.com",
   "sip": "kaylat@contoso.com",
   "picture": "https://contoso.sharepoint.com/kaylat_contoso_com_MThumb.jpg?t=63576928822"
}

日付/時刻フィールドDate/Time fields

日付/時刻型フィールドの値は、表示する形式に応じて異なる方法で取得できます。The value of Date/Time fields can be retrieved a few different ways, depending on the date format you'd like to display. 日付型の値を特定の形式に変換するために、次のメソッドがサポートされています。The following methods for converting date values to specific formats are supported:

  • toLocaleString() -日付型を完全に展開し、日付、時刻を含めて表示します。toLocaleString() - Displays a date type fully expanded with date and time.
  • toLocaleDateString() -日付型の日付だけを表示します。toLocaleDateString() - Displays a date type with just the date.
  • toLocaleTimeString() -日付型の時刻だけを表示します。toLocaleTimeString() - Displays a date type with just the time.

たとえば、次の JSON は現在のフィールド (日付フィールドであると仮定) を日付と時刻の文字列として表示します。For example, the following JSON will display the current field (assuming it's a date field) as a date and time string.

{
   "elmType": "div",
   "txtContent": {
        "operator": "toLocaleString()",
        "operands" : ["@currentField"]
    }
}

ルックアップ フィールドLookup fields

ルックアップ フィールド オブジェクトには、次のプロパティ (例の値) があります。The lookup field object has the following properties (with example values):

{
   "lookupId": "100",
   "lookupValue": "North America",
}


次の例では、現在のフィールドにルックアップ フィールドを活用する方法を示します。The following example shows how a lookup field might be used on a current field.

{
   "elmType": "a",
   "txtContent": "@currentField.lookupValue",
   "attributes": {
      "href": {
         "operator": "+",
         "operands": [
            "https://contoso.sharepoint.com/teams/Discovery/Lists/Regions/DispForm.aspx?ID=",
            "@currentField.lookupId"
         ]
      },
      "target": "_blank"
   }
}

ハイパーリンク フィールドHyperlink fields

ハイパーリンク フィールド オブジェクトには、次のプロパティがあります (値の例を示します)。The hyperlink field object has the following property (with example value):

{
   "desc": "SharePoint Patterns and Practices",
}


URL の値を参照するには、@currentField を使用します。To reference the URL value, use @currentField.

現在のフィールドでハイパーリンク フィールドを使用する例を次に示します。The following example shows how a hyperlink field might be used on a current field.

{
   "elmType": "a",
   "txtContent": "@currentField.desc",
   "attributes": {
      "href": "@currentField",
      "target": "_blank"
   }
}

"[$FieldName]""[$FieldName]"

列は行全体のコンテキスト内で書式設定されます。The column is formatted within the context of the entire row. このコンテキストを使用して、同じ行内の他のフィールドの値を参照することができます。大括弧で囲まれ、ドル記号で続行するフィールドの 社名 を特定します:[$InternalName]You can use this context to reference the values of other fields within the same row by specififying the internal name of the field surrounded by square brackets and preceeded by a dollar sign: [$InternalName]. たとえば、内部名が "MarchSales"のフィールドの値を取得するには、 [$MarchSales]を使用します。For example, to get the value of a field with an internal name of "MarchSales", use [$MarchSales].

フィールドの値がオブジェクトの場合は、オブジェクトのプロパティにアクセスできます。If the value of a field is an object, the object's properties can be accessed. たとえば、"SalesLead" という名前の個人フィールドの "Title" プロパティにアクセスするには、"[$SalesLead.title]" を使用します。For example, to access the "Title" property of a person field named "SalesLead", use "[$SalesLead.title]".

"@me""@me"

これは、現在のログイン済みのユーザーのメール アドレスとして評価されます。This will evaluate to the email address of the current logged in user.

このフィールドは現在のユーザーの電子メール アドレスを表示するために使用できますが、多くの場合、条件内で使用されます。This field can be used to display the current user's email address, but more likely it will be used within conditions. 次の例は、個人フィールドの色を設定します。現在ログインしているユーザーと等しい場合は赤、そうでない場合は青に設定します。The following is an example of setting the color for a person field to red when it is equal to the current logged in user and blue otherwise:

{
   "elmType": "div",
   "txtContent": "@currentField.title",
   "style": {
      "color": {
         "operator": "?",
         "operands": [
            {
               "operator": "==",
               "operands": [
                  "@me",
                  "@currentField.email"
               ]
            },
            "red",
            "blue"
         ]
      }
   }
}

"@now""@now"

これは、現在の日付と時刻として評価されます。This will evaluate to the current date and time.

"@ window.innerHeight""@window.innerHeight"

これは、リストがレンダリングされたときのブラウザ ウィンドウの高さ(ピクセル単位)に等しい数値で評価されます。This will evaluate to a number equal to the height of the browser window (in pixels) when the list was rendered.

"@ window.innerWidth""@window.innerWidth"

これは、リストがレンダリングされたときのブラウ ザウィンドウの幅(ピクセル単位)に等しい数値で評価されます。This will evaluate to a number equal to the width of the browser window (in pixels) when the list was rendered.

関連項目See also