[Excel] (Custom functions) Add new cell value type JSON parameter (#4632)

* [Excel] (Custom functions) Add new cell value type JSON parameter

* [Excel] (Custom functions) Add new cell value type JSON parameter

* Add closing code ticks

* Add cell value type values

* Minor adjustments

* Clarify new cell value type rules

* Grammar changes

* Remove FormattedNumberCellValue from recommended

* Linter suggestion

Author: alison-mk

docs/excel/custom-functions-data-types-concepts.md

@@ -1,7 +1,7 @@
 ---
 title: Custom functions and data types
 description: Use Excel data types with your custom functions and Office Add-ins.
-ms.date: 10/17/2022
+ms.date: 06/15/2025
 ms.topic: overview
 ms.custom: scenarios:getting-started
 ms.localizationpriority: medium
@@ -57,7 +57,7 @@ The following code sample shows a custom function that takes an [EntityCellValue
 /**
  * Accept an entity value data type as a function input.
  * @customfunction
- * @param {any} value
+ * @param {Excel.EntityCellValue} value
  * @param {string} attribute
  * @returns {any} The text value of the entity.
  */

docs/excel/custom-functions-json-autogeneration.md

@@ -1,7 +1,7 @@
 ---
 title: Autogenerate JSON metadata for custom functions
 description: Use JSDoc tags to dynamically create your custom functions JSON metadata.
-ms.date: 07/11/2023
+ms.date: 06/15/2025
 ms.localizationpriority: medium
 ---
 
@@ -34,7 +34,7 @@ The plugin is [CustomFunctionsMetadataPlugin](https://github.com/OfficeDev/Offic
 
 ### Multiple custom function source files
 
-If, and only if, you have organized your custom functions into multiple source files, there are additional steps. 
+If, and only if, you have organized your custom functions into multiple source files, there are additional steps.
 
 1. In the webpack.config.js file, replace the string value of `input` with an array of string URLs that point to each of the files. The following is an example:
 
@@ -395,6 +395,22 @@ By specifying a parameter type, Excel will convert values into that type before
 
 A single value may be represented using one of the following types: `boolean`, `number`, `string`.
 
+### Cell value type
+
+Use the `type` subfield `cellValueType` to specify that a custom function accept and return Excel data types. The `type` value must be `any` to use the `cellValueType` subfield. Accepted `cellValueType` values are:
+
+- `Excel.CellValue`
+- `Excel.BooleanCellValue`
+- `Excel.DoubleCellValue`
+- `Excel.EntityCellValue`
+- `Excel.ErrorCellValue`
+- `Excel.LinkedEntityCellValue`
+- `Excel.LocalImageCellValue`
+- `Excel.StringCellValue`
+- `Excel.WebImageCellValue`
+
+For a code sample using the `Excel.EntityCellValue` type, see [Input an entity value](custom-functions-data-types-concepts.md#input-an-entity-value).
+
 ### Matrix type
 
 Use a two-dimensional array type to have the parameter or return value be a matrix of values. For example, the type `number[][]` indicates a matrix of numbers and `string[][]` indicates a matrix of strings.

docs/excel/custom-functions-json.md

@@ -1,7 +1,7 @@
 ---
 title: Manually create JSON metadata for custom functions in Excel
 description: Define JSON metadata for custom functions in Excel and associate your function ID and name properties.
-ms.date: 10/10/2022
+ms.date: 06/15/2025
 ms.localizationpriority: medium
 ---
 
@@ -142,6 +142,8 @@ The `allowCustomDataForDataTypeAny` property is a boolean data type. Setting thi
 > [!NOTE]
 > Unlike most of the other JSON metadata properties, `allowCustomDataForDataTypeAny` is a top-level property and contains no sub-properties. See the preceding [JSON metadata code sample](#json-metadata-example) for an example of how to format this property.
 
+If your custom function uses the `cellValueType` [parameter](#parameters), then setting the `allowCustomDataForDataTypeAny` isn't required to accept data types as parameters and return values.
+
 ### allowErrorForDataTypeAny
 
 The `allowErrorForDataTypeAny` property is a boolean data type. Setting the value to `true` allows a custom function to process errors as input values. All parameters with the type `any` or `any[][]` can accept errors as input values when `allowErrorForDataTypeAny` is set to `true`. The default `allowErrorForDataTypeAny` value is `false`.
@@ -185,9 +187,24 @@ The `parameters` property is an array of parameter objects. The following table
 |  `dimensionality`  |  string  |  No  |  Must be either `scalar` (a non-array value) or `matrix` (a 2-dimensional array).  |
 |  `name`  |  string  |  Yes  |  The name of the parameter. This name is displayed in Excel's IntelliSense.  |
 |  `type`  |  string  |  No  |  The data type of the parameter. Can be `boolean`, `number`, `string`, or `any`, which allows you to use of any of the previous three types. If this property is not specified, the data type defaults to `any`. |
+| `cellValueType` | string | No | A subfield of the `type` property. Specifies the Excel data types accepted by the custom function. Accepts the case-insensitive values `cellvalue`, `booleancellvalue`, `doublecellvalue`, `entitycellvalue`, `errorcellvalue`, `linkedentitycellvalue`, `localimagecellvalue`, `stringcellvalue`, and `webimagecellvalue`. <br/><br/>The `type` field must have the value `any` to use the `cellValueType` subfield. |
 |  `optional`  | boolean | No | If `true`, the parameter is optional. |
 |`repeating`| boolean | No | If `true`, parameters populate from a specified array. Note that functions all repeating parameters are considered optional parameters by definition.  |
 
+> [!TIP]
+> See the following code snippet for an example of how to format the `cellValueType` parameter in JSON metadata.
+>
+> ```json
+> "parameters": [
+>     {
+>         "name": "range",
+>         "description": "the input range",
+>         "type": "any",
+>             "cellValueType": "webimagecellvalue"
+>     }
+> ]
+> ```
+
 ### result
 
 The `result` object defines the type of information that is returned by the function. The following table lists the properties of the `result` object.