カスタム関数パラメーターオプション

[アーティクル]
07/07/2023

カスタム関数は、さまざまなパラメーターオプションで構成できます。

重要

Excel カスタム関数は、次のプラットフォームで使用できます。

Office on the web
Windows での Office
- Microsoft 365 サブスクリプション
- retail 永久 Office 2016 以降
- ボリュームライセンスの永続的なOffice 2021以降
Office on Mac

Excel カスタム関数は現在、次ではサポートされていません。

Office on iPad
Windows での Office 2019 以前のボリュームライセンスの永続的バージョン

オプションのパラメーター

ユーザーが Excel で関数を呼び出すと、角かっこで囲まれた省略可能なパラメーターが表示されます。次の例では、add 関数は必要に応じて 3 番目の数値を追加できます。この関数は Excel のように =CONTOSO.ADD(first, second, [third]) 表示されます。

JavaScript
TypeScript

/**
 * Calculates the sum of the specified numbers
 * @customfunction
 * @param {number} first First number.
 * @param {number} second Second number.
 * @param {number} [third] Third number to add. If omitted, third = 0.
 * @returns {number} The sum of the numbers.
 */
function add(first, second, third) {
  if (third === null) {
    third = 0;
  }
  return first + second + third;
}

/**
 * Calculates the sum of the specified numbers
 * @customfunction
 * @param first First number.
 * @param second Second number.
 * @param [third] Third number to add. If omitted, third = 0.
 * @returns The sum of the numbers.
 */
function add(first: number, second: number, third?: number): number {
  if (third === null) {
    third = 0;
  }
  return first + second + third;
}

注:

省略可能なパラメーターに値が指定されていない場合、Excel は値を null割り当てます。つまり、TypeScript の既定で初期化されたパラメーターは、想定どおりに機能しません。構文 function add(first:number, second:number, third=0):number は 0 に初期化 third されないため、使用しないでください。代わりに、前の例に示すように TypeScript 構文を使用します。

1 つ以上の省略可能なパラメーターを含む関数を定義する場合は、省略可能なパラメーターが null の場合の動作を指定します。次の例の zipCode と dayOfWeek は、どちらも getWeatherReport 関数の省略可能なパラメーターです。パラメーターが zipCode null の場合、既定値はに 98052設定されます。パラメーターが dayOfWeek null の場合、水曜日に設定されます。

JavaScript
TypeScript

/**
 * Gets a weather report for a specified zipCode and dayOfWeek
 * @customfunction
 * @param {number} [zipCode] Zip code. If omitted, zipCode = 98052.
 * @param {string} [dayOfWeek] Day of the week. If omitted, dayOfWeek = Wednesday.
 * @returns {string} Weather report for the day of the week in that zip code.
 */
function getWeatherReport(zipCode, dayOfWeek) {
  if (zipCode === null) {
    zipCode = 98052;
  }

  if (dayOfWeek === null) {
    dayOfWeek = "Wednesday";
  }

  // Get weather report for specified zipCode and dayOfWeek.
  // ...
}

/**
 * Gets a weather report for a specified zipCode and dayOfWeek
 * @customfunction
 * @param zipCode Zip code. If omitted, zipCode = 98052.
 * @param [dayOfWeek] Day of the week. If omitted, dayOfWeek = Wednesday.
 * @returns Weather report for the day of the week in that zip code.
 */
function getWeatherReport(zipCode?: number, dayOfWeek?: string): string {
  if (zipCode === null) {
    zipCode = 98052;
  }

  if (dayOfWeek === null) {
    dayOfWeek = "Wednesday";
  }

  // Get weather report for specified zipCode and dayOfWeek.
  // ...
}

範囲パラメーター

カスタム関数は、セルデータの範囲を入力パラメーターとして受け入れる場合があります。関数は、データの範囲を返すこともできます。 Excel は、セルデータの範囲を 2 次元配列として渡します。

例えば、関数が Excel に保存されている数値の範囲から 2 番目に大きい値を返すとします。次の関数は、パラメーター valuesを受け取り、JSDOC 構文 number[][] は、この関数の JSON メタデータでパラメーターの dimensionality プロパティをに matrix 設定します。

/**
 * Returns the second highest value in a matrixed range of values.
 * @customfunction
 * @param {number[][]} values Multiple ranges of values.
 */
function secondHighest(values) {
  let highest = values[0][0],
    secondHighest = values[0][0];
  for (let i = 0; i < values.length; i++) {
    for (let j = 0; j < values[i].length; j++) {
      if (values[i][j] >= highest) {
        secondHighest = highest;
        highest = values[i][j];
      } else if (values[i][j] >= secondHighest) {
        secondHighest = values[i][j];
      }
    }
  }
  return secondHighest;
}

繰り返しパラメーター

繰り返しパラメーターを使用すると、ユーザーは関数に対して一連の省略可能な引数を入力できます。関数が呼び出されると、パラメーターの配列に値が指定されます。パラメーター名が数値で終わる場合、各引数の数値は、のように ADD(number1, [number2], [number3],…)増分的に増加します。これは、組み込みの Excel 関数に使用される規則と一致します。

次の関数は、数値、セルアドレス、および範囲 (入力した場合) の合計を合計します。

/**
* The sum of all of the numbers.
* @customfunction
* @param operands A number (such as 1 or 3.1415), a cell address (such as A1 or $E$11), or a range of cell addresses (such as B3:F12)
*/

function ADD(operands: number[][][]): number {
  let total: number = 0;

  operands.forEach(range => {
    range.forEach(row => {
      row.forEach(num => {
        total += num;
      });
    });
  });

  return total;
}

この関数は Excel ブックに表示 =CONTOSO.ADD([operands], [operands]...) されます。

Excel ワークシートのセルに入力されている ADD カスタム関数

単一値パラメーターの繰り返し

繰り返し単一値パラメーターを使用すると、複数の単一の値を渡すことができます。たとえば、ユーザーは ADD(1,B2,3) と入力できます。次の例は、単一の値パラメーターを宣言する方法を示しています。

/**
 * @customfunction
 * @param {number[]} singleValue An array of numbers that are repeating parameters.
 */
function addSingleValue(singleValue) {
  let total = 0;
  singleValue.forEach(value => {
    total += value;
  })

  return total;
}

単一範囲パラメーター

1 つの範囲パラメーターは技術的には繰り返しパラメーターではありませんが、宣言が繰り返しパラメーターと非常によく似ているため、ここに含まれています。これは、1 つの範囲が Excel から渡される ADD(A2:B3) としてユーザーに表示されます。次の例は、1 つの範囲パラメーターを宣言する方法を示しています。

/**
 * @customfunction
 * @param {number[][]} singleRange
 */
function addSingleRange(singleRange) {
  let total = 0;
  singleRange.forEach(setOfSingleValues => {
    setOfSingleValues.forEach(value => {
      total += value;
    })
  })
  return total;
}

繰り返し範囲パラメーター

繰り返し範囲パラメーターを使用すると、複数の範囲または数値を渡すことができます。たとえば、ユーザーは ADD(5,B2,C3,8,E5:E8) と入力できます。繰り返し範囲は、通常、3 次元行列であるため、型 number[][][] で指定されます。サンプルについては、繰り返しパラメーターの一覧メインサンプルを参照してください。

繰り返しパラメーターの宣言

Typescript で、パラメーターが多次元であることを示します。たとえば、 ADD(values: number[]) 1 次元配列を示し、 ADD(values:number[][]) 2 次元配列を示します。

JavaScript では、1 次元配列、 @param <name> {number[][]} 2 次元配列など、より多くの次元に使用@param values {number[]}します。

手動で作成された JSON の場合は、パラメーターが JSON ファイルと同様"repeating": trueに指定されていることと、パラメーターがとして"dimensionality": matrixマークされていることをチェックします。

呼び出しパラメーター

明示的に宣言されていない場合でも、すべてのカスタム関数に最後の入力パラメーターとして引数が自動的に渡 invocation されます。このパラメーターはinvocation、Invocation オブジェクトに対応します。オブジェクトを Invocation 使用して、カスタム関数を呼び出したセルのアドレスなど、追加のコンテキストを取得できます。オブジェクトに Invocation アクセスするには、カスタム関数の最後のパラメーターとして宣言 invocation する必要があります。

注:

パラメーターは invocation 、Excel のユーザーのカスタム関数引数として表示されません。

次の例では、パラメーターを使用して、 invocation カスタム関数を呼び出したセルのアドレスを返す方法を示します。このサンプルでは、オブジェクトの address プロパティを Invocation 使用します。オブジェクトに Invocation アクセスするには、まず JSDoc でパラメーターとして宣言 CustomFunctions.Invocation します。次に、JSDoc でを宣言 @requiresAddress して、 address オブジェクトのプロパティに Invocation アクセスします。最後に、関数内でを取得し、プロパティを address 返します。

/**
 * Return the address of the cell that invoked the custom function. 
 * @customfunction
 * @param {number} first First parameter.
 * @param {number} second Second parameter.
 * @param {CustomFunctions.Invocation} invocation Invocation object. 
 * @requiresAddress 
 */
function getAddress(first, second, invocation) {
  const address = invocation.address;
  return address;
}

Excel では、オブジェクトの Invocation プロパティをaddress呼び出すカスタム関数は、関数を呼び出したセルの形式SheetName!RelativeCellAddressに従って絶対アドレスを返します。たとえば、入力パラメーターがセル F6 の Prices というシートにある場合、返されるパラメーターアドレス値はになります Prices!F6。

注:

空白または次のいずれかの文字がワークシート名に含まれている場合: ~ ' ! @ # $ % ^ & ( ) - _ = + { } | ; : , ' < . >は、返されたアドレス内のワークシート名が単一引用符で囲まれるので、形式は 'SheetName'!RelativeCellAddressです。たとえばです 'Latest Prices'!F6。単一引用符 (アポストロフィ) 文字 ' が名前に含まれている場合、返されるアドレスには 2 つのそのような文字が 1 行に含まれます。たとえば、 'Bob''s Region'!F6です。

パラメーターを invocation 使用して、Excel に情報を送信することもできます。詳細については、「ストリーミング関数を作成する」を参照してください。

パラメーターのアドレスを検出する

呼び出しパラメーターと組み合わせて、Invocation オブジェクトを使用して、カスタム関数入力パラメーターのアドレスを取得できます。呼び出されると、オブジェクトの InvocationparameterAddresses プロパティを使用すると、関数はすべての入力パラメーターのアドレスを返すことができます。

これは、入力データ型が異なる可能性があるシナリオで役立ちます。入力パラメーターのアドレスを使用して、入力値の数値形式をチェックできます。必要に応じて、入力の前に数値形式を調整できます。入力パラメーターのアドレスを使用して、入力値に後続の計算に関連する関連プロパティがあるかどうかを検出することもできます。

注:

Office アドインの Yeoman ジェネレーターではなく、手動で作成された JSON メタデータを使用してパラメーターアドレスを返す場合、オブジェクトはプロパティを requiresParameterAddresses にtrue設定しresult、optionsオブジェクトにはプロパティを dimensionality に設定するmatrix必要があります。

次のカスタム関数は、3 つの入力パラメーターを parameterAddresses 受け取り、各パラメーターのオブジェクトの Invocation プロパティを取得し、アドレスを返します。

/**
 * Return the addresses of three parameters. 
 * @customfunction
 * @param {string} firstParameter First parameter.
 * @param {string} secondParameter Second parameter.
 * @param {string} thirdParameter Third parameter.
 * @param {CustomFunctions.Invocation} invocation Invocation object. 
 * @returns {string[][]} The addresses of the parameters, as a 2-dimensional array. 
 * @requiresParameterAddresses
 */
function getParameterAddresses(firstParameter, secondParameter, thirdParameter, invocation) {
  const addresses = [
    [invocation.parameterAddresses[0]],
    [invocation.parameterAddresses[1]],
    [invocation.parameterAddresses[2]]
  ];
  return addresses;
}

プロパティを呼び出すカスタム関数を parameterAddresses 実行すると、関数を呼び出したセルの形式 SheetName!RelativeCellAddress に従ってパラメーターアドレスが返されます。たとえば、入力パラメーターがセル D8 の Costs というシートにある場合、返されるパラメーターアドレス値はになります Costs!D8。カスタム関数に複数のパラメーターがあり、複数のパラメーターアドレスが返された場合、返されたアドレスは、関数を呼び出したセルから垂直方向に降順で、複数のセル間でスピルします。

注:

次の手順

カスタム関数で揮発性の値を使用する方法について説明します。

次の方法で共有

カスタム関数パラメーターオプション

オプションのパラメーター

範囲パラメーター

繰り返しパラメーター

単一値パラメーターの繰り返し

単一範囲パラメーター

繰り返し範囲パラメーター

繰り返しパラメーターの宣言

呼び出しパラメーター

パラメーターのアドレスを検出する

次の手順

関連項目

その他のリソース

次の方法で共有

カスタム関数パラメーター オプション

オプションのパラメーター

範囲パラメーター

繰り返しパラメーター

単一値パラメーターの繰り返し

単一範囲パラメーター

繰り返し範囲パラメーター

繰り返しパラメーターの宣言

呼び出しパラメーター

パラメーターのアドレスを検出する

次の手順

関連項目

その他のリソース

カスタム関数パラメーターオプション