Excel アドインでデータ型を使用する

アドインで文字列、数値、ブール値を超える必要がある場合は、Excel データ型を使用します。 データ型を使用すると、ワークシートの計算を引き続きサポートしながら、書式設定された日付、エンティティ カード、リンクされたレコード、Web イメージなどの拡張値を返します。

この記事では、データ型を強化し、メイン セル値型を使用するタイミングを示す valuesAsJson API について説明します。 機能の概要については、「 Excel アドインのデータ型の概要」を参照してください。

これらの概念をすぐに試すには、Excel でScript Labを開き、サンプル ライブラリのデータ型のサンプルを参照します。

valuesAsJson プロパティ

valuesAsJson プロパティは、Excel データ型の読み取りと書き込みのメイン API です。 NamedItem の単数valueAsJson プロパティは、1 つの名前付き項目に対して同じ目的を果たします。

valuesAsJson Range.values などのプロパティが展開されます。 values プロパティは、文字列、数値、ブール値、またはエラーの 4 つの基本的なセル値の型のいずれかのみを返します。 一方、 valuesAsJson は、これらの基本型と、書式設定された数値、エンティティ、Web イメージなどのデータ型に対して拡張された JSON 構造を返します。

次のオブジェクトは、 valuesAsJsonを公開します。

注:

一部のセル値は、ユーザーのロケールに基づいて変化します。 ローカライズされた値が必要な場合は、 valuesAsJsonLocal を使用します。 valuesAsJsonと同じオブジェクトで使用できます。

セルの値

valuesAsJson は CellValue 型のエイリアスを返します。 CellValue は、複数のセル値型の 和集合 です。

ほとんどのアドインで使用される種類は次のとおりです。

完全な CellValue 共用体には、次の型が含まれています。

CellValueは CellValueExtraProperties との交差部分です。 CellValueExtraProperties は、単独ではデータ型ではありません。 セル値の上書き方法を制御するのに役立つプロパティが追加されます。

JSON スキーマ

valuesAsJsonが返す各値は、そのセル値の種類用に設計された JSON メタデータ スキーマを使用します。 各型には独自のプロパティがありますが、すべてのスキーマは type、 basicType、 basicValueを共有します。

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

これらの共有フィールド以外に、各 *CellValue 型には独自のスキーマがあります。 たとえば、 WebImageCellValue には altText と attributionが含まれますが、 EntityCellValue には properties と textが含まれます。

次のセクションでは、書式設定された数値の一般的なパターン、追加のプロパティを持つ基本値、エンティティ値、リンクされたエンティティ、Web イメージ、および拡張エラーについて説明します。

書式設定された数値

基になる数値が重要な場合は DoubleCellValue を使用しますが、その値を持つ特定の表示形式を Excel に保持することもできます。 一般的なシナリオでは、シリアル日付値を返し、ワークシートに日付として表示します。

次の例は、書式設定された数値の完全な JSON スキーマを示しています。 この例では、 myDate は Excel UI で 1990 年 1 月 16 日 として表示されます。 データ型の最小互換性要件が満たされていない場合、計算では basicValueが使用されます。

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

DoubleCellValueの数値形式は既定の形式です。 ユーザーまたはアドインの別の部分が後でセルに書式設定を適用する場合、その適用された形式によって値の形式がオーバーライドされます。

書式設定された数値を試すには、Script Labを開き、データ型: 書式設定された数値のサンプルを実行します。

セルの基本的な値

基本的な Excel 値にプロパティを追加して、追加情報を関連付けることができます。 このパターンは、 文字列、 double、 ブール型 の基本型で動作します。 単純なセル値が、値を完全なエンティティに変えずに関連フィールドを運ぶ場合に使用します。

たとえば、請求書の合計には、 ドリンク、 食品、 税金、 チップなどの関連フィールドを含めることができます。

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

完全なチュートリアルについては、「 Excel の基本的なセル値にプロパティを追加する」を参照してください。

エンティティの値:

EntityCellValue にはテキスト、入れ子になったデータ型、配列を格納でき、Excel はそのデータをエンティティ カードに表示できます。

次の例は、請求書を表すエンティティ値の完全な JSON スキーマを示しています。 エンティティには、画像の表示テキストとプロパティ、期限、および状態値が含まれます。

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

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

重要

エンティティ値は、追加のセル値を格納する referencedValues 配列を定義できます。 これらの値は、エンティティの properties内からインデックスによって参照されます。

  • referencedValues配列は、セル値ツリーのルート レベルエンティティでのみサポートされます。
  • 入れ子になったエンティティは、別のエンティティ内のプロパティ値として使用されるエンティティであり、独自のreferencedValuesを定義することはできません。
  • 入れ子になったエンティティに referencedValues 配列が含まれている場合、JavaScript Excel API はアドインまたはスクリプト コードで GeneralException エラーをスローするか、カスタム関数が値を生成するときに #VALUE! エラーを表示します。

入れ子になったエンティティから値を参照するには、ルート エンティティの referencedValues 配列を指す ReferenceCellValue インデックスを使用します。

エンティティ データ型を調べるには、Script Labを開き、データ型: テーブル内のデータからエンティティ カードを作成するを実行します。 詳細な例については、「 データ型: 参照を含むエンティティ値」 および「 データ型: エンティティ値属性プロパティ」を参照してください。

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

LinkedEntityCellValue は、外部データ ソースに接続されているエンティティを表します。 大規模または頻繁に更新されるデータ セットのカードが必要で、すべての詳細を一度にブックに読み込みたくない場合は、リンクされたエンティティを使用します。

Excel UI で使用できる 株式と地域のデータ ドメイン は、リンクされたエンティティ セル値の例です。

リンクされたエンティティ セル値は、通常のエンティティ値よりも次の利点を提供します。

  • リンクされたエンティティ セルの値は入れ子にすることができ、ユーザーまたはワークシートが参照するまで、入れ子になったリンクされたエンティティは取得されません。 この動作は、ファイル サイズを小さくし、ブックのパフォーマンスを向上させるのに役立ちます。
  • Excel ではキャッシュが使用されるため、異なるセルが同じリンクされたエンティティ セル値を参照できます。 これは、ブックのパフォーマンスにも役立ちます。

実装の詳細については、「 Excel アドインでリンクされたエンティティ データ型を作成する」を参照してください。

Web 画像の値

WebImageCellValue は、アドインが範囲またはエンティティ値の一部としてイメージを格納する必要がある場合に使用します。 この型には、 address、 altText、 relatedImagesAddressなどのプロパティが含まれます。

basicType プロパティと basicValue プロパティは、データ型の最小互換性要件が満たされていない場合の Web イメージの計算の読み取り方法を定義します。 その場合、Web イメージは Excel UI で #VALUE! エラーとして表示されます。

次の例は、Web イメージの完全な JSON スキーマを示しています。

const myImage: Excel.WebImageCellValue = {
    type: Excel.CellValueType.webImage,
    address: "https://bit.ly/2YGOwtw",
    basicType: Excel.RangeValueType.error,
    basicValue: "#VALUE!"
};

Web イメージデータ型を試すには、Script Labを開き、データ型: Web イメージを実行します。

エラー サポートの改善

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

次のエラー オブジェクトでは、データ型によるサポートが拡張されています。

各エラー オブジェクトは、 errorSubTypeを介して列挙型にアクセスできます。 その列挙型は、特定のエラーに関する詳細を提供します。 たとえば、 BlockedErrorCellValueSubType は、 BlockedErrorCellValue が発生した理由に関する追加情報を提供します。

詳細については、Script Labを開き、データ型: エラー値の設定を実行します。

次の手順

関連項目

  • Last updated on