exceloffice-jscustom-functions-excel

Excel JS custom function does not return a matrix


I am trying to implement an Excel custom function (JavaScript) that returns a matrix of strings.

According to Create custom functions in Excel (Preview) the resultDimensionality has to be set to matrix in this case.

To keep it simple I've just copied the example from the documentation to return such an array of arrays:

function getstringmatrix () {
    return [["first","row"],["second","row"],["third","row"]];
}    
Excel.Script.CustomFunctions["MYFUNCTIONS"]["GETSTRINGMATRIX"] = {
    call: getstringmatrix,
    result: {
        resultType: Excel.CustomFunctionValueType.string,
        resultDimensionality: Excel.CustomFunctionDimensionality.matrix,
    },
    parameters: [ ],
    options:{ batch: false, stream: false }
};

When inserting the function =MYFUNCTIONS.GETSTRINGMATRIX() into an Excel cell this cell is filled with the string "first". But the expected second column and the other two rows are not filled at all!


Solution

  • The function you've created should be used in an Array Formula in Excel. Array formulas are an advanced type of formula that require the user to enter them in a specific way.

    1. First, select the range of cells where you want the formula output to go (in your case, select a 3-row, 2-column range)
    2. Then type the formula: =MYFUNCTIONS.GETSTRINGMATRIX()
    3. Then type Ctrl+Shift+Enter. That's the standard way of entering array formulas in Excel.

    There are native functions in Excel that also return arrays in this way, such as =LINEST().

    Of course, functions that take ranges as input don't require any special way to enter them - only functions that output arrays need the user to do something special.