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

2025-02-14

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

重要

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

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

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

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

注:

Microsoft 365 の統合マニフェストでは、現在、カスタム関数プロジェクトはサポートされていません。カスタム関数プロジェクトにはアドインのみのマニフェストを使用する必要があります。詳細については、「 Office アドインマニフェスト」を参照してください。

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

ユーザーが 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;
}

注:

省略可能なパラメーターに値が指定されていない場合は、値 nullが割り当てられます。つまり、TypeScript の既定で初期化されたパラメーターは、想定どおりに機能しません。 third を 0 に初期化しないため、構文function add(first:number, second:number, third=0):numberを使用しないでください。代わりに、前の例に示すように 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[][] パラメーターの dimensionality プロパティを、この関数の JSON メタデータに 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 values {number[]} 、2 次元配列に @param <name> {number[][]} など、より多くの次元を使用します。

手動で作成された JSON の場合は、パラメーターが "repeating"`: true` in your JSON file, as well as check that your parameters are marked as "次元": matrixとして指定されていることを確認します。

呼び出しパラメーター

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

注:

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

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

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

注:

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

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

/**
 * 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されます。カスタム関数に複数のパラメーターがあり、複数のパラメーターアドレスが返された場合、返されたアドレスは、関数を呼び出したセルから垂直方向に降順で、複数のセル間でスピルします。

注:

次の手順

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