データ検証

データ検証は、セルにルールを設定して入力されたデータが特定の要件を満たすことを保証する機能です。入力エラーを防ぎ、データの正確性や一貫性を向上させます。

現在、次のデータ検証タイプがサポートされています:

  • Number
  • Integer
  • Text length
  • Date
  • Checkbox
  • Dropdown list (single/multiple selection)
  • Custom formula

プラグインモード

インストール

Shell
pnpm add @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-ui

使い方

TypeScript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import { UniverDataValidationPlugin } from '@univerjs/data-validation'import { UniverSheetsDataValidationPlugin } from '@univerjs/sheets-data-validation'import { UniverSheetsDataValidationUIPlugin } from '@univerjs/sheets-data-validation-ui'import SheetsDataValidationJaJP from '@univerjs/sheets-data-validation-ui/locale/ja-JP'import '@univerjs/sheets-data-validation-ui/lib/index.css'import '@univerjs/sheets-data-validation/facade'const univer = new Univer({  locale: LocaleType.JA_JP,  locales: {    [LocaleType.JA_JP]: mergeLocales(      SheetsDataValidationJaJP,     ),  },})univer.registerPlugin(UniverDataValidationPlugin)univer.registerPlugin(UniverSheetsDataValidationPlugin)univer.registerPlugin(UniverSheetsDataValidationUIPlugin)

プラグインと設定

TypeScript
univer.registerPlugin(UniverSheetsDataValidationUIPlugin, {  /**   * ドロップダウンメニューに編集ボタンを表示するかどうか   * @default true   */  showEditOnDropdown: true,  /**   * ドロップダウンメニューに検索ボックスを表示するかどうか   * @default true   */  showSearchOnDropdown: true,})

設定項目の詳細は IUniverSheetsDataValidationUIConfig を参照してください。

モバイル対応

まずモバイルエディターを設定します。このページのプラグインモードの初期化コードで、以下のデスクトップ登録を同じパッケージのモバイル版に置き換え、文書を開く前に完了してください。モデル、スタイル、言語ファイル、Facade は維持し、両方を同時に登録しないでください。

パッケージデスクトップの登録モバイルの登録
@univerjs/sheets-data-validation-uiUniverSheetsDataValidationUIPluginUniverSheetsDataValidationMobileUIPlugin

プリセットモード

インストール

Shell
pnpm add @univerjs/preset-sheets-data-validation

使い方

TypeScript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreJaJP from '@univerjs/preset-sheets-core/locales/ja-JP'import { UniverSheetsDataValidationPreset } from '@univerjs/preset-sheets-data-validation'import UniverPresetSheetsDataValidationJaJP from '@univerjs/preset-sheets-data-validation/locales/ja-JP'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-core/lib/index.css'import '@univerjs/preset-sheets-data-validation/lib/index.css'const { univerAPI } = createUniver({  locale: LocaleType.JA_JP,  locales: {    [LocaleType.JA_JP]: mergeLocales(      UniverPresetSheetsCoreJaJP,      UniverPresetSheetsDataValidationJaJP,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsDataValidationPreset(),   ],})

プリセットと設定

TypeScript
UniverSheetsDataValidationPreset({  /**   * ドロップダウンメニューに編集ボタンを表示するかどうか   * @default true   */  showEditOnDropdown: true,  /**   * ドロップダウンメニューに検索ボックスを表示するかどうか   * @default true   */  showSearchOnDropdown: true,})

設定項目の詳細は IUniverSheetsDataValidationPresetConfig を参照してください。

Facade API

Facade API の完全な型定義は、FacadeAPI で確認できます。

インポート

プラグインモード注意

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

TypeScript
import '@univerjs/sheets-data-validation/facade'

データ検証ルールの追加

univerAPI.newDataValidation() は、新しいデータ検証ビルダーを作成します。これは FDataValidationBuilder インスタンスを返し、チェーン呼び出しでデータ検証ルールを生成できます。

以下は FDataValidationBuilder のメソッドの一部です:

MethodDescription
buildデータ検証ルールを構築します
requireCheckbox入力が boolean 値であることを要求するルールを設定します(チェックボックスとして表示されます)
requireDateAfterデータ検証タイプを DATE に設定し、指定日より後の日付を要求するルールを設定します
requireDateBeforeデータ検証タイプを DATE に設定し、指定日より前の日付を要求するルールを設定します
requireDateBetweenデータ検証タイプを DATE に設定し、特定の期間内の日付を要求するルールを設定します
requireDateEqualToデータ検証タイプを DATE に設定し、指定日と等しいことを要求するルールを設定します
requireDateNotBetweenデータ検証タイプを DATE に設定し、特定の期間内でないことを要求するルールを設定します
requireDateOnOrAfterデータ検証タイプを DATE に設定し、指定日以降の日付を要求するルールを設定します
requireDateOnOrBeforeデータ検証タイプを DATE に設定し、指定日以前の日付を要求するルールを設定します
requireFormulaSatisfied与えられた数式が true と評価されることを要求するルールを設定します
requireNumberBetween指定した 2 つの数値の間、またはどちらかに等しい数値を要求するルールを設定します
requireNumberEqualTo指定した値と等しい数値を要求するルールを設定します
requireNumberGreaterThan指定した値より大きい数値を要求するルールを設定します
requireNumberGreaterThanOrEqualTo指定した値以上の数値を要求するルールを設定します
requireNumberLessThan指定した値より小さい数値を要求するルールを設定します
requireNumberLessThanOrEqualTo指定した値以下の数値を要求するルールを設定します
requireNumberNotBetween指定した 2 つの数値の間にない、かつどちらとも等しくない数値を要求するルールを設定します
requireNumberNotEqualTo指定した値と等しくない数値を要求するルールを設定します
requireValueInListユーザーが特定の値のリストから値を入力することを要求するルールを設定します。単一/複数選択、ドロップダウンの表示/非表示をサポートします
requireValueInRange指定した範囲内の値を入力することを要求するルールを設定します。単一/複数選択、ドロップダウンの表示/非表示をサポートします
setOptionsデータ検証ルールのオプションを設定します
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// 範囲 A1:B10 に対して 1 から 10 の数値を要求する新しいデータ検証ルールを作成します。const fRange = fWorksheet.getRange('A1:B10')const rule = univerAPI.newDataValidation()  .requireNumberBetween(1, 10)  .setOptions({    allowBlank: true,    showErrorMessage: true,    error: 'Please enter a number between 1 and 10',  })  .build()fRange.setDataValidation(rule)

範囲のデータ検証をクリア

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// 範囲 A1:B10 のデータ検証をクリアしますconst fRange = fWorksheet.getRange('A1:B10')fRange.setDataValidation(null)

範囲 / ワークシート のデータ検証の取得

返されるデータ検証ルールオブジェクトは FDataValidation インスタンスであり、ルールの条件やオプションなどを取得できます。

以下は FDataValidation のメソッドの一部です:

MethodDescription
copy現在のルールオブジェクトを使用して新しい FDataValidationBuilder インスタンスを作成します
getCriteriaTypeルールのデータ検証タイプを取得します
getCriteriaValues条件評価に使用される値を取得します
getHelpTextヘルプテキスト情報を取得します(ユーザーへの案内に使用されます)
getRangesデータ検証ルールが適用されている範囲を取得します
setCriteriaデータ検証ルールの条件を設定します
setOptionsデータ検証ルールのオプションを設定します
setRangesデータ検証ルールの対象範囲を設定します
deleteワークシートからデータ検証ルールを削除します
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// 現在のシートのすべてのデータ検証ルールを取得しますconst rulesOfSheet = fWorksheet.getDataValidations()// ルール ID でデータ検証ルールを取得しますconst ruleById = fWorksheet.getDataValidation(rulesOfSheet[0]?.rule?.uid)const fRange = fWorksheet.getRange('A1:B10')// 現在の範囲の最初のデータ検証ルールを取得しますconst ruleOfRange = fRange.getDataValidation()console.log('ruleOfRange:', ruleOfRange, ruleOfRange?.getCriteriaValues())// 現在の範囲のすべてのデータ検証ルールを取得しますconst rulesOfRange = fRange.getDataValidations()

データ検証の更新 / 削除

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// 範囲 A1:B10 に対して 20 と等しい値を要求する新しいデータ検証ルールを作成しますconst fRange = fWorksheet.getRange('A1:B10')const rule = univerAPI.newDataValidation()  .requireNumberEqualTo(20)  .build()fRange.setDataValidation(rule)const newRuleRange = fWorksheet.getRange('C1:D10')// 3 秒後にルールを更新しますsetTimeout(() => {  fRange.getDataValidation()    // 範囲を C1:D10 に変更します    .setRanges([newRuleRange])    // 条件を 1 から 10 の数値を要求するように変更します    .setCriteria(      univerAPI.Enum.DataValidationType.DECIMAL,      [univerAPI.Enum.DataValidationOperator.BETWEEN, '1', '10'],    )    // バリデーションエラー時に入力を止め、エラーメッセージを表示するようにオプションを変更します    .setOptions({      allowBlank: true,      showErrorMessage: true,      error: 'Please enter a valid value',      errorStyle: univerAPI.Enum.DataValidationErrorStyle.STOP,    })}, 3000)// 6 秒後にルールを削除しますsetTimeout(() => {  newRuleRange.getDataValidation().delete()}, 6000)

検証エラーの取得

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// 現在のワークブックのすべてのデータ検証エラーを取得しますconst workbookErrors = await fWorkbook.getAllDataValidationErrorAsync()console.log('workbookErrors:', workbookErrors)// 現在のシートのすべてのデータ検証エラーを取得しますconst worksheetErrors = await fWorksheet.getAllDataValidationErrorAsync()console.log('worksheetErrors:', worksheetErrors)// 現在の範囲のデータ検証エラーを取得しますconst fRange = fWorksheet.getRange('A1:B10')const rangeErrors = await fRange.getDataValidationErrorAsync()console.log('rangeErrors:', rangeErrors)

各エラーオブジェクトには以下のフィールドが含まれます:

  • sheetName:エラーが発生したワークシートの名前
  • row:エラーをトリガーしたセルの行インデックス
  • column:エラーをトリガーしたセルの列インデックス
  • ruleId:エラーをトリガーしたルールの ID
  • inputValue:エラーをトリガーした入力値
  • rule:ルールコンテンツのスナップショット

バリデータの状態を取得

バリデータの状態は DataValidationStatus の列挙値であり、以下を含みます:

  • valid:セルの値が検証を通過しました
  • invalid:セルの値が検証に失敗しました
  • validating:セルが検証中です
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// ワークブックのデータ検証バリデータの状態を取得しますfWorkbook.getValidatorStatus().then((status) => {  console.log('===statusOfWorkbook', status)})// シートのデータ検証バリデータの状態を取得しますfWorksheet.getValidatorStatusAsync().then((status) => {})// 範囲のデータ検証バリデータの状態を取得しますconst fRange = fWorksheet.getRange('A1:B10')fRange.getValidatorStatus().then((status) => {  console.log('===tatusOfRange', status)})

イベントリスナー

完全なイベント型定義は、Events を参照してください。

データ検証モジュールは、ルールの追加、更新、削除、バリデーション状態の変更を監視するための一連のイベントを提供します。すべてのイベントは univerAPI.addEvent() で購読できます。

ルール変更イベント

univerAPI.Event.SheetDataValidationChanged: ルール変更後にトリガーします

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetDataValidationChanged, (params) => {  const { origin, worksheet, workbook, changeType, oldRule, rule } = params})// イベントリスナーを削除するには `disposable.dispose()` を使用します

univerAPI.Event.BeforeSheetDataValidationAdd: ルール追加前にトリガーします

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationAdd, (params) => {  const { worksheet, workbook, rule } = params  // データ検証ルールの追加をキャンセルします  params.cancel = true})// イベントリスナーを削除するには `disposable.dispose()` を使用します

univerAPI.Event.BeforeSheetDataValidationDelete: ルール削除前にトリガーします

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationDelete, (params) => {  const { worksheet, workbook, ruleId, rule } = params  // データ検証ルールの削除をキャンセルします  params.cancel = true})// イベントリスナーを削除するには `disposable.dispose()` を使用します

univerAPI.Event.BeforeSheetDataValidationDeleteAll: すべてのルール削除前にトリガーします

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationDeleteAll, (params) => {  const { worksheet, workbook, rules } = params  // データ検証ルールの削除をキャンセルします  params.cancel = true})// イベントリスナーを削除するには `disposable.dispose()` を使用します

ルール更新イベント

univerAPI.Event.BeforeSheetDataValidationCriteriaUpdate: ルール条件更新前にトリガーします

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationCriteriaUpdate, (params) => {  const { worksheet, workbook, ruleId, rule, newCriteria } = params  // データ検証ルールの条件更新をキャンセルします  params.cancel = true})// イベントリスナーを削除するには `disposable.dispose()` を使用します

univerAPI.Event.BeforeSheetDataValidationRangeUpdate: ルール範囲更新前にトリガーします

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationRangeUpdate, (params) => {  const { worksheet, workbook, ruleId, rule, newRanges } = params  // データ検証ルールの範囲更新をキャンセルします  params.cancel = true})// イベントリスナーを削除するには `disposable.dispose()` を使用します

univerAPI.Event.BeforeSheetDataValidationOptionsUpdate: ルールオプション更新前にトリガーします

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationOptionsUpdate, (params) => {  const { worksheet, workbook, ruleId, rule, newOptions } = params  // データ検証ルールのオプション更新をキャンセルします  params.cancel = true})// イベントリスナーを削除するには `disposable.dispose()` を使用します

バリデーション状態イベント

univerAPI.Event.SheetDataValidatorStatusChanged: セルのバリデーション状態が変更されたときにトリガーします

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetDataValidatorStatusChanged, (params) => {  const { worksheet, workbook, row, column, status, rule } = params})// イベントリスナーを削除するには `disposable.dispose()` を使用します

各イベントは以下の共通パラメータを含みます:

  • workbook: 現在のワークブックインスタンス
  • worksheet: 現在のワークシートインスタンス

特有のパラメータ:

  • rule: 関連するデータ検証ルールオブジェクト
  • ruleId: データ検証ルールの一意の識別子
  • status: バリデーション状態(SheetDataValidatorStatusChanged イベントのみ)
  • newCriteria: 新しい検証条件(BeforeSheetDataValidationCriteriaUpdate イベントのみ)
  • newRanges: 新しい検証範囲(BeforeSheetDataValidationRangeUpdate イベントのみ)
  • newOptions: 新しい検証オプション(BeforeSheetDataValidationOptionsUpdate イベントのみ)

Before プレフィックスが付いたすべてのイベントコールバックは params.cancel = true を使用して対応する操作を防止できます。

エラースタイル

errorStyle オプションは、無効なデータが入力されたときの動作を制御します。これは DataValidationErrorStyle の列挙値であり、以下を含みます:

  • STOP:ユーザーが無効なデータを入力するのを防ぎます
  • WARNING:ユーザーが無効なデータを入力することを許可しますが、警告を表示します
  • INFO:ユーザーが無効なデータを入力することを許可しますが、情報メッセージを表示します
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B10')const rule = univerAPI.newDataValidation()  .requireNumberBetween(1, 10)  .setOptions({    allowBlank: true,    showErrorMessage: true,    error: '1 から 10 の間の数値を入力してください',    errorStyle: univerAPI.Enum.DataValidationErrorStyle.STOP,  })  .build()fRange.setDataValidation(rule)

変更リストのレンダーモード設定

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B10')fRange.getDataValidation()?.setOptions({  // support TEXT, ARROW, CUSTOM  // default is `CUSTOM`  renderMode: univerAPI.Enum.DataValidationRenderMode.TEXT,})

このガイドはいかがですか?

© 2026 DreamNum Co., Ltd.