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

セルの元の string、 double、または Boolean 値を保持し、さらに詳細を公開する場合は、基本セル値のプロパティを使用します。たとえば、レストランの請求書は、計算の数値を維持しながら、データ型のカードと数式にFood、Drinks、Tax、Tipも表示できます。

この記事では、プロパティを使用して基本的な値を作成し、既存の値を更新し、数値を書式設定し、入れ子になったデータ型を追加する方法について説明します。

Excel データ型を初めて使用する場合は、「 Excel アドインのデータ型の概要」から始めます。
「 Excel アドインでデータ型を使用する」の JSON スキーマを確認します。
外部ソースからデータを取得し、個別に更新する必要がある場合は、[ Excel アドインでリンクされたエンティティデータ型を作成する] を使用します。

次の例は、Drinks、Food、Tax、および Tip という名前のフィールドが追加された数値14.67を示しています。

選択したセル値に表示されるドリンク、食品、税金、チップの各フィールドのスクリーンショット。

ユーザーがカードデータ型を開くと、追加のフィールドが表示されます。

データ型カード飲料、食品、税金、チップのプロパティの値を示します。

プロパティを持つ基本的な値は、ドット表記を使用して数式で参照することもできます。

ユーザーが「a1.」と入力し、Excel にドリンク、食べ物、税金、チップのオプションが含まれたメニューを表示します。

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

Range.valuesAsJsonを使用して値を作成し、そのプロパティを 1 つの割り当てで定義します。次の例では、 A1 に数値を書き込み、請求書の詳細をプロパティとして追加します。

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を使用して値を読み取ります。次に、プロパティを追加する前に、値が string、 double、または Boolean であることを確認します。

次の例では、 A1の数値を取得し、既存のプロパティを保持し、 Precision プロパティを追加します。

async function addPropertyToNumber() {
  await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const range = sheet.getRange("A1");

    range.load("valuesAsJson");
    await context.sync();

    const cellValue = range.valuesAsJson[0][0] as any;

    // Only apply this property to a double.
    if (cellValue.basicType === Excel.RangeValueType.double) {
      cellValue.properties = {
        ...(cellValue.properties ?? {}),
        Precision: {
          type: Excel.CellValueType.double,
          basicValue: 4
        }
      };

      range.valuesAsJson = [[cellValue]];
      await context.sync();
    }
  });
}

基本値またはエンティティ値を選択する

string、Boolean、double基本型にプロパティを追加することは、エンティティ値にプロパティを追加するのと似ていますが、動作はいくつかの重要な点で異なります。

数式が引き続きセルを基になる値として扱う必要がある場合は、プロパティで基本値を使用します。基本型にはエラーフォールバックがないため、計算は常に続行できます。たとえば、A1がプロパティを持つ double であり、A2とA3が標準の数値である場合、=SUM(A1:A3)は引き続き6を返します。
計算で基本値を使用する場合、結果には基になる値のみが含まれます。結果では、ソースプロパティは保持されません。
基本値のアイコンを指定しない場合、セルにはアイコンが表示されません。アイコンが指定されていない場合、エンティティ値には既定のアイコンが表示されます。

書式設定された数値

numberFormat プロパティを使用して、CellValueType.double型の値に数値の書式設定を適用できます。次の例では、通貨値を作成し、説明的なプロパティを追加します。

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: "Price"
            }
          }
        }
      ]
    ];

    await context.sync();
  });
}

この数値形式は、値の既定の形式です。ユーザーまたは他のコードがセルに別の形式を適用すると、その形式によって値の numberFormatがオーバーライドされます。

カードレイアウトをカスタマイズする

プロパティを持つ基本値では、既定のデータ型カードが使用されます。より便利な方法でプロパティを表示するには、json の説明に layouts プロパティを追加し、カスタムカードレイアウトを定義します。

レイアウトオプションと例については、「セル値データ型でカードを使用する」を参照してください。

入れ子になったデータ型

エンティティ値、追加の string、 double、 Boolean 値など、他のデータ型を基本値内に入れ子にすることができます。次の例では、コンピューターのバッテリー残量の値を A1 に書き込み、コンピューターとその電源設定を記述する入れ子になったエンティティを追加します。

重要

エンティティ値を入れ子にする場合、 referencedValues 配列はルートレベルのエンティティでのみサポートされます。入れ子になったエンティティは、独自の referencedValuesを定義しないでください。入れ子になったエンティティに referencedValuesが含まれている場合、Excel はセル値を拒否し、そのセルの #VALUE! エラーを返します。入れ子になったエンティティから追加の値を参照するには、ルートエンティティのreferencedValues配列を指す ReferenceCellValue インデックスを使用します。詳細については、「エンティティ値」を参照してください。

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 のセル値は 70% のバッテリ充電を示し、データ型カード充電と電力消費のプロパティ値を持つ入れ子になったノート PC エンティティを示しています。

互換性

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

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

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-06-17