Добавление ссылочных методов в значения ячеек

Добавьте ссылочные методы к значениям ячеек, чтобы предоставить пользователям доступ к динамическим вычислениям на основе значения ячейки. EntityCellValue Типы и LinkedEntityCellValue поддерживают ссылочные методы. Например, добавьте метод к значению сущности продукта, которое преобразует его вес в различные единицы.

На следующем рисунке показан пример добавления ConvertWeight метода к значению сущности продукта, представляющего смесь блинчиков.

Формула Excel, показывающая =A1. ConvertWeight (унции).

DoubleCellValueТипы , BooleanCellValueи StringCellValue также поддерживают ссылочные методы. На следующем рисунке показан пример добавления ConvertToRomanNumeral метода к типу двойного значения.

Формула Excel, показывающая =A1. ConvertToRomanNumeral()

Ссылочные методы не отображаются в карта типа данных.

Данные карта для типа данных блинного набора, но ссылочные методы не перечислены.

Добавление ссылочного метода к значению сущности

Чтобы добавить ссылочный метод к значению сущности, определите Excel.JavaScriptCustomFunctionReferenceCellValue его в ФОРМАТЕ JSON с помощью типа . В следующем примере кода показано, как определить простой метод, возвращающий значение 27.

const referenceCustomFunctionGet27: Excel.JavaScriptCustomFunctionReferenceCellValue = { 
  type: Excel.CellValueType.function,
  functionType: Excel.FunctionCellValueType.javaScriptReference,
  namespace: "CONTOSO", 
  id: "GET27" 
}

Свойства описаны в следующей таблице.

Свойство	Описание
type	Указывает тип ссылки. Это свойство поддерживает `function` только и должно иметь значение `Excel.CellValueType.function`.
functionType	Указывает тип функции. Это свойство поддерживает только ссылочные функции JavaScript и должно иметь значение `Excel.FunctionCellValueType.javaScriptReference`.
пространство имен	Пространство имен, содержащее настраиваемую функцию. Это значение должно соответствовать пространству имен, заданному элементом customFunctions.namespace в унифицированном манифесте или элементом Namespace в манифесте только надстройки.
id	Имя настраиваемой функции для сопоставления с этим ссылочным методом. Имя — это версия пользовательского имени функции в верхнем регистре.

При создании значения сущности добавьте ссылочный метод в список свойств. В следующем примере кода показано, как создать простое значение сущности с именем Math и добавить в него ссылочный метод. Get27 — это имя метода, которое отображается для пользователей (например, A1.Get27()).

function makeMathEntity(value: number){
  const entity: Excel.EntityCellValue = {
    type: Excel.CellValueType.entity,
    text: "Math value",
    properties: {
      "value": {
        type: Excel.CellValueType.double,
        basicValue: value,
        numberFormat: "#"
      },
      Get27: referenceCustomFunctionGet27
    }
  };
  return entity;
}

В следующем примере кода показано, как создать экземпляр сущности Math и добавить его в выбранную ячейку.

// Add entity to selected cell.
async function addEntityToCell(){
  const entity: Excel.EntityCellValue = makeMathEntity(10);
  await Excel.run( async (context) => {
    const cell = context.workbook.getActiveCell();
    cell.valuesAsJson = [[entity]];
    await context.sync();
  });
}

Наконец, реализуйте ссылочный метод с помощью пользовательской функции. В следующем примере кода показано, как реализовать пользовательскую функцию.

/**
 * Returns the value 27.
 * @customfunction
 * @excludeFromAutoComplete
 * @returns {number} 27
 */
function get27() {
  return 27;
}

В предыдущем примере кода тег гарантирует, @excludeFromAutoComplete что пользователь не будет отображать пользовательскую функцию в пользовательском интерфейсе Excel, когда пользователь вводит ее в поле поиска. Однако пользователь по-прежнему может вызывать пользовательскую функцию отдельно от значения сущности, если он вводит ее непосредственно в ячейку.

При выполнении кода создается значение сущности Math , как показано на следующем рисунке. Метод отображается в формуле Автозавершение, когда пользователь ссылается на значение сущности из формулы.

Введите

Добавление аргументов

Если для эталонного метода требуются аргументы, добавьте их в настраиваемую функцию. В следующем примере кода показано, как добавить аргумент с именем x в метод с именем addValue. Метод добавляет его к значению x путем вызова пользовательской функции с именем addValue.

/**
 * Adds a value to 1.
 * @customfunction
 * @excludeFromAutoComplete
 * @param {number} x The value to add to 1.
 * @return {number[][]}  Sum of x and 1.
 */
function addValue(x): number[][] {  
  return [[x+1]];
}

Ссылка на значение сущности как на вызывающий объект

Распространенный сценарий заключается в том, что для выполнения вычислений методы должны ссылаться на свойства самого значения сущности. Например, это более полезно, если addValue метод добавляет значение аргумента к самому значению сущности. Укажите, что значение сущности передается в качестве первого аргумента, применив @capturesCallingObject тег к пользовательской функции, как показано в следующем примере кода.

/**
 * Adds x to the calling object.
 * @customfunction
 * @excludeFromAutoComplete
 * @capturesCallingObject
 * @param {any} math The math object (calling object).
 * @param {number} x The value to add.
 * @return {number[][]}  Sum.
 */
function addValue(math, x): number[][] {  
  const result: number = math.properties["value"].basicValue + x;
  return [[result]];
}

Вы можете использовать любое имя аргумента, соответствующее правилам синтаксиса Excel в разделе Имена в формулах. Так как это математическая сущность, аргумент вызывающего объекта называется math. Имя аргумента можно использовать в вычислении.

Обратите внимание на приведенный ниже пример кода.

Тег @excludeFromAutoComplete гарантирует, что пользователь не будет отображать пользовательскую функцию в пользовательском интерфейсе Excel, когда пользователь вводит ее в поле поиска. Однако пользователь по-прежнему может вызывать пользовательскую функцию отдельно от значения сущности, если он вводит ее непосредственно в ячейку.
Вызывающий объект всегда передается в качестве первого аргумента и должен иметь тип any. В этом случае он называется math и используется для получения свойства value из math объекта .
Он возвращает двойной массив чисел.
Когда пользователь взаимодействует с ссылочным методом в Excel, он не видит вызывающий объект в качестве аргумента.

Пример. Вычисление налога с продаж продукта

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

/**
 * Calculates the price when a sales tax rate is applied.
 * @customfunction
 * @excludeFromAutoComplete
 * @capturesCallingObject
 * @param {any} product The product entity value (calling object).
 * @param {number} taxRate The tax rate (0.11 = 11%).
 * @return {number[][]}  Product unit price with tax rate applied.
 */
function applySalesTax(product, taxRate): number[][] {
  const unitPrice: number = product.properties["Unit Price"].basicValue;
  const result: number = unitPrice * taxRate + unitPrice;
  return [[result]];
}

В следующем примере кода показано, как указать ссылочный метод и включить id объект пользовательской applySalesTax функции.

const referenceCustomFunctionCalculateSalesTax: Excel.JavaScriptCustomFunctionReferenceCellValue = { 
  type: Excel.CellValueType.function,
  functionType: Excel.FunctionCellValueType.javaScriptReference,
  namespace: "CONTOSO", 
  id: "APPLYSALESTAX" 
}

В следующем коде показано, как добавить ссылочный метод к значению сущности product .

function makeProductEntity(productID: number, productName: string, price: number) {
  const entity: Excel.EntityCellValue = {
    type: Excel.CellValueType.entity,
    text: productName,
    properties: {
      "Product ID": {
        type: Excel.CellValueType.string,
        basicValue: productID.toString() || ""
      },
      "Product Name": {
        type: Excel.CellValueType.string,
        basicValue: productName || ""
      },
      "Unit Price": {
        type: Excel.CellValueType.formattedNumber,
        basicValue: price,
        numberFormat: "$* #,##0.00"
      },
      applySalesTax: referenceCustomFunctionCalculateSalesTax
    },
  };
  return entity;
}

Исключение пользовательских функций из пользовательского интерфейса Excel

@excludeFromAutoComplete Используйте тег в теге JSDoc пользовательских функций, используемых ссылочными методами, чтобы указать, что функция будет исключена из автозаполнения формулы и построителя формул. Это помогает предотвратить случайное использование пользовательской функции отдельно от значения сущности.

Примечание.

Если функция введена в сетку вручную правильно, она по-прежнему выполняется.

Важно!

Функция не может содержать одновременно теги @excludeFromAutoComplete и @linkedEntityLoadService.

Тег @excludeFromAutoComplete обрабатывается во время сборки для создания файла functions.json пакетом Custom-Functions-Metadata . Этот пакет автоматически добавляется в процесс сборки, если вы создаете надстройку с генератором Yeoman для надстроек Office и выбираете шаблон пользовательских функций. Если вы не используете пакет Custom-Functions-Metadata , необходимо вручную добавить excludeFromAutoComplete свойство в файл functions.json .

В следующем примере кода показано, как вручную определить пользовательскую APPLYSALESTAX функцию с помощью JSON в файле functions.json . Для свойства excludeFromAutoComplete задано значение true.

{
    "description": "Calculates the price when a sales tax rate is applied.",
    "id": "APPLYSALESTAX",
    "name": "APPLYSALESTAX",
    "options": {
        "excludeFromAutoComplete": true,
        "capturesCallingObject": true
    },
    "parameters": [
        {
            "description": "The product entity value (calling object).",
            "name": "product",
            "type": "any"
        },
        {
            "description": "The tax rate (0.11 = 11%).",
            "name": "taxRate",
            "type": "number"
        }
    ],
    "result": {
        "dimensionality": "matrix",
        "type": "number"
    }
},

Дополнительные сведения см . в статье Создание метаданных JSON вручную для пользовательских функций.

Добавление функции в базовый тип значения

Чтобы добавить функции к базовым типам значений Boolean, doubleи , используйте тот же процесс, что и stringдля значений сущностей. В следующем примере кода показано, как создать двойное базовое значение с помощью пользовательской функции с именем addValue. Функция добавляет значение x к базовому значению.

/**
 * Adds the value x to the number value.
 * @customfunction
 * @capturesCallingObject
 * @param {any} numberValue The number value (calling object).
 * @param {number} x The value to add.
 * @return {number[][]}  Sum of the number value and x.
 */
export function addValue(numberValue: any, x: number): number[][] {
  return [[x+numberValue.basicValue]];
}

В следующем примере кода показано, как определить addValue пользовательскую функцию из предыдущего примера в ФОРМАТЕ JSON, а затем сослаться на нее с помощью метода с именем createSimpleNumber.

const referenceCustomFunctionAddValue: Excel.JavaScriptCustomFunctionReferenceCellValue = { 
  type: Excel.CellValueType.function,
  functionType: Excel.FunctionCellValueType.javaScriptReference,
  namespace: "CONTOSO", 
  id: "ADDVALUE" 
} 

async function createSimpleNumber() {
  await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const range = sheet.getRange("A1");
    range.valuesAsJson = [
      [
        {
          type: Excel.CellValueType.double,
          basicType: Excel.RangeValueType.double,
          basicValue: 6.0,
          properties: {
            addValue: referenceCustomFunctionAddValue
          }
        }
      ]
    ];
    await context.sync();
  });
}

аргументов Optional;

В следующем примере кода показано, как создать ссылочный метод, который принимает необязательные аргументы. Ссылочный метод называется generateRandomRange и создает диапазон случайных значений.

const referenceCustomFunctionOptional: Excel.JavaScriptCustomFunctionReferenceCellValue = { 
  type: Excel.CellValueType.function,
  functionType: Excel.FunctionCellValueType.javaScriptReference,
  namespace: "CONTOSO", 
  id: "GENERATERANDOMRANGE" 
}

function makeProductEntity(productID: number, productName: string, price: number) {
  const entity: Excel.EntityCellValue = {
    type: Excel.CellValueType.entity,
    text: productName,
    properties: {
      "Product ID": {...},
      "Product Name": {...},
      "Unit Price": {...},
      generateRandomRange: referenceCustomFunctionOptional
    },
  };
  return entity;
}

В следующем примере кода показана реализация ссылочного метода в виде пользовательской функции с именем generateRandomRange. Он возвращает динамический массив случайных значений, соответствующих числу и columns заданнымrows. min Аргументы и max являются необязательными, и если они не заданы, по умолчанию будут использоваться и 110.

/**
 * Generates a dynamic array of random numbers.
 * @customfunction
 * @excludeFromAutoComplete
 * @param {number} rows Number of rows to generate.
 * @param {number} columns Number of columns to generate.
 * @param {number} [min] Lowest number that can be generated. Default is 1.
 * @param {number} [max] Highest number that can be generated. Default is 10.
 * @returns {number[][]} A dynamic array of random numbers.
 */
function generateRandomRange(rows, columns, min, max) {
  // Set defaults for any missing optional arguments.
  if (min === undefined) min = 1;
  if (max === undefined) max = 10;

  let numbers = new Array(rows);
  for (let r = 0; r < rows; r++) {
    numbers[r] = new Array(columns);
    for (let c = 0; c < columns; c++) {
      numbers[r][c] = Math.round(Math.random() * (max - min) ) + min;
    }
  }
  return numbers;
}

Когда пользователь вводит настраиваемую функцию в Excel, автозаполнение отображает свойства функции и указывает необязательные аргументы, окружив их в квадратных скобках ([]). На следующем рисунке показан пример ввода необязательных параметров с помощью ссылочного generateRandomRange метода.

Снимок экрана: ввод метода generateRandomRange в Excel.

Несколько параметров

Ссылочные методы поддерживают несколько параметров, аналогично тому, как функция Excel SUM поддерживает несколько параметров. В следующем примере кода показано, как создать эталонную функцию, которая объединяет ноль или несколько названий продуктов, передаваемых в массиве products. Функция отображается пользователю как concatProductNames([products], ...).

/** 
 * @customfunction 
 * @excludeFromAutoComplete 
 * @description Concatenate the names of given products, joined by " | " 
 * @param {any[]} products - The products to concatenate.
 * @returns A string of concatenated product names. 
 */ 
function concatProductNames(products: any[]): string { 
  return products.map((product) => product.properties["Product Name"].basicValue).join(" | "); 
}

В следующем примере кода показано, как создать сущность с помощью ссылочного concatProductNames метода.

const referenceCustomFunctionMultiple: Excel.JavaScriptCustomFunctionReferenceCellValue = { 
  type: Excel.CellValueType.function,
  functionType: Excel.FunctionCellValueType.javaScriptReference,
  namespace: "CONTOSO", 
  id: "CONCATPRODUCTNAMES" 
} 

function makeProductEntity(productID: number, productName: string, price: number) {
  const entity: Excel.EntityCellValue = {
    type: Excel.CellValueType.entity,
    text: productName,
    properties: {
      "Product ID": {...},
      "Product Name": {...},
      "Unit Price": {...},
      concatProductNames: referenceCustomFunctionMultiple,
    },
  };
  return entity;
}

На следующем рисунке показан пример ввода нескольких параметров с помощью ссылочного concatProductNames метода.

Снимок экрана: ввод метода concatProductNames в Excel с передачей A1 и A2, содержащих значение сущности велосипеда и одноциклового продукта.

Несколько параметров с диапазонами

Для поддержки передачи диапазонов в ссылочный метод, например B1:B3, используйте многомерный массив. В следующем примере кода показано, как создать эталонную функцию, которая суммирует ноль или больше параметров, которые могут включать диапазоны.

/** 
 * @customfunction 
 * @excludeFromAutoComplete 
 * @description Calculate the sum of arbitrary parameters. 
 * @param {number[][][]} operands - The operands to sum. 
 * @returns The sum of all operands. 
 */ 
function sumAll(operands: number[][][]): number { 
  let total: number = 0; 
 
  operands.forEach(range => { 
    range.forEach(row => { 
      row.forEach(num => { 
        total += num; 
      }); 
    }); 
  }); 
 
  return total; 
}

В следующем примере кода показано, как создать сущность с помощью ссылочного sumAll метода.

const referenceCustomFunctionRange: Excel.JavaScriptCustomFunctionReferenceCellValue = { 
  type: Excel.CellValueType.function,
  functionType: Excel.FunctionCellValueType.javaScriptReference,
  namespace: "CONTOSO", 
  id: "SUMALL" 
} 

function makeProductEntity(productID: number, productName: string, price: number) {
  const entity: Excel.EntityCellValue = {
    type: Excel.CellValueType.entity,
    text: productName,
    properties: {
      "Product ID": {...},
      "Product Name": {...},
      "Unit Price": {...},
      sumAll: referenceCustomFunctionRange
    },
  };
  return entity;
}

На следующем рисунке показан пример ввода нескольких параметров, включая параметр диапазона, с помощью ссылочного sumAll метода.

Снимок экрана: ввод метода sumAll в Excel с дополнительным диапазоном B1:B2.

Сведения о поддержке

Ссылочные методы поддерживаются во всех типах пользовательских функций, таких как переменные и потоковые функции. Поддерживаются все типы возвращаемых пользовательских функций — матричные, скалярные и ошибки.

Важно!

Связанная сущность не может иметь настраиваемую функцию, которая объединяет как ссылочный метод, так и поставщик данных. При разработке связанных сущностей эти типы пользовательских функций следует разделять.

См. также

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

Была ли эта страница полезна?

Last updated on 2025-11-04