数字格式

Facade API	可付费升级	需要 Univer 服务端	Univer on Node.js	Preset
✅	-	-	✅	UniverSheetsCorePreset

数字格式插件提供了对单元格中数字的格式化功能，包括数字的小数位数、千分位分隔符、货币符号等。

🚨

不支持 DBNum 语法

使用方法

UI 界面中，可以通过菜单栏设置单元格的数字格式。或者在单元格数据 ICellData 对象中设置 s.n.pattern 字段。


{
  v: 123456.789,
  s: {
    n: {
      pattern: '#,##0.00'
    }
  }
}

Facade API 0.5.2+

设置数字格式

具体参数请参考 https://support.microsoft.com/zh-cn/office/%E6%95%B0%E5%AD%97%E6%A0%BC%E5%BC%8F%E4%BB%A3%E7%A0%81-5026bbd6-04bc-48cd-bf33-80f18b4eae68


const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
 
// 将 A1 单元格的数字格式设置为 '#,##0.00'
const fRange = fWorksheet.getRange('A1');
fRange.setValue(1234.567).setNumberFormat('#,##0.00');
console.log(fRange.getDisplayValue()); // 1,234.57


const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
 
// 设置 A1:B2 范围的数字格式
const fRange = fWorksheet.getRange('A1:B2');
fRange.setValues([
  [1234.567, 0.1234],
  [45658, 0.9876]
]).setNumberFormats([
  ['#,##0.00', '0.00%'],
  ['yyyy-MM-DD', '']
]);
console.log(fRange.getDisplayValues()); // [['1,234.57', '12.34%'], ['2025-01-01', 0.9876]]

获取数字格式


const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
 
// 获取 A1:B2 范围左上角单元格的数字格式
const fRange = fWorksheet.getRange('A1:B2');
console.log(fRange.getNumberFormat());


const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
 
// 获取 A1:B2 范围的数字格式
const fRange = fWorksheet.getRange('A1:B2');
console.log(fRange.getNumberFormats());

设置数字格式的区域设置

使用 FWorkbook.setNumfmtLocal(local) 方法设置数字格式的区域设置。


const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const fRange = fWorksheet.getRange('A1');
fRange.setValue(1234.567).setNumberFormat('#,##0.00');
 
// 设置数字格式的区域设置为 en_US
fWorkbook.setNumfmtLocal('en_US');
console.log(fRange.getDisplayValue()); // 1,234.57
 
// 设置数字格式的区域设置为 de_DE
fWorkbook.setNumfmtLocal('de_DE');
console.log(fRange.getDisplayValue()); // 1.234,57

常见问题

关于单元格输入带有0开头或可转换为日期格式的数字时，不想被默认转换

可将单元格数字格式设置为文本格式，或在输入数字前加上单引号 '（强制文本）。

ICellData 对象中设置 s.n.pattern：


import { DEFAULT_TEXT_FORMAT_EXCEL } from '@univerjs/engine-numfmt';
 
{
  v: '012.0',
  s: {
    n: {
      pattern: DEFAULT_TEXT_FORMAT_EXCEL // 文本格式
    }
  }
}

univerAPI 设置单元格格式：


range.setNumberFormat(DEFAULT_TEXT_FORMAT_EXCEL);

禁用单元格文本格式警告和标记 0.6.7+

UniverSheetsNumfmtPlugin 插件提供了 disableTextFormatAlert 和 disableTextFormatMark 两个配置项，用于禁用单元格文本格式的警告和标记。


// presets 配置
const { univerAPI } = createUniver({
  // ...
  presets: [
    UniverSheetsCorePreset({
      disableTextFormatAlert: true,
      disableTextFormatMark: true
    }),
  ]
});


// Plugin 配置
univer.registerPlugin(UniverSheetsNumfmtPlugin, {
  disableTextFormatAlert: true,
  disableTextFormatMark: true,
});