# 数値書式

- Human documentation: [https://docs.univer.ai/ja-JP/guides/sheets/features/core/numfmt](https://docs.univer.ai/ja-JP/guides/sheets/features/core/numfmt)

- Agent Markdown: [https://docs.univer.ai/ja-JP/guides/sheets/features/core/numfmt.md](https://docs.univer.ai/ja-JP/guides/sheets/features/core/numfmt.md)

- Requested language: `ja-JP`

- Content language: `ja-JP`

- Documentation version: `1.1.0`

- Source: [sheets/features/core/numfmt.ja-JP.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/core/numfmt.ja-JP.mdx)

---

スプレッドシートの数値書式機能は、数値の表示方法を制御するためのものです。小数点以下桁数、桁区切り（千位区切り）、パーセンテージ、通貨記号など、数値の表示形式をカスタマイズできます。適切な数値書式を設定することで、データをより読みやすく、理解しやすくできます。

ツールバーの通貨操作は Univer の `region` に基づいて通貨記号と書式を選択します。明示的に設定しない場合、`region` は `locale` に従います。

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

> [!WARNING: 注意事項]
> **DBNum 構文** には対応していません。



## 使い方

UI ではメニューバーからセルの数値書式を設定できます。あるいはセルデータ [`ICellData`](https://docs.univer.ai/ja-JP/guides/sheets/model/cell-data.md) オブジェクト内の [`s.n.pattern`](https://docs.univer.ai/ja-JP/guides/sheets/model/cell-data.md#number-format)[^number-format-value] フィールドを設定します。

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

**既定では、先頭が 0 のテキストや、日付形式に変換可能な数値は自動的に対応する数値書式に変換されます。**

この自動変換を避けたい場合、以下のいずれかを行ってください:

1. セルの数値書式をテキスト形式に設定する。

```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)
```

2. 入力時に数値の前へシングルクォート（`'`）を付ける（[テキストとして扱う強制](https://docs.univer.ai/ja-JP/guides/sheets/model/cell-data.md#cell-type)）。

## Facade API

### インポート

> [!INFO: プラグインモード注意]
> Facade パッケージの手動 import が必要なのはプラグインモードのみです。プリセットモードには対応する Facade パッケージが内蔵されているため、追加の import は不要です。

```typescript
import '@univerjs/sheets-numfmt/facade'
```

### 数値書式の設定

詳細なパラメータ仕様: [https://support.microsoft.com/en-us/office/number-format-codes-5026bbd6-04bc-48cd-bf33-80f18b4eae68](https://support.microsoft.com/en-us/office/number-format-codes-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)`](https://docs.univer.ai/ja-JP/reference/facade/workbook.md#setnumfmtlocal) を使用して数値書式のロケールを設定できます。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1')
fRange.setValue(1234.567).setNumberFormat('#,##0.00')

// ja ロケールを適用
fWorkbook.setNumfmtLocal('ja')
fRange.getDisplayValue() // 1,234.57

// de ロケールを適用
fWorkbook.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,
    }),
  ],
})
```

[^number-format-value]: 数値書式は表示だけを変え、保存値は変えません。`0.25` に `0%` を適用すると `25%` と表示されますが、数式は `0.25` で計算します。

## 地域に合わせた日付プリセット

日付書式パネルは、Univer の現在の `locale` に応じた書式候補とプレビューを表示します。既存のカスタム日付書式も選択できます。選択範囲を変更すると、パネルも現在のセルの書式に更新されます。