Web SDK

Validation des données

La validation des données permet de définir des règles dans les cellules afin de vérifier que les données saisies répondent à des critères précis. Elle aide à éviter les erreurs de saisie et améliore l’exactitude ainsi que la cohérence des données.

Les types de validation des données suivants sont actuellement pris en charge :

  • Nombre
  • Nombre entier
  • Longueur du texte
  • Date
  • Case à cocher
  • Liste déroulante (sélection simple ou multiple)
  • Formule personnalisée

Mode prédéfini

Installation

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

Utilisation

TypeScript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'import { UniverSheetsDataValidationPreset } from '@univerjs/preset-sheets-data-validation'import UniverPresetSheetsDataValidationEnUS from '@univerjs/preset-sheets-data-validation/locales/en-US'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.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      UniverPresetSheetsCoreEnUS,      UniverPresetSheetsDataValidationEnUS,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsDataValidationPreset(),   ],})

Préréglages et configuration

TypeScript
UniverSheetsDataValidationPreset({  /**   * Whether to display the edit button in the drop-down menu   * @default true   */  showEditOnDropdown: true,  /**   * Whether to display the search box in the drop-down menu   * @default true   */  showSearchOnDropdown: true,})

La liste complète des options de configuration figure dans IUniverSheetsDataValidationPresetConfig.

Mode extension

Installation

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

Utilisation

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 SheetsDataValidationEnUS from '@univerjs/sheets-data-validation-ui/locale/en-US'import '@univerjs/sheets-data-validation-ui/lib/index.css'import '@univerjs/sheets-data-validation/facade'const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      SheetsDataValidationEnUS,     ),  },})univer.registerPlugin(UniverDataValidationPlugin)univer.registerPlugin(UniverSheetsDataValidationPlugin)univer.registerPlugin(UniverSheetsDataValidationUIPlugin)

Extensions et configuration

TypeScript
univer.registerPlugin(UniverSheetsDataValidationUIPlugin, {  /**   * Whether to display the edit button in the drop-down menu   * @default true   */  showEditOnDropdown: true,  /**   * Whether to display the search box in the drop-down menu   * @default true   */  showSearchOnDropdown: true,})

La liste complète des options de configuration figure dans IUniverSheetsDataValidationUIConfig.

Prise en charge mobile

Configurez d’abord l’éditeur mobile. Dans l’initialisation en mode plugin de cette page, remplacez les inscriptions de bureau ci-dessous par les exports mobiles des mêmes paquets avant d’ouvrir un document. Conservez modèles, styles, traductions et imports Facade ; n’enregistrez pas les deux variantes.

PaquetInscription de bureauInscription mobile
@univerjs/sheets-data-validation-uiUniverSheetsDataValidationUIPluginUniverSheetsDataValidationMobileUIPlugin

Facade API

Les définitions de types complètes de l’API Facade sont disponibles dans la référence de l’API Facade.

Importation

Remarque sur le mode extension

Seul le mode extension nécessite d’importer manuellement le package Facade. Le mode prédéfini inclut déjà le package Facade correspondant, aucune importation supplémentaire n’est donc nécessaire.

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

Ajouter une règle de validation des données

univerAPI.newDataValidation() permet de créer un générateur de validation des données. Celui-ci renvoie une instance de FDataValidationBuilder, avec laquelle vous pouvez créer des règles de validation au moyen d’appels chaînés.

Voici quelques méthodes de FDataValidationBuilder :

MéthodeDescription
buildGénère la règle de validation des données.
requireCheckboxExige que la valeur saisie soit une valeur booléenne, affichée sous la forme d’une case à cocher
requireDateAfterDéfinit le type de validation sur DATE et exige une date postérieure à une date donnée
requireDateBeforeDéfinit le type de validation sur DATE et exige une date antérieure à une date donnée
requireDateBetweenDéfinit le type de validation sur DATE et exige une date comprise dans une période donnée
requireDateEqualToDéfinit le type de validation sur DATE et exige une date égale à une date donnée
requireDateNotBetweenDéfinit le type de validation sur DATE et exige une date située en dehors d’une période donnée
requireDateOnOrAfterDéfinit le type de validation sur DATE et exige une date identique ou postérieure à une date donnée
requireDateOnOrBeforeDéfinit le type de validation sur DATE et exige une date identique ou antérieure à une date donnée
requireFormulaSatisfiedExige que la formule fournie soit évaluée à true
requireNumberBetweenExige un nombre compris entre deux nombres donnés, bornes incluses
requireNumberEqualToExige un nombre égal à la valeur donnée
requireNumberGreaterThanExige un nombre supérieur à la valeur donnée
requireNumberGreaterThanOrEqualToExige un nombre supérieur ou égal à la valeur donnée
requireNumberLessThanExige un nombre inférieur à la valeur donnée
requireNumberLessThanOrEqualToExige un nombre inférieur ou égal à la valeur donnée
requireNumberNotBetweenExige un nombre qui n’est ni compris entre les deux nombres donnés, ni égal à l’un d’eux
requireNumberNotEqualToExige un nombre différent de la valeur donnée
requireValueInListExige une valeur issue d’une liste donnée. Prend en charge la sélection simple ou multiple, ainsi que l’affichage ou le masquage de la liste déroulante
requireValueInRangeExige une valeur issue d’une plage donnée. Prend en charge la sélection simple ou multiple, ainsi que l’affichage ou le masquage de la liste déroulante
setOptionsDéfinit les options de la règle de validation des données
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Create a new data validation rule that requires a number between 1 and 10 for the range A1:B10const 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)

Effacer les validations des données d’une plage

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Clear data validation of range A1:B10const fRange = fWorksheet.getRange('A1:B10')fRange.setDataValidation(null)

Récupérer les validations d’une plage ou d’une feuille de calcul

L’objet de règle de validation renvoyé est une instance de FDataValidation. Il permet notamment d’obtenir les critères et les options de la règle.

Voici quelques méthodes de FDataValidation :

MéthodeDescription
copyCrée une instance de FDataValidationBuilder à partir de la règle actuelle
getCriteriaTypeRenvoie le type de validation des données de la règle
getCriteriaValuesRenvoie les valeurs utilisées pour évaluer les critères
getHelpTextRenvoie le texte d’aide destiné à guider l’utilisateur
getRangesRenvoie les plages auxquelles la règle de validation est appliquée
setCriteriaDéfinit les critères de la règle de validation
setOptionsDéfinit les options de la règle de validation
setRangesDéfinit les plages de la règle de validation
deleteSupprime la règle de validation de la feuille de calcul
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Get all data validation rules in current sheet.const rulesOfSheet = fWorksheet.getDataValidations()// Get a data validation rule by rule ID.const ruleById = fWorksheet.getDataValidation(rulesOfSheet[0]?.rule?.uid)const fRange = fWorksheet.getRange('A1:B10')// Get first data validation rule in current range.const ruleOfRange = fRange.getDataValidation()console.log('ruleOfRange:', ruleOfRange, ruleOfRange?.getCriteriaValues())// Get all data validation rules in current range.const rulesOfRange = fRange.getDataValidations()

Mettre à jour ou supprimer une validation des données

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Create a new data validation rule that requires a number equal to 20 for the range A1:B10const fRange = fWorksheet.getRange('A1:B10')const rule = univerAPI.newDataValidation()  .requireNumberEqualTo(20)  .build()fRange.setDataValidation(rule)const newRuleRange = fWorksheet.getRange('C1:D10')// Update the rule after 3 secondssetTimeout(() => {  fRange.getDataValidation()    // Change the range to C1:D10    .setRanges([newRuleRange])    // Change the criteria to require a number between 1 and 10    .setCriteria(      univerAPI.Enum.DataValidationType.DECIMAL,      [univerAPI.Enum.DataValidationOperator.BETWEEN, '1', '10'],    )    // Change option to stop input on validation errors and show error message    .setOptions({      allowBlank: true,      showErrorMessage: true,      error: 'Please enter a valid value',      errorStyle: univerAPI.Enum.DataValidationErrorStyle.STOP,    })}, 3000)// Delete the rule after 6 secondssetTimeout(() => {  newRuleRange.getDataValidation().delete()}, 6000)

Récupérer les erreurs de validation

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Get all data validation errors for current workbook.const workbookErrors = await fWorkbook.getAllDataValidationErrorAsync()console.log('workbookErrors:', workbookErrors)// Get all data validation errors for current sheet.const worksheetErrors = await fWorksheet.getAllDataValidationErrorAsync()console.log('worksheetErrors:', worksheetErrors)// Get data validation errors for current range.const fRange = fWorksheet.getRange('A1:B10')const rangeErrors = await fRange.getDataValidationErrorAsync()console.log('rangeErrors:', rangeErrors)

Chaque objet d’erreur contient les champs suivants :

  • sheetName : nom de la feuille de calcul dans laquelle l’erreur s’est produite
  • row : indice de ligne de la cellule à l’origine de l’erreur
  • column : indice de colonne de la cellule à l’origine de l’erreur
  • ruleId : identifiant de la règle à l’origine de l’erreur
  • inputValue : valeur saisie à l’origine de l’erreur
  • rule : instantané du contenu de la règle

Récupérer l’état du validateur

L’état du validateur est une valeur de l’énumération DataValidationStatus, qui comprend :

  • valid : la valeur de la cellule est valide
  • invalid : la valeur de la cellule n’est pas valide
  • validating : la validation de la cellule est en cours
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Get data validation validator status for current workbook.fWorkbook.getValidatorStatus().then((status) => {  console.log('===statusOfWorkbook', status)})// Get data validation validator status for current sheet.fWorksheet.getValidatorStatusAsync().then((status) => {})// Get data validation validator status for current range.const fRange = fWorksheet.getRange('A1:B10')fRange.getValidatorStatus().then((status) => {  console.log('===tatusOfRange', status)})

Écouteurs d’événements

Pour consulter la définition complète des types d’événements, reportez-vous à la documentation des événements.

Le module de validation des données fournit une série d’événements permettant de surveiller l’ajout, la mise à jour et la suppression des règles, ainsi que les changements d’état de validation. Vous pouvez écouter tous ces événements avec univerAPI.addEvent().

Événements de modification des règles de validation

univerAPI.Event.SheetDataValidationChanged : déclenché après la modification d’une règle de validation

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetDataValidationChanged, (params) => {  const { origin, worksheet, workbook, changeType, oldRule, rule } = params})// Remove the event listener, use `disposable.dispose()`

univerAPI.Event.BeforeSheetDataValidationAdd : déclenché avant l’ajout d’une règle de validation

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationAdd, (params) => {  const { worksheet, workbook, rule } = params  // Cancel the data validation rule addition operation  params.cancel = true})// Remove the event listener, use `disposable.dispose()`

univerAPI.Event.BeforeSheetDataValidationDelete : déclenché avant la suppression d’une règle de validation

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationDelete, (params) => {  const { worksheet, workbook, ruleId, rule } = params  // Cancel the data validation rule deletion operation  params.cancel = true})// Remove the event listener, use `disposable.dispose()`

univerAPI.Event.BeforeSheetDataValidationDeleteAll : déclenché avant la suppression de toutes les règles de validation

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationDeleteAll, (params) => {  const { worksheet, workbook, rules } = params  // Cancel the data validation rule deletion operation  params.cancel = true})// Remove the event listener, use `disposable.dispose()`

Événements de mise à jour des règles de validation

univerAPI.Event.BeforeSheetDataValidationCriteriaUpdate : déclenché avant la mise à jour des critères d’une règle de validation

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationCriteriaUpdate, (params) => {  const { worksheet, workbook, ruleId, rule, newCriteria } = params  // Cancel the data validation rule criteria update operation  params.cancel = true})// Remove the event listener, use `disposable.dispose()`

univerAPI.Event.BeforeSheetDataValidationRangeUpdate : déclenché avant la mise à jour des plages d’une règle de validation

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationRangeUpdate, (params) => {  const { worksheet, workbook, ruleId, rule, newRanges } = params  // Cancel the data validation rule range update operation  params.cancel = true})// Remove the event listener, use `disposable.dispose()`

univerAPI.Event.BeforeSheetDataValidationOptionsUpdate : déclenché avant la mise à jour des options d’une règle de validation

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationOptionsUpdate, (params) => {  const { worksheet, workbook, ruleId, rule, newOptions } = params  // Cancel the data validation rule options update operation  params.cancel = true})// Remove the event listener, use `disposable.dispose()`

Événements d’état de validation

univerAPI.Event.SheetDataValidatorStatusChanged : déclenché lorsque l’état de validation d’une cellule change

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetDataValidatorStatusChanged, (params) => {  const { worksheet, workbook, row, column, status, rule } = params})// Remove the event listener, use `disposable.dispose()`

Chaque événement comprend les paramètres communs suivants :

  • workbook : instance du classeur actuel
  • worksheet : instance de la feuille de calcul actuelle

Paramètres particuliers :

  • rule : objet de la règle de validation concernée
  • ruleId : identifiant unique de la règle de validation
  • status : état de validation (uniquement dans l’événement SheetDataValidatorStatusChanged)
  • newCriteria : nouveaux critères de validation (uniquement dans l’événement BeforeSheetDataValidationCriteriaUpdate)
  • newRanges : nouvelles plages (uniquement dans l’événement BeforeSheetDataValidationRangeUpdate)
  • newOptions : nouvelles options (uniquement dans l’événement BeforeSheetDataValidationOptionsUpdate)

Tous les rappels d’événements dont le nom commence par Before peuvent utiliser params.cancel = true pour empêcher l’opération correspondante.

Style d’erreur

L’option errorStyle détermine le comportement adopté lors de la saisie de données non valides. Il s’agit d’une valeur de l’énumération DataValidationErrorStyle, qui comprend :

  • STOP : empêche la saisie de données non valides
  • WARNING : autorise la saisie de données non valides, mais affiche un avertissement
  • INFO : autorise la saisie de données non valides, mais affiche un message d’information
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: 'Please enter a number between 1 and 10',    errorStyle: univerAPI.Enum.DataValidationErrorStyle.STOP,  })  .build()fRange.setDataValidation(rule)

Modifier le mode d’affichage des listes

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,})

Que pensez-vous de ce guide ?

© 2026 DreamNum Co., Ltd.