Excel データ型の主要概念

この記事では、Excel JavaScript API を使用してデータ型を操作する方法について説明します。ここでは、データ型の開発の基本となる主要な概念を紹介します。

`valuesAsJson` プロパティ

valuesAsJson プロパティ (または NamedItem の単数valueAsJson) は、Excel でのデータ型の作成に不可欠です。このプロパティは、Range.values などの values プロパティの拡張です。 values と valuesAsJson プロパティはどちらもセル内の値にアクセスするに使用しますが、values プロパティは、文字列、数値、ブール値、またはエラーの 4 つの基本型の 1 つだけを返します (文字列として)。一方、valuesAsJson は、4 つの基本型に関する拡張情報を返します。このプロパティは、書式設定された数値、エンティティ、Web イメージなどのデータ型を返すことができます。

次のオブジェクトは、valuesAsJson プロパティを提供します。

注:

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

セルの値

このvaluesAsJson プロパティは、CellValue型エイリアスを返します。これは、次のデータ型の共用体です。

CellValue 型エイリアスは、CellValueExtraProperties オブジェクトも返します。これは、他の *CellValue 型との積集合部分です。データ型自体ではありません。 CellValueExtraProperties オブジェクトのプロパティは、セル値の上書きに関連する詳細を指定するために、すべてのデータ型で使用されます。

JSON スキーマ

valuesAsJson から返されたセルの値の型は、その型用に設計された JSON メタデータスキーマを使用します。各データ型に固有の追加のプロパティと共に、これらの JSON メタデータスキーマには、共通の type、basicType、basicValue プロパティがあります。

type はデータの CellValueType を定義します。 basicTypeは常に読み取り専用であり、データ型がサポートされていないか、正しく書式設定されていない場合にフォールバックとして使用されます。 basicValue は values プロパティで返される値と一致します。 basicValue は、データ型機能をサポートしていない以前のバージョンの Excel など、計算で互換性のないシナリオが発生した場合にフォールバックとして使用されます。 basicValueは、ArrayCellValue、EntityCellValue、LinkedEntityCellValue、およびWebImageCellValueのデータ型の読み取り専用です。

すべてのデータ型が共有する 3 つのフィールドに加えて、それぞれの *CellValue JSON メタデータスキーマには、その型に従って使用可能なプロパティがあります。たとえば、WebImageCellValue 型には altText と attributionプロパティが含まれますが、EntityCellValue 型には properties と text フィールドが用意されています。

次のセクションでは、書式設定された数値、エンティティ値、および Web 画像データ型の JSON コードサンプルを示します。

書式設定された数値

DoubleCellValue オブジェクトを使用すると、Excel アドインで値のnumberFormat プロパティを定義できます。割り当てられると、この数値形式は値を使用して計算を通過し、関数から返すことができます。

次の JSON コードサンプルは、フォーマットされた数値の完全なスキーマを示しています。コードサンプルの myDate書式設定された数値は、Excel UI で 1/16/1990 と表示されます。データ型機能の最小互換性要件が満たされていない場合、計算では、フォーマットされた数値の代わりに basicValue が使用されます。

// This is an example of the complete JSON of a formatted number value.
// In this case, the number is formatted as a date.
const myDate: Excel.DoubleCellValue = {
    type: Excel.CellValueType.double,
    basicValue: 32889.0,
    basicType: Excel.RangeValueType.double, // A read-only property. Used as a fallback in incompatible scenarios.
    numberFormat: "m/d/yyyy"
};

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

書式設定された数値の値の実験を開始するには、Script Labを開き、サンプル ライブラリの [データ型: 書式設定された数値] スニペットを確認します。

セルの基本的な値

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

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

詳細については、「基本セル値にプロパティを追加する」を参照してください。

エンティティの値:

エンティティ値は、オブジェクト指向プログラミングのオブジェクトと同様に、データ型のコンテナーです。エンティティは、エンティティ値のプロパティとして配列もサポートします。 EntityCellValue オブジェクトを使用すると、アドインは type、text、propertiesなどのプロパティを定義できます。 properties プロパティを使用すると、エンティティ値で追加のデータ型を定義および格納できます。

basicType プロパティと basicValue プロパティは、データ型を使用するための最小互換性要件が満たされていない場合に、計算がこのエンティティデータ型を読み取る方法を定義します。このシナリオでは、このエンティティデータ型は、Excel UI で #VALUE! エラーとして表示されます。

次の JSON コードサンプルは、テキスト、画像、日付、および追加のテキスト値を含むエンティティ値の完全なスキーマを示しています。

// This is an example of the complete JSON for an entity value.
// The entity contains text and properties which contain an image, a date, and another text value.
const myEntity: Excel.EntityCellValue = {
    type: Excel.CellValueType.entity,
    text: "A llama",
    properties: {
        image: myImage,
        "start date": myDate,
        "quote": {
            type: Excel.CellValueType.string,
            basicValue: "I love llamas."
        }
    }, 
    basicType: Excel.RangeValueType.error, // A read-only property. Used as a fallback in incompatible scenarios.
    basicValue: "#VALUE!" // A read-only property. Used as a fallback in incompatible scenarios.
};

エンティティデータ型を調べるには、まず Excel でScript Labに移動し、[データ型: サンプルライブラリのテーブルスニペット内のデータからエンティティカードを作成する] を開きます。データ型: 参照を含むエンティティ値とデータ型: エンティティ値属性プロパティスニペットは、エンティティ機能をより詳細に確認できます。

リンクされたエンティティセルの値

リンクされたエンティティセル値 (LinkedEntityCellValue オブジェクト) は、外部データソースからの統合データ型であり、エンティティカードとしてデータを表示できます。この機能を使用すると、すべてのデータをブックにダウンロードすることなく、大規模なデータセットを表すデータ型をスケーリングできます。 Excel UI で使用できる株式と地域のデータドメインには、リンクされたエンティティセル値が用意されています。

リンクされたエンティティセルの値は、外部データソースにリンクされます。通常のエンティティ値よりも次の利点があります。

リンクされたエンティティセルの値は入れ子にすることができ、入れ子になったリンクされたエンティティセルの値は、ユーザーまたはワークシートによって参照されるまで取得されません。これにより、ファイルサイズを減らし、ブックのパフォーマンスを向上させることができます。
Excel では、キャッシュを使用して、異なるセルが同じリンクされたエンティティセル値をシームレスに参照できるようにします。これにより、ブックのパフォーマンスも向上します。

詳細については、「リンクされたエンティティセル値を作成する」を参照してください。

Web 画像の値

WebImageCellValue オブジェクトは、エンティティの一部として、または範囲内の独立した値として画像を格納する機能を作成します。このオブジェクトには、address、altText、 relatedImagesAddress など、多くのプロパティが用意されています。

basicType および basicValue プロパティは、データ型機能を使用するための最小互換性要件が満たされていない場合に、計算が Web 画像データ型を読み取る方法を定義します。このシナリオでは、この Web イメージデータ型は、Excel UI で #VALUE! エラーとして表示されます。

次の JSON コードサンプルは、Web イメージの完全なスキーマを示しています。

// This is an example of the complete JSON for a web image.
const myImage: Excel.WebImageCellValue = {
    type: Excel.CellValueType.webImage,
    address: "https://bit.ly/2YGOwtw", 
    basicType: Excel.RangeValueType.error, // A read-only property. Used as a fallback in incompatible scenarios.
    basicValue: "#VALUE!" // A read-only property. Used as a fallback in incompatible scenarios.
};

Script Labを開き、サンプル ライブラリの [データ型: Web イメージ] スニペットを選択して、Web イメージのデータ型を試してください。

エラーサポートの改善

データ型 API は、既存の Excel UI エラーをオブジェクトとして公開します。これらのエラーにオブジェクトとしてアクセスできるようになったので、アドインは type、errorType、 errorSubType などのプロパティを定義または取得できます。

データ型を介してサポートが拡張されたすべてのエラーオブジェクトの一覧を次に示します。

各エラーオブジェクトは、errorSubType プロパティを使用して列挙型にアクセスでき、この列挙型にはエラーに関する追加のデータが含まれています。たとえば、BlockedErrorCellValue エラーオブジェクトは、BlockedErrorCellValueSubType 列挙型にアクセスできます。 BlockedErrorCellValueSubTypeenum は、エラーの原因に関する追加データを提供します。

データ型エラーオブジェクトの詳細については、「データ型: Script Labサンプルライブラリのエラー値の設定」スニペットを確認してください。

次の手順

エンティティデータ型は、エンティティ値データ型でカードを使用する記事を使用して、2 次元グリッドを超えて Excel アドインの可能性を拡張する方法について説明します。

OfficeDev/Office-Add-in-samples リポジトリの Excel サンプルのデータ型の作成と探索を使用して、ブック内のデータ型を作成および編集するアドインをビルドしてサイドローディングすることで、データ型をさらに詳しく実験します。

フィードバック

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

Last updated on 2025-05-13

次の方法で共有