# Validation des données - Human documentation: [https://docs.univer.ai/fr-FR/guides/sheets/features/data-validation](https://docs.univer.ai/fr-FR/guides/sheets/features/data-validation) - Agent Markdown: [https://docs.univer.ai/fr-FR/guides/sheets/features/data-validation.md](https://docs.univer.ai/fr-FR/guides/sheets/features/data-validation.md) - Requested language: `fr-FR` - Content language: `fr-FR` - Documentation version: `1.2.0` - Source: [sheets/features/data-validation.fr-FR.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/data-validation.fr-FR.mdx) --- #### Package metadata ```json { "preset": [ { "client": "@univerjs/preset-sheets-data-validation", "locale": "@univerjs/preset-sheets-data-validation/locales/fr-FR", "style": "@univerjs/preset-sheets-data-validation/lib/index.css" } ], "plugins": [ { "client": "@univerjs/data-validation", "locale": "@univerjs/data-validation/locale/fr-FR" }, { "client": "@univerjs/sheets-data-validation", "facade": "@univerjs/sheets-data-validation/facade", "locale": "@univerjs/sheets-data-validation/locale/fr-FR" }, { "client": "@univerjs/sheets-data-validation-ui", "locale": "@univerjs/sheets-data-validation-ui/locale/fr-FR", "style": "@univerjs/sheets-data-validation-ui/lib/index.css" } ], "mobile": true, "server": false } ``` 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 #### npm ```bash npm install @univerjs/preset-sheets-data-validation ``` #### pnpm ```bash pnpm add @univerjs/preset-sheets-data-validation ``` #### yarn ```bash yarn add @univerjs/preset-sheets-data-validation ``` #### bun ```bash bun 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' // [!code ++] import UniverPresetSheetsDataValidationEnUS from '@univerjs/preset-sheets-data-validation/locales/en-US' // [!code ++] import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets' import '@univerjs/preset-sheets-core/lib/index.css' import '@univerjs/preset-sheets-data-validation/lib/index.css' // [!code ++] const { univerAPI } = createUniver({ locale: LocaleType.EN_US, locales: { [LocaleType.EN_US]: mergeLocales( UniverPresetSheetsCoreEnUS, UniverPresetSheetsDataValidationEnUS, // [!code ++] ), }, presets: [ UniverSheetsCorePreset(), UniverSheetsDataValidationPreset(), // [!code ++] ], }) ``` ### 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`](https://github.com/dream-num/univer/tree/dev/presets/packages/preset-sheets-data-validation). ## Mode extension ### Installation #### npm ```bash npm install @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-ui ``` #### pnpm ```bash pnpm add @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-ui ``` #### yarn ```bash yarn add @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-ui ``` #### bun ```bash bun 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' // [!code ++] import { UniverSheetsDataValidationPlugin } from '@univerjs/sheets-data-validation' // [!code ++] import { UniverSheetsDataValidationUIPlugin } from '@univerjs/sheets-data-validation-ui' // [!code ++] import SheetsDataValidationEnUS from '@univerjs/sheets-data-validation-ui/locale/en-US' // [!code ++] import '@univerjs/sheets-data-validation-ui/lib/index.css' // [!code ++] import '@univerjs/sheets-data-validation/facade' // [!code ++] const univer = new Univer({ locale: LocaleType.EN_US, locales: { [LocaleType.EN_US]: mergeLocales( SheetsDataValidationEnUS, // [!code ++] ), }, }) univer.registerPlugin(UniverDataValidationPlugin) // [!code ++] univer.registerPlugin(UniverSheetsDataValidationPlugin) // [!code ++] univer.registerPlugin(UniverSheetsDataValidationUIPlugin) // [!code ++] ``` ### 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`](https://github.com/dream-num/univer/blob/dev/packages/sheets-data-validation-ui/src/config/config.ts). ## Prise en charge mobile Configurez d’abord l’[éditeur mobile](https://docs.univer.ai/fr-FR/guides/sheets/getting-started/installation.md#mobile-support). 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. | Paquet | Inscription de bureau | Inscription mobile | | ------------------------------------- | ------------------------------------ | ------------------------------------------ | | `@univerjs/sheets-data-validation-ui` | `UniverSheetsDataValidationUIPlugin` | `UniverSheetsDataValidationMobileUIPlugin` | ## Facade API Les définitions de types complètes de l’API Facade sont disponibles dans la [référence de l’API Facade](https://docs.univer.ai/fr-FR/reference/facade.md). ### Importation > [!INFO: 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()`](https://docs.univer.ai/fr-FR/reference/facade/univer.md#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`](https://docs.univer.ai/fr-FR/reference/facade/data-validation-builder.md) : | Méthode | Description | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | build | Génère la règle de validation des données. | | requireCheckbox | Exige que la valeur saisie soit une valeur booléenne, affichée sous la forme d’une case à cocher | | requireDateAfter | Définit le type de validation sur DATE et exige une date postérieure à une date donnée | | requireDateBefore | Définit le type de validation sur DATE et exige une date antérieure à une date donnée | | requireDateBetween | Définit le type de validation sur DATE et exige une date comprise dans une période donnée | | requireDateEqualTo | Définit le type de validation sur DATE et exige une date égale à une date donnée | | requireDateNotBetween | Définit le type de validation sur DATE et exige une date située en dehors d’une période donnée | | requireDateOnOrAfter | Définit le type de validation sur DATE et exige une date identique ou postérieure à une date donnée | | requireDateOnOrBefore | Définit le type de validation sur DATE et exige une date identique ou antérieure à une date donnée | | requireFormulaSatisfied | Exige que la formule fournie soit évaluée à `true` | | requireNumberBetween | Exige un nombre compris entre deux nombres donnés, bornes incluses | | requireNumberEqualTo | Exige un nombre égal à la valeur donnée | | requireNumberGreaterThan | Exige un nombre supérieur à la valeur donnée | | requireNumberGreaterThanOrEqualTo | Exige un nombre supérieur ou égal à la valeur donnée | | requireNumberLessThan | Exige un nombre inférieur à la valeur donnée | | requireNumberLessThanOrEqualTo | Exige un nombre inférieur ou égal à la valeur donnée | | requireNumberNotBetween | Exige un nombre qui n’est ni compris entre les deux nombres donnés, ni égal à l’un d’eux | | requireNumberNotEqualTo | Exige un nombre différent de la valeur donnée | | requireValueInList | Exige 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 | | requireValueInRange | Exige 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 | | setOptions | Dé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:B10 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) ``` ### Effacer les validations des données d’une plage ```typescript const fWorkbook = univerAPI.getActiveWorkbook() const fWorksheet = fWorkbook.getActiveSheet() // Clear data validation of range A1:B10 const 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`](https://docs.univer.ai/fr-FR/reference/facade/data-validation.md) : | Méthode | Description | | ----------------- | ------------------------------------------------------------------------- | | copy | Crée une instance de FDataValidationBuilder à partir de la règle actuelle | | getCriteriaType | Renvoie le type de validation des données de la règle | | getCriteriaValues | Renvoie les valeurs utilisées pour évaluer les critères | | getHelpText | Renvoie le texte d’aide destiné à guider l’utilisateur | | getRanges | Renvoie les plages auxquelles la règle de validation est appliquée | | setCriteria | Définit les critères de la règle de validation | | setOptions | Définit les options de la règle de validation | | setRanges | Définit les plages de la règle de validation | | delete | Supprime 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:B10 const 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 seconds setTimeout(() => { 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 seconds setTimeout(() => { 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](https://docs.univer.ai/fr-FR/reference/facade/events.md). 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, }) ```