Параметры параметров пользовательских функций

Статья
07/05/2023

Настраиваемые функции настраиваются с помощью множества различных параметров.

Важно!

Обратите внимание, что настраиваемые функции доступны в Excel на следующих платформах.

Office для Windows
- Подписка на Microsoft 365
- Розничный бессрочный Office 2016 и более поздних версий
Office для Mac
Office в Интернете

В настоящее время пользовательские функции Excel не поддерживаются в следующих приложениях:

Office для iPad
корпоративные бессрочные версии Office 2019 или более ранних версий

Необязательные параметры

Если пользователь вызывает функцию в Excel, необязательные параметры отображаются в квадратных скобках. В следующем примере функция add может при необходимости добавить третье число. Эта функция отображается как =CONTOSO.ADD(first, second, [third]) в Excel.

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 , так как он не инициализируется third до 0. Вместо этого используйте синтаксис TypeScript, как показано в предыдущем примере.

При определении функции, содержащей один или несколько необязательных параметров, укажите, что происходит, если необязательные параметры имеют значение 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 будет передавать диапазон данных ячейки в виде двумерного массива.

Например, предположим, что функция возвращает второе по величине значение из диапазона значений, хранящихся в Excel. Следующая функция принимает параметр values, а синтаксис number[][] JSDOC задает свойству matrix параметра dimensionality значение в метаданных JSON для этой функции.

/**
 * 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;
}

Эта функция отображается =CONTOSO.ADD([operands], [operands]...) в книге Excel.

Пользовательская функция ADD вводится в ячейку листа Excel

Повторяющийся параметр одного значения

Повторяющийся параметр одного значения позволяет передавать несколько отдельных значений. Например, пользователь может ввести 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;
}

Параметр одного диапазона

Один параметр диапазона технически не является повторяющимся параметром, но включается сюда, так как объявление очень похоже на повторяющиеся параметры. Пользователь будет отображаться как ADD(A2:B3), где один диапазон передается из Excel. В следующем примере показано, как объявить один параметр диапазона.

/**
 * @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). Повторяющиеся диапазоны обычно указываются с типом number[][][] , так как они являются трехмерными матрицами. Пример см. в main примере для повторяющихся параметров.

Объявление повторяющихся параметров

В Typescript укажите, что параметр является многомерным. Например, ADD(values: number[]) указывает одномерный массив, ADD(values:number[][]) двухмерный массив и т. д.

В JavaScript используется @param values {number[]} для одномерных массивов, @param <name> {number[][]} для двумерных массивов и т. д. для дополнительных измерений.

Для json, созданных вручную, убедитесь, что параметр указан как "repeating": true в файле JSON, а также проверка, что параметры помечены как "dimensionality": matrix.

Параметр вызова

Каждой пользовательской invocation функции автоматически передается аргумент в качестве последнего входного параметра, даже если он не объявлен явным образом. Этот invocation параметр соответствует объекту Invocation . Объект Invocation можно использовать для получения дополнительного контекста, например адреса ячейки, которая вызвала пользовательскую функцию. Чтобы получить доступ к объекту Invocation , необходимо объявить invocation в качестве последнего параметра в пользовательской функции.

Примечание.

Параметр invocation не отображается в качестве настраиваемого аргумента функции для пользователей в Excel.

В следующем примере показано, как использовать invocation параметр для возврата адреса ячейки, которая вызвала пользовательскую функцию. В этом примере используется свойство Invocationaddress объекта . Чтобы получить доступ к объекту Invocation , сначала объявите CustomFunctions.Invocation в качестве параметра в JSDoc. Затем объявите @requiresAddress в JSDoc для доступа к 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 пользовательская функция, вызывающая address свойство Invocation объекта, вернет абсолютный адрес в ячейке SheetName!RelativeCellAddress , вызвавающей функцию. Например, если входной параметр находится на листе с именем Цены в ячейке F6, возвращенное значение адреса параметра будет иметь значение Prices!F6.

Примечание.

Если пустое пробел или любой из следующих символов содержит имя листа: ~ ' ! @ # $ % ^ & ( ) - _ = + { } | ; : , ' < . >, имя листа в возвращенном адресе заключено в одинарные кавычки, поэтому формат имеет 'SheetName'!RelativeCellAddressформат ; например, 'Latest Prices'!F6. Если одинарный символ кавычек (апостроф) ' находится в имени, то возвращаемый адрес содержит два таких символа в строке; например, 'Bob''s Region'!F6.

Параметр invocation также можно использовать для отправки сведений в Excel. Дополнительные сведения см. в статье Создание функции потоковой передачи .

Определение адреса параметра

В сочетании с параметром вызова можно использовать объект Invocation для получения адреса входного параметра пользовательской функции. При вызове свойство InvocationparameterAddresses объекта позволяет функции возвращать адреса всех входных параметров.

Это полезно в сценариях, в которых типы входных данных могут отличаться. Адрес входного параметра можно использовать для проверка числового формата входного значения. Затем числовой формат можно изменить перед вводом, если это необходимо. Адрес входного параметра также можно использовать для определения того, имеет ли входное значение какие-либо связанные свойства, которые могут иметь отношение к последующим вычислениям.

Примечание.

Если вы работаете с созданными вручную метаданными JSON для возврата адресов параметров вместо генератора Yeoman для надстроек Office, options для объекта должно быть requiresParameterAddresses задано значение true, а result для объекта — dimensionality значение matrix.

Следующая пользовательская функция принимает три входных параметра, извлекает 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!D8. Если пользовательская функция имеет несколько параметров и возвращается несколько адресов параметров, возвращенные адреса будут распределяться по нескольким ячейкам, убывая по вертикали от ячейки, которая вызвала функцию.

Примечание.

Дальнейшие действия

Узнайте, как использовать переменные значения в пользовательских функциях.

Параметры параметров пользовательских функций

Необязательные параметры

Параметры диапазона

Повторяющиеся параметры

Повторяющийся параметр одного значения

Параметр одного диапазона

Параметр повторяющегося диапазона

Объявление повторяющихся параметров

Параметр вызова

Определение адреса параметра

Дальнейшие действия

См. также

Обратная связь

Дополнительные ресурсы