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.

Remarks

[ API set: ExcelApi 1.16 ]

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();
});