數字格式

數字格式是電子表格中用於控制數字顯示方式的功能。它允許使用者自訂數字的顯示格式，包括小數點位數、千位分隔符、百分比、貨幣符號等。透過設定數字格式，使用者可以使資料更易於閱讀和理解。

工具列的貨幣操作會根據 Univer 的 region 選擇貨幣符號和格式。未明確設定時，region 會跟隨 locale：

TypeScript

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

注意事項

不支援 DBNum 語法

數字格式示意

修改數值、格式或地區。格式只改變顯示，不改變儲存的數值。

儲存數值格式代碼格式地區

顯示結果

1,234.57

儲存數值: 1234.567

試試將 0.25 顯示為百分比，或將 45658 顯示為日期。

使用方法

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')// 設定數字格式的區域設定為 enfWorkbook.setNumfmtLocal('en')fRange.getDisplayValue() // 1,234.57// 設定數字格式的區域設定為 defWorkbook.setNumfmtLocal('de')fRange.getDisplayValue() // 1.234,57

禁用單元格文字格式警告和標記

UniverSheetsNumfmtPlugin 外掛提供了 disableTextFormatAlert 和 disableTextFormatMark 兩個配置項，用於禁用單元格文字格式的警告和標記。

依接入模式將以下選項合併到既有的初始化設定中，保留其他外掛、語言、主題與容器設定，請勿重複註冊同一外掛。

TypeScript

import { UniverSheetsNumfmtPlugin } from '@univerjs/sheets-numfmt'univer.registerPlugin(UniverSheetsNumfmtPlugin, {  disableTextFormatAlert: true,  disableTextFormatMark: true,})

TypeScript

import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import { createUniver } from '@univerjs/presets'const { univerAPI } = createUniver({  presets: [    UniverSheetsCorePreset({      disableTextFormatAlert: true,      disableTextFormatMark: true,    }),  ],})

本地化日期預設

日期格式面板依 Univer 目前的 locale 產生預設格式與預覽。既有的自訂日期格式仍可選取。切換選取範圍後，格式面板會重新整理，讓控制項反映目前儲存格的格式。

數字格式只改變顯示，不改變儲存的數值。例如將 0.25 設為 0% 會顯示 25%，公式仍使用 0.25 計算。 ↩

你覺得這篇文檔如何？