数字格式

数字格式是电子表格中用于控制数字显示方式的功能。它允许用户自定义数字的显示格式，包括小数点位数、千位分隔符、百分比、货币符号等。通过设置数字格式，用户可以使数据更易于阅读和理解。

工具栏的货币操作会根据 Univer 的 region 选择货币符号和格式。未显式配置时，region 会跟随 locale：

TypeScript

const univer = new Univer({  locale: LocaleType.ZH_CN,  region: LocaleType.DE_DE,})

注意事项

不支持 DBNum 语法

使用方法

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

TypeScript

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

默认情况下，以 0 开头的文本以及可被转换为日期格式的数字会被自动转换成对应的数字格式。

如果不希望这种自动转换，可以选择以下方式进行设置：

将单元格数字格式设置为文本格式。

TypeScript

import { DEFAULT_TEXT_FORMAT_EXCEL } from '@univerjs/core'const data = {  v: '012.0',  s: {    n: {      pattern: DEFAULT_TEXT_FORMAT_EXCEL, // 文本格式    },  },}

或使用 Facade API 设置单元格格式：

TypeScript

fRange.setNumberFormat(DEFAULT_TEXT_FORMAT_EXCEL)

在输入数字前加上单引号 '（强制文本）

Facade API

引入

插件模式提示

仅插件模式需要手动引入 Facade 包。预设模式已内置对应的 Facade 包，无需额外导入。

TypeScript

import '@univerjs/sheets-numfmt/facade'

设置数字格式

具体参数请参考 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

TypeScript

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

TypeScript

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', ''],])fRange.getDisplayValues() // [['1,234.57', '12.34%'], ['2025-01-01', 0.9876]]

获取数字格式

TypeScript

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

TypeScript

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

设置数字格式的区域设置

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

TypeScript

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

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

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

TypeScript

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

TypeScript

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

你觉得这篇文档如何？