データ検証
データ検証は、セルにルールを設定して入力されたデータが特定の要件を満たすことを保証する機能です。入力エラーを防ぎ、データの正確性や一貫性を向上させます。
現在、次のデータ検証タイプがサポートされています:
- Number
- Integer
- Text length
- Date
- Checkbox
- Dropdown list (single/multiple selection)
- Custom formula
プラグインモード
インストール
pnpm add @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-uinpm install @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-uiyarn add @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-uibun add @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-ui使い方
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)プラグインと設定
univer.registerPlugin(UniverSheetsDataValidationUIPlugin, { /** * ドロップダウンメニューに編集ボタンを表示するかどうか * @default true */ showEditOnDropdown: true, /** * ドロップダウンメニューに検索ボックスを表示するかどうか * @default true */ showSearchOnDropdown: true,})設定項目の詳細は IUniverSheetsDataValidationUIConfig を参照してください。
モバイル対応
まずモバイルエディターを設定します。このページのプラグインモードの初期化コードで、以下のデスクトップ登録を同じパッケージのモバイル版に置き換え、文書を開く前に完了してください。モデル、スタイル、言語ファイル、Facade は維持し、両方を同時に登録しないでください。
| パッケージ | デスクトップの登録 | モバイルの登録 |
|---|---|---|
@univerjs/sheets-data-validation-ui | UniverSheetsDataValidationUIPlugin | UniverSheetsDataValidationMobileUIPlugin |
プリセットモード
インストール
pnpm add @univerjs/preset-sheets-data-validationnpm install @univerjs/preset-sheets-data-validationyarn add @univerjs/preset-sheets-data-validationbun add @univerjs/preset-sheets-data-validation使い方
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(), ],})プリセットと設定
UniverSheetsDataValidationPreset({ /** * ドロップダウンメニューに編集ボタンを表示するかどうか * @default true */ showEditOnDropdown: true, /** * ドロップダウンメニューに検索ボックスを表示するかどうか * @default true */ showSearchOnDropdown: true,})設定項目の詳細は IUniverSheetsDataValidationPresetConfig を参照してください。
Facade API
Facade API の完全な型定義は、FacadeAPI で確認できます。
インポート
プラグインモード注意
Facade パッケージの手動 import が必要なのはプラグインモードのみです。プリセットモードには対応する Facade パッケージが内蔵されているため、追加の import は不要です。
import '@univerjs/sheets-data-validation/facade'データ検証ルールの追加
univerAPI.newDataValidation() は、新しいデータ検証ビルダーを作成します。これは FDataValidationBuilder インスタンスを返し、チェーン呼び出しでデータ検証ルールを生成できます。
以下は FDataValidationBuilder のメソッドの一部です:
| Method | Description |
|---|---|
| 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 | データ検証ルールのオプションを設定します |
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)範囲のデータ検証をクリア
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// 範囲 A1:B10 のデータ検証をクリアしますconst fRange = fWorksheet.getRange('A1:B10')fRange.setDataValidation(null)範囲 / ワークシート のデータ検証の取得
返されるデータ検証ルールオブジェクトは FDataValidation インスタンスであり、ルールの条件やオプションなどを取得できます。
以下は FDataValidation のメソッドの一部です:
| Method | Description |
|---|---|
| copy | 現在のルールオブジェクトを使用して新しい FDataValidationBuilder インスタンスを作成します |
| getCriteriaType | ルールのデータ検証タイプを取得します |
| getCriteriaValues | 条件評価に使用される値を取得します |
| getHelpText | ヘルプテキスト情報を取得します(ユーザーへの案内に使用されます) |
| getRanges | データ検証ルールが適用されている範囲を取得します |
| setCriteria | データ検証ルールの条件を設定します |
| setOptions | データ検証ルールのオプションを設定します |
| setRanges | データ検証ルールの対象範囲を設定します |
| delete | ワークシートからデータ検証ルールを削除します |
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()データ検証の更新 / 削除
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)検証エラーの取得
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:エラーをトリガーしたルールの IDinputValue:エラーをトリガーした入力値rule:ルールコンテンツのスナップショット
バリデータの状態を取得
バリデータの状態は DataValidationStatus の列挙値であり、以下を含みます:
valid:セルの値が検証を通過しましたinvalid:セルの値が検証に失敗しましたvalidating:セルが検証中です
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: ルール変更後にトリガーします
const disposable = univerAPI.addEvent(univerAPI.Event.SheetDataValidationChanged, (params) => { const { origin, worksheet, workbook, changeType, oldRule, rule } = params})// イベントリスナーを削除するには `disposable.dispose()` を使用しますuniverAPI.Event.BeforeSheetDataValidationAdd: ルール追加前にトリガーします
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationAdd, (params) => { const { worksheet, workbook, rule } = params // データ検証ルールの追加をキャンセルします params.cancel = true})// イベントリスナーを削除するには `disposable.dispose()` を使用しますuniverAPI.Event.BeforeSheetDataValidationDelete: ルール削除前にトリガーします
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationDelete, (params) => { const { worksheet, workbook, ruleId, rule } = params // データ検証ルールの削除をキャンセルします params.cancel = true})// イベントリスナーを削除するには `disposable.dispose()` を使用しますuniverAPI.Event.BeforeSheetDataValidationDeleteAll: すべてのルール削除前にトリガーします
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationDeleteAll, (params) => { const { worksheet, workbook, rules } = params // データ検証ルールの削除をキャンセルします params.cancel = true})// イベントリスナーを削除するには `disposable.dispose()` を使用しますルール更新イベント
univerAPI.Event.BeforeSheetDataValidationCriteriaUpdate: ルール条件更新前にトリガーします
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationCriteriaUpdate, (params) => { const { worksheet, workbook, ruleId, rule, newCriteria } = params // データ検証ルールの条件更新をキャンセルします params.cancel = true})// イベントリスナーを削除するには `disposable.dispose()` を使用しますuniverAPI.Event.BeforeSheetDataValidationRangeUpdate: ルール範囲更新前にトリガーします
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationRangeUpdate, (params) => { const { worksheet, workbook, ruleId, rule, newRanges } = params // データ検証ルールの範囲更新をキャンセルします params.cancel = true})// イベントリスナーを削除するには `disposable.dispose()` を使用しますuniverAPI.Event.BeforeSheetDataValidationOptionsUpdate: ルールオプション更新前にトリガーします
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationOptionsUpdate, (params) => { const { worksheet, workbook, ruleId, rule, newOptions } = params // データ検証ルールのオプション更新をキャンセルします params.cancel = true})// イベントリスナーを削除するには `disposable.dispose()` を使用しますバリデーション状態イベント
univerAPI.Event.SheetDataValidatorStatusChanged: セルのバリデーション状態が変更されたときにトリガーします
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:ユーザーが無効なデータを入力することを許可しますが、情報メッセージを表示します
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)変更リストのレンダーモード設定
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,})このガイドはいかがですか?