Edit

Share via

Excel.FormattedNumberCellValue interface

  • Reference
Package:
excel

Represents the value of a cell containing a number with a format string. Number format strings must conform to Excel guidelines. To learn more, see Review guidelines for customizing a number format. In this scenario, the format is applied to the value and not to the cell, so the value retains its format string throughout calculation.

Properties

basicType

Represents the value that would be returned by Range.valueTypes for a cell with this value.
basicValue

Represents the value that would be returned by Range.values for a cell with this value.
numberFormat

Returns the number format string that is used to display this value. When accessed through a valuesAsJson property, this number format string is in the en-US locale. When accessed through a valuesAsJsonLocal property, this number format is in the user's display locale. Number format strings must conform to Excel guidelines. To learn more, see Review guidelines for customizing a number format.
type

Represents the type of this cell value.

Property Details

basicType

Represents the value that would be returned by Range.valueTypes for a cell with this value.

basicType?: RangeValueType.double | "Double";

Property Value

double | "Double"

Remarks

[ API set: ExcelApi 1.16 ]

basicValue

Represents the value that would be returned by Range.values for a cell with this value.

basicValue: number;

Property Value

number

Remarks

[ API set: ExcelApi 1.16 ]

numberFormat

Returns the number format string that is used to display this value. When accessed through a valuesAsJson property, this number format string is in the en-US locale. When accessed through a valuesAsJsonLocal property, this number format is in the user's display locale. Number format strings must conform to Excel guidelines. To learn more, see Review guidelines for customizing a number format.

numberFormat: string;

Property Value

string

Remarks

[ API set: ExcelApi 1.16 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/20-data-types/data-types-formatted-number.yaml

// This function creates a formatted number data type,
// and sets the format of this data type as a currency.
await Excel.run(async (context) => {
  // Get the Sample worksheet and a range on that sheet.
  const sheet = context.workbook.worksheets.getItemOrNullObject("Sample");
  const currencyRange = sheet.getRange("A2");

  // Write a number formatted as currency to cell A2.
  currencyRange.valuesAsJson = [
    [
      {
        type: Excel.CellValueType.formattedNumber,
        basicValue: 12.34,
        numberFormat: "$* #,##0.00"
      }
    ]
  ];

  await context.sync();
});

type

Represents the type of this cell value.

type: CellValueType.formattedNumber | "FormattedNumber";

Property Value

formattedNumber | "FormattedNumber"

Remarks

[ API set: ExcelApi 1.16 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/20-data-types/data-types-formatted-number.yaml

// This function creates a formatted number data type,
// and sets the format of this data type as a date.
await Excel.run(async (context) => {
  // Get the Sample worksheet and a range on that sheet.
  const sheet = context.workbook.worksheets.getItemOrNullObject("Sample");
  const dateRange = sheet.getRange("A1");

  // Write a number formatted as a date to cell A1.
  dateRange.valuesAsJson = [
    [
      {
        type: Excel.CellValueType.formattedNumber,
        basicValue: 32889.0,
        numberFormat: "m/d/yyyy"
      }
    ]
  ];
  await context.sync();
});