Excel でカスタム関数でデータ型を使用する

[アーティクル]
03/10/2023

データ型は Excel JavaScript API を拡張して、元の 4 つのセル値タイプ (文字列、数値、ブール値、エラー) 以外のデータ型もサポートします。データ型には、Web イメージ、書式設定された数値、エンティティ、エンティティ内の配列のサポートが含まれます。

これらのデータ型はカスタム関数の能力を強化します。というのは、カスタム関数が入力値と出力値の両方としてデータ型を受け入れるからです。カスタム関数を使用してデータ型を生成することも、既存のデータ型を関数引数として計算に取り込んだりすることもできます。データ型の JSON スキーマが設定されると、このスキーマは計算全体で維持されます。

Excel アドインでのデータ型の使用の詳細については、「Excel アドインのデータ型の概要」を参照してください。

カスタム関数がデータ型を処理する方法

カスタム関数はデータ型を認識し、それらをパラメーター値として受け入れることができます。カスタム関数は、戻り値の新しいデータ型を作成できます。カスタム関数は、Excel JavaScript API と同じデータ型の JSON スキーマを使用し、この JSON スキーマは、カスタム関数が計算および評価するときに維持されます。

注:

カスタム関数は、データ型によって提供される拡張エラーオブジェクトの全機能をサポートしていません。カスタム関数はデータ型エラーオブジェクトを受け入れることができますが、計算全体を通じて維持されることはありません。現時点では、カスタム関数は CustomFunctions.Error オブジェクトに含まれるエラーのみをサポートしています。

カスタム関数のデータ型を有効にする

カスタム関数プロジェクトには、JSON メタデータファイルが含まれています。この JSON メタデータファイルは、データ型 API で使用される JSON スキーマとは異なります。データ型とカスタム関数の統合を使用するには、カスタム関数の JSON メタデータファイルを手動で更新して、プロパティ allowCustomDataForDataTypeAny を含める必要があります。このプロパティを true に設定します。

手動の JSON メタデータ作成プロセスの詳細については、「カスタム関数の JSON メタデータを手動で作成する」を参照してください。このプロパティの追加の詳細については、allowCustomDataForDataTypeAny を参照してください。

書式設定された数値を出力する

次のコードサンプルは、カスタム関数を使用して FormattedNumberCellValue データ型を作成する方法を示しています。この関数は、基本数値と書式設定を入力パラメーターとして受け取り、書式設定された数値データ型を出力として返します。

/**
 * Take a number as the input value and return a formatted number value as the output.
 * @customfunction
 * @param {number} value
 * @param {string} format (e.g. "0.00%")
 * @returns A formatted number value.
 */
function createFormattedNumber(value, format) {
    return {
        type: "FormattedNumber",
        basicValue: value,
        numberFormat: format
    }
}

エンティティ値の入力

次のコードサンプルは、EntityCellValue データ型を入力として受け取るカスタム関数を示しています。 attribute パラメータが text に設定されている場合、関数はエンティティ値の text プロパティを返します。それ以外の場合、関数はエンティティ値の basicValue プロパティを返します。

/**
 * Accept an entity value data type as a function input.
 * @customfunction
 * @param {any} value
 * @param {string} attribute
 * @returns {any} The text value of the entity.
 */
function getEntityAttribute(value, attribute) {
    if (value.type == "Entity") {
        if (attribute == "text") {
            return value.text;
        } else {
            return value.properties[attribute].basicValue;
        }
    } else {
        return JSON.stringify(value);
    }
}

次の手順

カスタム関数とデータ型を試すには、Excel にScript Labをインストールし、サンプル ライブラリのデータ型: カスタム関数スニペットを試します。

次の方法で共有