基本セル値にプロパティを追加する

Excel の基本的なセル値にプロパティを追加して、追加情報を値に関連付けます。 エンティティ値と同様に、文字列、double、ブール型の基本型にプロパティを追加できます。 各プロパティは、キーと値のペアです。 次の例は、 Drinks、 Food、 Tax、 Tip という名前のフィールドが追加された請求書を表す数値 14.67 (double) を示しています。

ユーザーがカードデータ型の表示を選択すると、フィールドの値が表示されます。

セル値プロパティは、数式でも使用できます。

プロパティを使用してセル値を作成する

セル値を作成してプロパティを追加するには、 Range.valuesAsJson を使用してプロパティを割り当てます。 次のコード サンプルは、セル A1 に新しい数値を作成する方法を示しています。 レストランの請求書を説明する Food、 Drinks、および追加のプロパティが追加されます。 プロパティの JSON 説明を valuesAsJsonに割り当てます。

async function createNumberProperties() {
  await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const range = sheet.getRange("A1");
    range.valuesAsJson = [
      [
        {
          type: Excel.CellValueType.double,
          basicType: Excel.RangeValueType.double,
          basicValue: 14.67,
          properties: {
            Food: {
              type: Excel.CellValueType.string,
              basicType: Excel.RangeValueType.string,
              basicValue: "Sandwich and fries"
            },
            Drinks: {
              type: Excel.CellValueType.string,
              basicType: Excel.RangeValueType.string,
              basicValue: "Soda"
            },
            Tax: {
              type: Excel.CellValueType.double,
              basicType: Excel.RangeValueType.double,
              basicValue: 5.5
            },
            Tip: {
              type: Excel.CellValueType.double,
              basicType: Excel.RangeValueType.double,
              basicValue: 21
            }
          }
        }
      ]
    ];
    await context.sync();
  });
}

注:

一部のセル値は、ユーザーのロケールに基づいて変化します。 valuesAsJsonLocal プロパティはローカライズのサポートを提供し、valuesAsJson などのオブジェクトで利用可能です。

既存の値にプロパティを追加する

既存の値にプロパティを追加するには、最初に valuesAsJson を使用してセルから値を取得し、プロパティ JSON オブジェクトを追加します。 次の例は、セル A1 から数値を取得し、 Precision という名前のプロパティを割り当てる方法を示しています。 値の型をチェックして、文字列、double、またはブール型の基本型であることを確認する必要があることに注意してください。

async function addPropertyToNumber() {
    await Excel.run(async (context) => {
        let sheet = context.workbook.worksheets.getActiveWorksheet();
        let range = sheet.getRange("A1");
        range.load("valuesAsJson");
        await context.sync();
        let cellValue = range.valuesAsJson[0][0] as any;

        // Only apply this property to a double.
        if (cellValue.basicType === "Double") {
            cellValue.properties = {
                Precision: {
                    type: Excel.CellValueType.double,
                    basicValue: 4
                }
            };
            range.valuesAsJson = [[cellValue]];
            await context.sync();
        }
    });
}

エンティティ値との違い

文字列、ブール型、および二重基本型にプロパティを追加することは、エンティティ値にプロパティを追加するのと似ています。 ただし、違いがあります。

• 基本型にはエラー以外のフォールバックがあるため、計算を操作できます。 たとえば、A1 が 1、A2 が 2、A3 が 3 である数式 =SUM(A1:A3) を考えてみましょう。 A1 はプロパティを持つ double ですが、 A2 と A3 にはプロパティがありません。 合計は 6 の正しい結果を返します。 A1 がエンティティ値の場合、数式は機能しません。
• 計算で基本型の値を使用すると、プロパティは結果に除外されます。 前の 例の =SUM(A1:A3) では、A1 はプロパティを持つ double ですが、 6 の結果にはプロパティはありません。
• 基本型にアイコンが指定されていない場合、セルにはアイコンは表示されません。 ただし、エンティティ値でアイコンが指定されていない場合は、セル値に既定のアイコンが表示されます。

書式設定された数値

数値書式は、 CellValueType.double型の値に適用できます。 JSON スキーマの numberFormat プロパティを使用して、数値形式を指定します。 次のコード サンプルは、通貨として書式設定された数値の完全なスキーマを示しています。 コード サンプルの書式設定された数値は、Excel UI に $24.00 として表示されます。

// This is an example of the complete JSON of a formatted number value with a property.
// In this case, the number is formatted as currency.
async function createCurrencyValue() {
    await Excel.run(async (context) => {
        const sheet = context.workbook.worksheets.getActiveWorksheet();
        const range = sheet.getRange("A1");
        range.valuesAsJson = [
            [
                {
                    type: Excel.CellValueType.double,
                    basicType: Excel.RangeValueType.double,
                    basicValue: 24,
                    numberFormat: "$0.00",
                    properties: {
                        Name: {
                            type: Excel.CellValueType.string,
                            basicValue: "dollar"
                        }
                    }
                }
            ]
        ];
        await context.sync();
    });
}

数値の書式設定は、既定の形式と見なされます。 ユーザーまたは他のコードが、書式設定された数値を含むセルに書式設定を適用する場合、適用された形式は数値の形式をオーバーライドします。

カード レイアウト

プロパティを持つセル値には、ユーザーが表示できる既定のデータ型カードがあります。 既定のカード レイアウトではなく、使用するカスタム カード レイアウトを指定して、プロパティを表示するときのユーザー エクスペリエンスを向上させることができます。 これを行うには、 layouts プロパティを JSON の説明に追加します。

詳細については、「 セル値データ型でカードを使用する」を参照してください。

入れ子になったデータ型

追加のエンティティ値、 文字列、 doubles、 ブール値など、セル値にデータ型を入れ子にすることができます。 次のコード サンプルは、コンピューターのバッテリーの充電状態を表すセル値を作成する方法を示しています。 これには、電力消費と充電状態のコンピューターのプロパティを記述する入れ子になったエンティティ値が含まれています。 コンピューター エンティティの値には、コンピューターの電源プランを記述する入れ子になった文字列値も含まれています。

async function createNumberWithNestedEntity() {
    await Excel.run(async (context) => {
        const sheet = context.workbook.worksheets.getActiveWorksheet();
        const range = sheet.getRange("A1");
        range.valuesAsJson = [
            [
                {
                    type: Excel.CellValueType.double,
                    basicType: Excel.RangeValueType.double,
                    layouts: {
                        compact: {
                            icon: "Battery10"
                        }
                    },
                    basicValue: 0.7,
                    numberFormat: "00%",
                    properties: {
                        Computer: {
                            type: Excel.CellValueType.entity,
                            text: "Laptop",
                            properties: {
                                "Power Consumption": {
                                    type: Excel.CellValueType.double,
                                    basicType: Excel.RangeValueType.double,
                                    basicValue: 0.25,
                                    numberFormat: "00%",
                                    layouts: {
                                        compact: {
                                            icon: "Power"
                                        }
                                    },
                                    properties: {
                                        plan: {
                                            type: Excel.CellValueType.string,
                                            basicType: Excel.RangeValueType.string,
                                            basicValue: "Balanced"
                                        }
                                    }
                                },
                                Charging: {
                                    type: Excel.CellValueType.boolean,
                                    basicType: Excel.RangeValueType.boolean,
                                    basicValue: true
                                }
                            }
                        }
                    }
                }
            ]
        ];
        await context.sync();
    });
}

次の図は、入れ子になったノート PC エンティティの数値とデータ型カードを示しています。

互換性

データ型機能をサポートしていない以前のバージョンの Excel では、ユーザーに [使用できないデータ型] という警告が表示されます。 値は、数式やその他の Excel 機能と共に、期待どおりにセルと関数に引き続き表示されます。 値が書式設定された数値の場合、計算では、書式設定された数値の代わりに basicValue が使用されます。

Office 2016 より古いバージョンの Excel では、値はエラーなしでセルに表示され、基本値と区別できません。

関連項目

• Excel JavaScript API データ型の主要概念