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

  • [アーティクル]

データ型は 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をインストールし、サンプル ライブラリのデータ型: カスタム関数スニペットを試します。

関連項目