CustomFunctions.Invocation interface

The cell address where the function is being called, if requested, otherwise undefined.

To request the address for the function, in the metadata JSON file, the function options should specify: { "requiresAddress": true }

If the metadata JSON file is being generated from JSDoc comments, include the tag @requiresAddress.

address?: string;

Property Value

Remarks

[ API set: CustomFunctionsRuntime 1.1 ]

Examples

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

The name of this function.

functionName?: string;

Property Value

Remarks

[ API set: CustomFunctionsRuntime 1.1 ]

Indicates whether the function is invoked as part of the formula value preview. isInValuePreview is read-only and can't be set by a custom functions add-in. This value is true if the function is invoked to preview the formula value; otherwise it is false.

isInValuePreview?: string;

Property Value

Remarks

[ API set: CustomFunctionsRuntime BETA (PREVIEW ONLY) ]

Examples

/**
* Get the listing price for a house on the market for the given address.
* @customfunction
* @param address The address of the house.
* @param invocation Custom function handler.
* @returns The price of the house at the address.
*/
function getHousePrice(address: string, invocation: CustomFunctions.Invocation): number {
  // Check if this call is for formula value preview mode.
  if (invocation.isInValuePreview) { 
    // Avoid long-running expensive service calls. 
    // Return a usable but fake number.
    return 450000; 
  } else { 
    // Make the actual service calls in this block. 
    const price = callHouseServiceAPI(address);
    return price; 
  } 
}

The range addresses where the function parameters are located, if requested, otherwise undefined.

To request the parameter addresses for the function, in the metadata JSON file, the function options should specify: { "requiresParameterAddresses": true }

If the metadata JSON file is being generated from JSDoc comments, include the tag @requiresParameterAddresses.

parameterAddresses?: string[];

Property Value

Remarks

[ API set: CustomFunctionsRuntime 1.3 ]

Examples

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