# Documentation Django 3.1.9.dev

# Champs et composants de formulaires spécifiques à PostgreSQL

Tous ces champs et composants sont disponibles dans le module `django.contrib.postgres.forms`.

## Champs

### `SimpleArrayField`

class `SimpleArrayField`(base_field, delimiter=', ', max_length=None, min_length=None)

  Un champ qui correspond à un tableau. Il est représenté par un élément HTML `<input>`.

  `base_field`

    Ce paramètre est obligatoire.

    Il définit le champ de formulaire de base du tableau. Ceci n’est pas utilisé pour produire du code HTML, mais pour traiter les données envoyées et les valider. Par exemple :

        >>> from django import forms
        >>> from django.contrib.postgres.forms import SimpleArrayField

        >>> class NumberListForm(forms.Form):
        ...     numbers = SimpleArrayField(forms.IntegerField())

        >>> form = NumberListForm({'numbers': '1,2,3'})
        >>> form.is_valid()
        True
        >>> form.cleaned_data
        {'numbers': [1, 2, 3]}

        >>> form = NumberListForm({'numbers': '1,2,a'})
        >>> form.is_valid()
        False

  `delimiter`

    Il s’agit d’un paramètre facultatif dont la valeur par défaut est une virgule : `,`. Cette valeur est utilisée pour séparer les données envoyées. Elle permet d’enchaîner des champs `SimpleArrayField` pour des données à plusieurs dimensions :

        >>> from django import forms
        >>> from django.contrib.postgres.forms import SimpleArrayField

        >>> class GridForm(forms.Form):
        ...     places = SimpleArrayField(SimpleArrayField(IntegerField()), delimiter='|')

        >>> form = GridForm({'places': '1,2|2,1|4,3'})
        >>> form.is_valid()
        True
        >>> form.cleaned_data
        {'places': [[1, 2], [2, 1], [4, 3]]}

    Note

    Le champ ne permet pas d’échapper le caractère de délimitation, soyez donc prudent dans les cas où le délimiteur est un caractère valable du champ sous-jacent. Le délimiteur ne doit pas forcément se limiter à un seul caractère.

  `max_length`

    C’est un paramètre facultatif qui valide que le tableau ne dépasse pas la longueur indiquée.

  `min_length`

    C’est un paramètre facultatif qui valide que le tableau atteint au moins la longueur indiquée.

  Formulaires conviviaux

  `SimpleArrayField` n’est pas particulièrement convivial dans la plupart des cas, mais il s’agit toutefois d’une manière utile de mettre en forme des données à partir d’un composant client pour les envoyer vers le serveur.

### `SplitArrayField`

class `SplitArrayField`(base_field, size, remove_trailing_nulls=False)

  Ce champ se charge des tableaux en reproduisant le champ de base un nombre défini de fois.

  `base_field`

    Il s’agit d’un paramètre obligatoire. Il définit le champ de formulaire à répéter.

  `size`

    Le nombre de fois que le champ de base va être utilisé.

  `remove_trailing_nulls`

    Par défaut, cette valeur vaut `False`. Dans ce cas, chaque valeur des champs répétés est stockée. Quand la valeur vaut `True`, toute valeur en fin de tableau qui reste vierge est supprimée du résultat. Si le champ de base possède `required=True` mais que `remove_trailing_nulls` vaut `True`, les valeurs nulles ne sont permises qu’à la fin et elles seront ignorées.

    Quelques exemples :

        SplitArrayField(IntegerField(required=True), size=3, remove_trailing_nulls=False)

        ['1', '2', '3']  # -> [1, 2, 3]
        ['1', '2', '']  # -> ValidationError - third entry required.
        ['1', '', '3']  # -> ValidationError - second entry required.
        ['', '2', '']  # -> ValidationError - first and third entries required.

        SplitArrayField(IntegerField(required=False), size=3, remove_trailing_nulls=False)

        ['1', '2', '3']  # -> [1, 2, 3]
        ['1', '2', '']  # -> [1, 2, None]
        ['1', '', '3']  # -> [1, None, 3]
        ['', '2', '']  # -> [None, 2, None]

        SplitArrayField(IntegerField(required=True), size=3, remove_trailing_nulls=True)

        ['1', '2', '3']  # -> [1, 2, 3]
        ['1', '2', '']  # -> [1, 2]
        ['1', '', '3']  # -> ValidationError - second entry required.
        ['', '2', '']  # -> ValidationError - first entry required.

        SplitArrayField(IntegerField(required=False), size=3, remove_trailing_nulls=True)

        ['1', '2', '3']  # -> [1, 2, 3]
        ['1', '2', '']  # -> [1, 2]
        ['1', '', '3']  # -> [1, None, 3]
        ['', '2', '']  # -> [None, 2]

### `HStoreField`

class `HStoreField`

  Un champ qui accepte des données codées en JSON pour un champ `HStoreField`. Il force toutes les valeurs (sauf la valeur nulle) à des chaînes. En HTML, il est représenté par une balise `<textarea>`.

  Formulaires conviviaux

  `HStoreField` n’est pas particulièrement convivial dans la plupart des cas, il s’agit cependant d’une manière utile de mettre en forme des données d’un composant côté client en vue de son envoi vers le serveur.

  Note

  Parfois, il est utile de pouvoir limiter les clés admises comme valides pour un champ donné. Cela peut se faire à l’aide de `KeysValidator`.

### `JSONField`

class `JSONField`

  Un champ qui accepte des données codées en JSON pour un champ `JSONField`. En HTML, il est représenté par une balise `<textarea>`.

  Formulaires conviviaux

  `JSONField` n’est pas particulièrement convivial dans la plupart des cas, il s’agit cependant d’une manière utile de mettre en forme des données d’un composant côté client en vue de son envoi vers le serveur.

  Obsolète depuis la version 3.1: Utilisez plutôt `django.forms.JSONField`.

### Champs d’intervalle

Ce groupe de champs partage des fonctionnalités identiques pour accepter des données d’intervalle. Ils sont basés sur `MultiValueField`. Ils traitent une valeur omise comme un intervalle illimité. Ils valident aussi que la limite inférieure n’est pas plus grande que la limite supérieure. Tous ces champs utilisent le composant `RangeWidget`.

#### `IntegerRangeField`

class `IntegerRangeField`

  Basé sur `IntegerField` et traduit la valeur saisie en intervalle `NumericRange`. Champ de formulaire par défaut pour `IntegerRangeField` et `BigIntegerRangeField`.

#### `DecimalRangeField`

class `DecimalRangeField`

  Basé sur `DecimalField` et traduit la valeur saisie en intervalle `NumericRange`. Champ de formulaire par défaut pour `DecimalRangeField`.

#### `DateTimeRangeField`

class `DateTimeRangeField`

  Basé sur `DateTimeField` et traduit la valeur saisie en intervalle `DateTimeTZRange`. Champ de formulaire par défaut pour `DateTimeRangeField`.

#### `DateRangeField`

class `DateRangeField`

  Basé sur `DateField` et traduit la valeur saisie en intervalle `DateRange`. Champ de formulaire par défaut pour `DateRangeField`.

## Composants de formulaires (« widgets »)

### `RangeWidget`

class `RangeWidget`(base_widget, attrs=None)

  Composant utilisé par tous les champs d’intervalle. Basé sur `MultiWidget`.

  `RangeWidget` requiert un paramètre obligatoire :

  `base_widget`

    Un intervalle `RangeWidget` composé d’un tuple binaire de `base_widget`.

  `decompress`(value)

    Accepte une valeur « compressée » unique d’un champ, par exemple un intervalle `DateRangeField`, et renvoie un tuple représentant les limites inférieure et supérieure.