Formulärvalidering sker när data rensas. Om du vill anpassa den här processen finns det olika platser där du kan göra ändringar, var och en med olika syften. Tre typer av rengöringsmetoder körs under formulärbehandlingen. Dessa körs normalt när du anropar metoden is_valid() på ett formulär. Det finns andra saker som också kan utlösa rengöring och validering (åtkomst till attributet errors eller direkt anrop av full_clean())), men normalt sett behövs de inte.
I allmänhet kan varje rengöringsmetod höja ValidationError om det finns ett problem med de data den bearbetar, och skicka relevant information till ValidationError-konstruktören. Se nedan för bästa praxis för att höja ValidationError. Om inget ValidationError uppstår bör metoden returnera de rensade (normaliserade) data som ett Python-objekt.
Den mesta valideringen kan göras med hjälp av validatorer - hjälpare som kan återanvändas. Validerare är funktioner (eller anropsbara) som tar ett enda argument och ger upphov till ValidationError vid ogiltig indata. Validerare körs efter att fältets metoder to_python och validate har anropats.
Valideringen av ett formulär är uppdelad i flera steg, som kan anpassas eller åsidosättas:
\nMetoden to_python() på en Field är det första steget i varje validering. Den tvingar värdet till en korrekt datatyp och ger upphov till ValidationError om det inte är möjligt. Den här metoden tar emot det råa värdet från widgeten och returnerar det konverterade värdet. Till exempel: kommer en FloatField att omvandla data till en Python float eller ge upphov till ett ValidationError.
Metoden validate() för en Field hanterar fältspecifik validering som inte lämpar sig för en validerare. Den tar ett värde som har tvingats till en korrekt datatyp och ger upphov till ValidationError vid eventuella fel. Den här metoden returnerar ingenting och bör inte ändra värdet. Du bör åsidosätta den för att hantera valideringslogik som du inte kan eller vill lägga in i en validator.
Metoden run_validators() på ett Field kör alla fältets validatorer och aggregerar alla fel till ett enda ValidationError. Du ska inte behöva åsidosätta den här metoden.
Metoden clean() i en subklass av Field är ansvarig för att köra to_python(), validate() och run_validators() i rätt ordning och sprida deras fel. Om någon av metoderna vid något tillfälle ger upphov till ValidationError, stoppas valideringen och det felet anges. Denna metod returnerar de rena uppgifterna, som sedan infogas i formulärets ordbok cleaned_data.
Metoden clean_<fieldname>() anropas på en formulärunderklass – där <fieldname> ersätts med namnet på formulärfältets attribut. Denna metod utför all rengöring som är specifik för det specifika attributet, oberoende av vilken typ av fält det är. Den här metoden får inga parametrar. Du måste leta upp värdet på fältet i self.cleaned_data och komma ihåg att det kommer att vara ett Python-objekt vid denna tidpunkt, inte den ursprungliga strängen som skickades in i formuläret (det kommer att vara i cleaned_data eftersom den allmänna fältmetoden clean() ovan redan har rensat data en gång).
Om du till exempel vill validera att innehållet i en CharField som heter serialnumber är unikt, skulle clean_serialnumber() vara rätt plats att göra detta. Du behöver inte ett specifikt fält (det är en CharField), men du vill ha en formulärfältsspecifik del av valideringen och eventuellt rensa/normera data.
Returvärdet för den här metoden ersätter det befintliga värdet i cleaned_data, så det måste vara fältets värde från cleaned_data (även om den här metoden inte ändrade det) eller ett nytt rensat värde.
Metoden clean() i formulärunderklassen kan utföra validering som kräver åtkomst till flera formulärfält. Det är här du kan lägga in kontroller som ”om fält A anges, måste fält B innehålla en giltig e-postadress”. Den här metoden kan returnera en helt annan ordbok om den vill, som kommer att användas som cleaned_data.
Eftersom fältvalideringsmetoderna har körts när clean() anropas, har du också tillgång till formulärets errors-attribut som innehåller alla fel som uppstått vid rensning av enskilda fält.
Observera att fel som utlöses av åsidosättningen av Form.clean() inte kopplas till något specifikt fält. De hamnar i ett särskilt ”fält” (kallat __all__), som du kan komma åt via metoden non_field_errors() vid behov. Om du vill koppla fel till ett specifikt fält i formuläret måste du anropa add_error().
Observera också att det finns särskilda överväganden när du åsidosätter clean()-metoden för en ModelForm-underklass. (se ModelForm dokumentation för mer information)
Dessa metoder körs i den ordning som anges ovan, ett fält i taget. För varje fält i formuläret (i den ordning de deklareras i formulärdefinitionen) körs alltså metoden Field.clean() (eller dess åsidosättning), följt av clean_<fieldname>(). När dessa två metoder slutligen har körts för varje fält körs metoden Form.clean(), eller dess åsidosättning, oavsett om de tidigare metoderna har utlöst fel eller inte.
Exempel på var och en av dessa metoder ges nedan.
\nSom nämnts kan någon av dessa metoder ge upphov till ett ValidationError. För ett fält, om metoden Field.clean() ger upphov till ett ValidationError, anropas inte någon fältspecifik rengöringsmetod. Rengöringsmetoderna för alla återstående fält körs dock fortfarande.
ValidationErrorLink to this heading#För att felmeddelanden ska vara flexibla och lätta att åsidosätta bör du beakta följande riktlinjer:
\nAnge en beskrivande fel-code till konstruktorn för att möjliggöra programmatisk användning (t.ex. i tester) som inte varierar med översättningar:
# Good\nValidationError(_("Invalid value"), code="invalid")\n\n# Bad\nValidationError(_("Invalid value"))\nTvinga inte in variabler i meddelandet; använd platshållare och params-argumentet i konstruktören:
# Good\nValidationError(\n _("Invalid value: %(value)s"),\n params={"value": "42"},\n)\n\n# Bad\nValidationError(_("Invalid value: %s") % value)\nAnvänd mappningsnycklar i stället för positionsformatering. Detta gör det möjligt att placera variablerna i vilken ordning som helst eller att utelämna dem helt och hållet när meddelandet skrivs om:
\n# Good\nValidationError(\n _("Invalid value: %(value)s"),\n params={"value": "42"},\n)\n\n# Bad\nValidationError(\n _("Invalid value: %s"),\n params=("42",),\n)\nOmslut meddelandet med gettext för att möjliggöra översättning:
# Good\nValidationError(_("Invalid value"))\n\n# Bad\nValidationError("Invalid value")\nAtt sätta ihop allt:
\nraise ValidationError(\n _("Invalid value: %(value)s"),\n code="invalid",\n params={"value": "42"},\n)\nDet är särskilt viktigt att följa dessa riktlinjer om du skriver återanvändbara formulär, formulärfält och modellfält.
\nÄven om det inte rekommenderas, om du är i slutet av valideringskedjan (dvs. ditt formulär clean()-metoden) och du vet att du aldrig kommer att behöva åsidosätta ditt felmeddelande kan du fortfarande välja den mindre verbala:
ValidationError(_("Invalid value: %s") % value)\nMetoderna Form.errors.as_data() och Form.errors.as_json() har stor nytta av fullt utrustade ValidationError (med ett code-namn och en params-ordbok).
Om du upptäcker flera fel under en rensningsmetod och vill signalera dem alla till den som skickar in formuläret, är det möjligt att skicka en lista med fel till konstruktören ValidationError.
Som ovan rekommenderas det att skicka en lista över ValidationError-instanser med code och params men en lista med strängar fungerar också:
# Good\nraise ValidationError(\n [\n ValidationError(_("Error 1"), code="error1"),\n ValidationError(_("Error 2"), code="error2"),\n ]\n)\n\n# Bad\nraise ValidationError(\n [\n _("Error 1"),\n _("Error 2"),\n ]\n)\nI de föregående avsnitten förklarades hur validering fungerar i allmänhet för formulär. Eftersom det ibland kan vara lättare att få saker på plats genom att se varje funktion användas, följer här en serie små exempel som använder var och en av de tidigare funktionerna.
\nDjangos formulär- (och modell-) fält stöder användning av verktygsfunktioner och klasser som kallas validerare. En validator är ett anropbart objekt eller en funktion som tar ett värde och returnerar ingenting om värdet är giltigt eller ger upphov till ett ValidationError om inte. Dessa kan skickas till ett fälts konstruktör, via fältets validators argument, eller definieras på Field-klassen själv med default_validators-attributet.
Validatorer kan användas för att validera värden i fältet, låt oss ta en titt på Djangos SlugField:
from django.core import validators\nfrom django.forms import CharField\n\n\nclass SlugField(CharField):\n default_validators = [validators.validate_slug]\nSom du kan se är SlugField en CharField med en anpassad validator som validerar att den inskickade texten följer vissa teckenregler. Detta kan också göras på fältdefinitionen så här:
slug = forms.SlugField()\när likvärdig med:
\nslug = forms.CharField(validators=[validators.validate_slug])\nVanliga fall som validering mot ett e-postmeddelande eller ett reguljärt uttryck kan hanteras med hjälp av befintliga valideringsklasser som finns i Django. Till exempel: är validators.validate_slug en instans av en RegexValidator konstruerad med det första argumentet som är mönstret: ^[-a-zA-Z0-9_]+\\Z. Se avsnittet om Skriva validatorer för att se en lista över vad som redan finns tillgängligt och för ett exempel på hur man skriver en validator.
Låt oss först skapa ett anpassat formulärfält som validerar att dess inmatning är en sträng som innehåller kommaseparerade e-postadresser. Den fullständiga klassen ser ut så här:
\nfrom django import forms\nfrom django.core.validators import validate_email\n\n\nclass MultiEmailField(forms.Field):\n def to_python(self, value):\n """Normalize data to a list of strings."""\n # Return an empty list if no input was given.\n if not value:\n return []\n return value.split(",")\n\n def validate(self, value):\n """Check if value consists only of valid emails."""\n # Use the parent's handling of required fields, etc.\n super().validate(value)\n for email in value:\n validate_email(email)\nVarje formulär som använder det här fältet kommer att köra dessa metoder innan något annat kan göras med fältets data. Det här är en rengöring som är specifik för den här typen av fält, oavsett hur det sedan används.
\nLåt oss skapa en ContactForm för att visa hur du använder det här fältet:
class ContactForm(forms.Form):\n subject = forms.CharField(max_length=100)\n message = forms.CharField()\n contact_email = forms.EmailField()\n recipients = MultiEmailField()\n urgent = forms.BooleanField(required=False)\nAnvänd MultiEmailField som vilket annat formulärfält som helst. När metoden is_valid() anropas på formuläret kommer metoden MultiEmailField.clean() att köras som en del av rengöringsprocessen och den kommer i sin tur att anropa de anpassade metoderna to_python() och validate().
Fortsätt från föregående exempel och anta att vi i vårt ContactForm vill säkerställa att fältet recipients endast innehåller adresser som är @example.com. Detta är validering som är specifik för formuläret, så vi vill inte lägga den i den generella klassen MultiEmailField. I stället skriver vi en rensningsmetod som arbetar på fältet recipients, så här:
from django import forms\nfrom django.core.exceptions import ValidationError\n\n\nclass ContactForm(forms.Form):\n # Everything as before.\n ...\n\n def clean_recipients(self):\n data = self.cleaned_data["recipients"]\n if not all(email.endswith("@example.com") for email in data):\n raise ValidationError("All recipients must be @example.com.")\n\n # Always return a value to use as the new cleaned data, even if\n # this method didn't change it.\n return data\nAnta att vi lägger till ytterligare ett krav för kontaktformuläret: om fältet urgent är True måste subject innehålla "help". Vi utför validering av mer än ett fält åt gången, så formulärets metod clean() är ett bra ställe att göra detta på. Observera att vi här talar om metoden clean() på formuläret, medan vi tidigare skrev en metod clean() på ett fält. Det är viktigt att hålla skillnaden mellan fält och formulär tydlig när man avgör var saker ska valideras. Fält är enskilda datapunkter, formulär är en samling fält.
När formulärets clean()-metod anropas har alla enskilda fältrengöringsmetoder körts (de två föregående avsnitten), så self.cleaned_data kommer att fyllas i med alla data som har överlevt hittills. Så du måste också komma ihåg att ta hänsyn till det faktum att de fält du vill validera kanske inte har överlevt de första individuella fältkontrollerna.
Det finns två sätt att rapportera eventuella fel från detta steg. Den vanligaste metoden är förmodligen att visa felet högst upp i formuläret. För att skapa ett sådant fel kan du skapa ett ValidationError från clean()-metoden. Till exempel:
from django import forms\nfrom django.core.exceptions import ValidationError\n\n\nclass ContactForm(forms.Form):\n # Everything as before.\n ...\n\n def clean(self):\n cleaned_data = super().clean()\n urgent = cleaned_data.get("urgent")\n subject = cleaned_data.get("subject")\n\n if urgent and subject:\n # Only do something if both fields are valid so far.\n if "help" not in subject:\n raise ValidationError(\n "Must put 'help' in the subject for urgent requests."\n )\nI den här koden visas ett felmeddelande högst upp i formuläret (normalt) som beskriver problemet om valideringsfelet uppstår. Sådana fel är icke-fältfel, som visas i mallen med {{ form.non_field_errors }}.
Anropet till super().clean() i exempelkoden säkerställer att all valideringslogik i överordnade klasser bibehålls. Om ditt formulär ärver ett annat som inte returnerar en cleaned_data-ordbok i sin clean()-metod (att göra det är valfritt), tilldela då inte cleaned_data till resultatet av super()-anropet och använd self.cleaned_data istället:
def clean(self):\n super().clean()\n urgent = self.cleaned_data.get("urgent")\n ...\nDet andra sättet att rapportera valideringsfel kan innebära att felmeddelandet tilldelas ett av fälten. I detta fall tilldelar vi ett felmeddelande både raden ”subject” och raden ”urgent” i formulärvisningen. Var försiktig när du gör detta i praktiken, eftersom det kan leda till förvirrande formulärutdata. Här visar vi vad som är möjligt och lämnar åt dig och dina designers att avgöra vad som fungerar effektivt i din specifika situation. Vår nya kod (som ersätter det föregående exemplet) ser ut så här:
\nfrom django import forms\n\n\nclass ContactForm(forms.Form):\n # Everything as before.\n ...\n\n def clean(self):\n cleaned_data = super().clean()\n urgent = cleaned_data.get("urgent")\n subject = cleaned_data.get("subject")\n\n if urgent and subject and "help" not in subject:\n self.add_error(\n "subject", "Must put 'help' in the subject for urgent requests."\n )\n self.add_error(\n "urgent", "Must not mark urgent unless 'help' is in the subject."\n )\nDet andra argumentet i add_error() kan vara en sträng, eller helst en instans av ValidationError. Se Upphävande av ValidationError för mer information. Notera att add_error() automatiskt tar bort fältet från cleaned_data.