次の方法で共有

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 コード サンプルを示します。

書式設定された数値

FormattedNumberCellValue オブジェクトを使用すると、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.FormattedNumberCellValue = {
    type: Excel.CellValueType.formattedNumber,
    basicValue: 32889.0,
    basicType: Excel.RangeValueType.double, // A read-only property. Used as a fallback in incompatible scenarios.
    numberFormat: "m/d/yyyy"
};

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

エンティティの値:

エンティティ値は、オブジェクト指向プログラミングのオブジェクトと同様に、データ型のコンテナーです。 エンティティは、エンティティ値のプロパティとして配列もサポートします。 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.
};

エンティティ値には、エンティティのカードを作成する layouts プロパティも用意されています。 カードは、Excel UI のモーダル ウィンドウとして表示され、セルに表示される内容を超えて、エンティティ値に含まれる追加情報を表示できます。 詳細については、「エンティティ値データ型でカードを使用する」を参照してください。

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

リンクされたエンティティ

リンクされたエンティティ値 または LinkedEntityCellValue オブジェクトは、エンティティ値の種類です。 これらのオブジェクトは外部サービスによって提供されるデータを統合し、このデータを通常のエンティティ値のように エンティティ カード として表示できます。 Excel UI で使用できる 株価と地理データ型 はリンクされたエンティティ値です。

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.
};

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

エラー サポートの改善

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

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

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

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

次の手順

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

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

関連項目