En instans av Form är antingen bunden till en uppsättning data eller obunden.
Om det är bundet till en uppsättning data, kan det validera dessa data och rendera formuläret som HTML med de data som visas i HTML.
Om det är unbound kan det inte göra validering (eftersom det inte finns några data att validera!), men det kan fortfarande återge det tomma formuläret som HTML.
För att skapa en obunden Form-instans instansierar du klassen:
>>> f = ContactForm()\nFör att binda data till ett formulär skickar du data som en ordbok som första parameter till din Form-klass konstruktör:
>>> data = {\n... "subject": "hello",\n... "message": "Hi there",\n... "contact_email": "foo@example.com",\n... "urgent": True,\n... }\n>>> f = ContactForm(data)\nI den här ordlistan är nycklarna fältnamnen, som motsvarar attributen i din klass Form. Värdena är de data som du försöker validera. Dessa kommer vanligtvis att vara strängar, men det finns inget krav på att de ska vara strängar; typen av data du skickar beror på Field, som vi kommer att se om ett ögonblick.
Om du behöver skilja mellan bundna och obundna formulärinstanser vid körning, kontrollera värdet på formulärets attribut is_bound:
>>> f = ContactForm()\n>>> f.is_bound\nFalse\n>>> f = ContactForm({"subject": "hello"})\n>>> f.is_bound\nTrue\nObservera att om du skickar en tom ordbok skapas ett bundet formulär med tomma data:
\n>>> f = ContactForm({})\n>>> f.is_bound\nTrue\nOm du har en bunden Form-instans och vill ändra data på något sätt, eller om du vill binda en obunden Form-instans till vissa data, skapar du en annan Form-instans. Det finns inget sätt att ändra data i en Form-instans. När en Form-instans har skapats bör du betrakta dess data som oföränderliga, oavsett om den har data eller inte.
Implementera en clean()-metod på din Form när du måste lägga till anpassad validering för fält som är beroende av varandra. Se Rengöring och validering av fält som är beroende av varandra för exempel på användning.
Den primära uppgiften för ett Form-objekt är att validera data. Med en bunden Form-instans anropar du is_valid()-metoden för att köra validering och returnera en boolesk som anger om data var giltiga:
>>> data = {\n... "subject": "hello",\n... "message": "Hi there",\n... "contact_email": "foo@example.com",\n... "urgent": True,\n... }\n>>> f = ContactForm(data)\n>>> f.is_valid()\nTrue\nLet’s try with some invalid data. In this case, subject is blank (an error,\nbecause all fields are required by default) and contact_email is not a\nvalid email address:
>>> data = {\n... "subject": "",\n... "message": "Hi there",\n... "contact_email": "invalid email address",\n... "urgent": True,\n... }\n>>> f = ContactForm(data)\n>>> f.is_valid()\nFalse\nFå tillgång till attributet errors för att få en ordlista med felmeddelanden:
>>> f.errors\n{'subject': ['This field is required.'],\n 'contact_email': ['Enter a valid email address.']}\nI den här ordlistan är nycklarna fältnamnen och värdena listor med strängar som representerar felmeddelandena. Felmeddelandena lagras i listor eftersom ett fält kan ha flera felmeddelanden.
\nDu kan komma åt errors utan att först behöva anropa is_valid(). Formulärets data kommer att valideras första gången du antingen anropar is_valid() eller använder errors.
Valideringsrutinerna kommer bara att anropas en gång, oavsett hur många gånger du använder errors eller anropar is_valid(). Detta innebär att om valideringen har bieffekter, kommer dessa bieffekter bara att utlösas en gång.
Returnerar ett dict som mappar fält till deras ursprungliga ValidationError-instanser.
>>> f.errors.as_data()\n{'subject': [ValidationError(['This field is required.'])],\n 'contact_email': [ValidationError(['Enter a valid email address.'])]}\nUse this method anytime you need to identify an error by its code. This\nenables things like rewriting the error’s message or writing custom logic in a\nview when a given error is present. It can also be used to serialize the errors\nin a custom format (e.g. XML); for instance, as_json()\nrelies on as_data().
Behovet av metoden as_data() beror på bakåtkompatibilitet. Tidigare förlorades ValidationError-instanser så snart deras renderade felmeddelanden lades till i Form.errors-ordlistan. Helst skulle Form.errors ha lagrat ValidationError-instanser och metoder med ett as_-prefix skulle kunna rendera dem, men det måste göras tvärtom för att inte bryta kod som förväntar sig renderade felmeddelanden i Form.errors.
Returns a string with the errors serialized as JSON.
\n>>> f.errors.as_json()\n'{"subject": [{"message": "This field is required.", "code": "required"}],\n "contact_email": [{"message": "Enter a valid email address.", "code": "invalid"}]}'\nSom standard escapar inte as_json() sin utdata. Om du använder den för något som AJAX-förfrågningar till en formulärvy där klienten tolkar svaret och infogar fel på sidan, vill du vara säker på att undkomma resultaten på klientsidan för att undvika risken för en cross-site scripting-attack. Du kan göra detta i JavaScript med element.textContent = errorText eller med jQuerys $(el).text(errorText) (snarare än dess .html()-funktion).
Om du av någon anledning inte vill använda escaping på klientsidan kan du också ställa in escape_html=True och felmeddelanden kommer att escapas så att du kan använda dem direkt i HTML.
Returns the errors as a dictionary suitable for serializing to JSON.\nForm.errors.as_json() returns serialized JSON, while this returns the\nerror data before it’s serialized.
The escape_html parameter behaves as described in\nForm.errors.as_json().
Denna metod gör det möjligt att lägga till fel i specifika fält inom metoden Form.clean(), eller helt utanför formuläret, t.ex. från en vy.
Argumentet field är namnet på det fält som felen ska läggas till i. Om dess värde är None kommer felet att behandlas som ett icke-fältfel som returneras av Form.non_field_errors().
Argumentet error kan vara en sträng, eller helst en instans av ValidationError. Se Upphävande av ValidationError för bästa praxis vid definition av formulärfel.
Observera att Form.add_error() automatiskt tar bort det relevanta fältet från cleaned_data.
Denna metod returnerar en boolean som anger om ett fält har ett fel med en specifik fel-”kod”. Om code är None returneras True om fältet innehåller några fel alls.
För att kontrollera fel som inte är fält använder du NON_FIELD_ERRORS som parametern field.
Den här metoden returnerar listan över fel från Form.errors som inte är associerade med ett visst fält. Detta inkluderar ValidationError som tas upp i Form.clean() och fel som läggs till med Form.add_error(None, "...").
Det är meningslöst att validera ett formulär utan data, men så här går det till när formuläret är obundet:
\n>>> f = ContactForm()\n>>> f.is_valid()\nFalse\n>>> f.errors\n{}\nAnvänd initial för att ange det initiala värdet för formulärfält vid körning. Du kanske t.ex. vill fylla i fältet username med användarnamnet för den aktuella sessionen.
För att åstadkomma detta använder du argumentet initial till en Form. Detta argument, om det anges, bör vara en ordbok som mappar fältnamn till initiala värden. Inkludera bara de fält för vilka du anger ett initialt värde; det är inte nödvändigt att inkludera alla fält i ditt formulär. Exempelvis:
>>> f = ContactForm(initial={"subject": "Hi there!"})\nDessa värden visas endast för obundna formulär och de används inte som reservvärden om ett visst värde inte anges.
\nOm en Field definierar initial och du inkluderar initial när du instansierar Form, så kommer den senare initial att ha företräde. I det här exemplet anges initial både på fältnivå och på formulärinstansnivå, och den senare får företräde:
>>> from django import forms\n>>> class CommentForm(forms.Form):\n... name = forms.CharField(initial="class")\n... url = forms.URLField()\n... comment = forms.CharField()\n...\n>>> f = CommentForm(initial={"name": "instance"}, auto_id=False)\n>>> print(f)\n<div>Name:<input type="text" name="name" value="instance" required></div>\n<div>Url:<input type="url" name="url" required></div>\n<div>Comment:<input type="text" name="comment" required></div>\nReturnerar de initiala uppgifterna för ett formulärfält. Den hämtar data från Form.initial om den finns, annars försöker den Field.initial. Kallbara värden utvärderas.
It is recommended to use BoundField.initial over\nget_initial_for_field() because BoundField.initial has a\nsimpler interface. Also, unlike get_initial_for_field(),\nBoundField.initial caches its values. This is useful especially when\ndealing with callables whose return values can change (e.g. datetime.now or\nuuid.uuid4):
>>> import uuid\n>>> class UUIDCommentForm(CommentForm):\n... identifier = forms.UUIDField(initial=uuid.uuid4)\n...\n>>> f = UUIDCommentForm()\n>>> f.get_initial_for_field(f.fields["identifier"], "identifier")\nUUID('972ca9e4-7bfe-4f5b-af7d-07b3aa306334')\n>>> f.get_initial_for_field(f.fields["identifier"], "identifier")\nUUID('1b411fab-844e-4dec-bd4f-e9b0495f04d0')\n>>> # Using BoundField.initial, for comparison\n>>> f["identifier"].initial\nUUID('28a09c59-5f00-4ed9-9179-a3b074fa9c30')\n>>> f["identifier"].initial\nUUID('28a09c59-5f00-4ed9-9179-a3b074fa9c30')\nAnvänd metoden has_changed() på ditt Form när du behöver kontrollera om formulärdata har ändrats från de ursprungliga data.
>>> data = {\n... "subject": "hello",\n... "message": "Hi there",\n... "contact_email": "foo@example.com",\n... "urgent": True,\n... }\n>>> f = ContactForm(data, initial=data)\n>>> f.has_changed()\nFalse\nNär formuläret skickas in rekonstruerar vi det och tillhandahåller originaldata så att jämförelsen kan göras:
\n>>> f = ContactForm(request.POST, initial=data)\n>>> f.has_changed()\nTrue\nhas_changed() blir True om data från request.POST skiljer sig från vad som angavs i initial eller False annars. Resultatet beräknas genom att anropa Field.has_changed() för varje fält i formuläret.
Attributet changed_data returnerar en lista med namnen på de fält vars värden i formulärets bundna data (vanligtvis request.POST) skiljer sig från vad som angavs i initial. Det returnerar en tom lista om inga data skiljer sig åt.
>>> f = ContactForm(request.POST, initial=data)\n>>> f.changed_data\n['subject', 'message']\nDu kan komma åt fälten i Form-instansen från dess fields-attribut:
>>> for row in f.fields.values():\n... print(row)\n...\n<django.forms.fields.CharField object at 0x7ffaac632510>\n<django.forms.fields.URLField object at 0x7ffaac632f90>\n<django.forms.fields.CharField object at 0x7ffaac3aa050>\n>>> f.fields["name"]\n<django.forms.fields.CharField object at 0x7ffaac6324d0>\nDu kan ändra fältet och BoundField i Form-instansen för att ändra hur det presenteras i formuläret:
>>> f.as_div().split("</div>")[0]\n'<div><label for="id_subject">Subject:</label><input type="text" name="subject" maxlength="100" required id="id_subject">'\n>>> f["subject"].label = "Topic"\n>>> f.as_div().split("</div>")[0]\n'<div><label for="id_subject">Topic:</label><input type="text" name="subject" maxlength="100" required id="id_subject">'\nTänk på att inte ändra attributet base_fields eftersom denna ändring kommer att påverka alla efterföljande ContactForm-instanser inom samma Python-process:
>>> f.base_fields["subject"].label_suffix = "?"\n>>> another_f = ContactForm(auto_id=False)\n>>> another_f.as_div().split("</div>")[0]\n'<div><label for="id_subject">Subject?</label><input type="text" name="subject" maxlength="100" required id="id_subject">'\nVarje fält i en Form-klass ansvarar inte bara för att validera data utan också för att ”rensa” dem - normalisera dem till ett enhetligt format. Det här är en bra funktion eftersom det gör att data för ett visst fält kan matas in på många olika sätt och alltid resultera i ett enhetligt resultat.
Till exempel: normaliserar DateField indata till ett Python-objekt av typen datetime.date. Oavsett om du skickar en sträng i formatet '1994-07-15', ett datetime.date-objekt eller ett antal andra format, kommer DateField alltid att normalisera det till ett datetime.date-objekt så länge det är giltigt.
När du har skapat en Form-instans med en uppsättning data och validerat den, kan du komma åt de rena data via dess cleaned_data-attribut:
>>> data = {\n... "subject": "hello",\n... "message": "Hi there",\n... "contact_email": "foo@example.com",\n... "urgent": True,\n... }\n>>> f = ContactForm(data)\n>>> f.is_valid()\nTrue\n>>> f.cleaned_data\n{'subject': 'hello', 'message': 'Hi there', 'contact_email': 'foo@example.com', 'urgent': True}\nObservera att alla textbaserade fält - t.ex. CharField eller EmailField - alltid omvandlar inmatningen till en sträng. Vi kommer att täcka kodningsimplikationerna senare i detta dokument.
Om dina data inte valideras innehåller ordlistan cleaned_data endast de giltiga fälten:
>>> data = {\n... "subject": "",\n... "message": "Hi there",\n... "contact_email": "invalid email address",\n... "urgent": True,\n... }\n>>> f = ContactForm(data)\n>>> f.is_valid()\nFalse\n>>> f.cleaned_data\n{'message': 'Hi there', 'urgent': True}\ncleaned_data kommer alltid bara att innehålla en nyckel för fält som definieras i Form, även om du skickar extra data när du definierar Form. I det här exemplet skickar vi en massa extra fält till konstruktören ContactForm, men cleaned_data innehåller bara formulärets fält:
>>> data = {\n... "subject": "hello",\n... "message": "Hi there",\n... "contact_email": "foo@example.com",\n... "urgent": True,\n... "extra_field_1": "foo",\n... "extra_field_2": "bar",\n... "extra_field_3": "baz",\n... }\n>>> f = ContactForm(data)\n>>> f.is_valid()\nTrue\n>>> f.cleaned_data # Doesn't contain extra_field_1, etc.\n{'subject': 'hello', 'message': 'Hi there', 'contact_email': 'foo@example.com', 'urgent': True}\nWhen the Form is valid, cleaned_data will include a key and value for\nall its fields, even if the data didn’t include a value for some optional\nfields. In this example, the data dictionary doesn’t include a value for the\nnickname field, but cleaned_data includes it, with an empty value:
>>> from django import forms\n>>> class OptionalPersonForm(forms.Form):\n... first_name = forms.CharField()\n... last_name = forms.CharField()\n... nickname = forms.CharField(required=False)\n...\n>>> data = {"first_name": "John", "last_name": "Lennon"}\n>>> f = OptionalPersonForm(data)\n>>> f.is_valid()\nTrue\n>>> f.cleaned_data\n{'first_name': 'John', 'last_name': 'Lennon', 'nickname': ''}\nIn this above example, the cleaned_data value for nickname is set to\nan empty string, because nickname is CharField, and CharFields\ntreat empty values as an empty string. Each field type knows what its ”blank”\nvalue is – e.g., for DateField, it’s None instead of the empty string.\nFor full details on each field’s behavior in this case, see the ”Empty value”\nnote for each field in the Inbyggda Field-klasser section below.
Du kan skriva kod för att utföra validering för vissa formulärfält (baserat på deras namn) eller för formuläret som helhet (med hänsyn till kombinationer av olika fält). Mer information om detta finns i Validering av formulär och fält.
\nDen andra uppgiften för ett Form-objekt är att rendera sig själv som HTML. För att göra det, print det:
>>> f = ContactForm()\n>>> print(f)\n<div><label for="id_subject">Subject:</label><input type="text" name="subject" maxlength="100" required id="id_subject"></div>\n<div><label for="id_message">Message:</label><textarea name="message" cols="40" rows="10" required id="id_message"></textarea></div>\n<div><label for="id_contact_email">Contact email:</label><input type="email" name="contact_email" maxlength="320" required id="id_contact_email"></div>\n<div><label for="id_urgent">Urgent:</label><input type="checkbox" name="urgent" id="id_urgent"></div>\nOm formuläret är bundet till data kommer HTML-utdata att innehålla dessa data på lämpligt sätt. Om ett fält t.ex. representeras av en <input type="text">, kommer data att finnas i attributet value. Om ett fält representeras av en <input type="checkbox">, kommer HTML-texten att innehålla checked om så är lämpligt:
>>> data = {\n... "subject": "hello",\n... "message": "Hi there",\n... "contact_email": "foo@example.com",\n... "urgent": True,\n... }\n>>> f = ContactForm(data)\n>>> print(f)\n<div><label for="id_subject">Subject:</label><input type="text" name="subject" value="hello" maxlength="100" required id="id_subject"></div>\n<div><label for="id_message">Message:</label><textarea name="message" cols="40" rows="10" required id="id_message">Hi there</textarea></div>\n<div><label for="id_contact_email">Contact email:</label><input type="email" name="contact_email" value="foo@example.com" maxlength="320" required id="id_contact_email"></div>\n<div><label for="id_urgent">Urgent:</label><input type="checkbox" name="urgent" id="id_urgent" checked></div>\nDenna standardutskrift omsluter varje fält med en <div>. Lägg märke till följande:
För flexibilitetens skull innehåller utdata inte taggarna<form>``` och `</form> eller taggen ``<input type="submit">. Det är ditt jobb att göra det.
Varje fälttyp har en standard HTML-representation. CharField representeras av en <input type="text"> och EmailField av en <input type="email">. BooleanField(null=False) representeras av en <input type="checkbox">. Observera att detta bara är förnuftiga standardvärden; du kan ange vilken HTML som ska användas för ett visst fält genom att använda widgets, som vi förklarar strax.
HTML-namnet för varje tagg hämtas direkt från attributnamnet i klassen ”ContactForm”.
The text label for each field – e.g. 'Subject:', 'Message:' and\n'Contact email:' is generated from the field name by converting all\nunderscores to spaces and upper-casing the first letter. Again, note\nthese are merely sensible defaults; you can also specify labels manually.
Varje textetikett omges av en HTML-tagg <label>, som pekar på lämpligt formulärfält via dess id. Dess id genereras i sin tur genom att fältnamnet kompletteras med 'id_. Attributen id och taggarna <label> inkluderas i utdata som standard, för att följa bästa praxis, men du kan ändra detta beteende.
Utdata använder HTML5-syntax, med <!DOCTYPE html> som mål. Exempelvis används booleska attribut som checked i stället för XHTML-stilen checked='checked'.
Även om <div> är standardutmatningsstilen när du skriver ut ett formulär kan du anpassa utmatningen genom att använda din egen formulärmall som kan ställas in för hela webbplatsen, per formulär eller per instans. Se återanvändbara-formulär-mallar.
Standardrenderingen när du printar ett formulär använder följande metoder och attribut.
template_nameLink to this heading#Namnet på den mall som återges om formuläret omvandlas till en sträng, t.ex. via print(form) eller i en mall via {{ form }}.
Som standard en egenskap som returnerar värdet av renderingsprogrammets form_template_name. Du kan ställa in det som ett strängmallnamn för att åsidosätta det för en viss formulärklass.
render()Link to this heading#Renderingsmetoden anropas av __str__ samt metoderna Form.as_div(), Form.as_table(), Form.as_p() och Form.as_ul(). Alla argument är valfria och standardvärdena är:
template_name: Form.template_name
context: Värde som returneras av Form.get_context()
renderer: Värde som returneras av Form.default_renderer
Genom att skicka template_name kan du anpassa den mall som används för bara ett enda anrop.
get_context()Link to this heading#Returnerar mallkontexten för rendering av formuläret.
\nDen tillgängliga kontexten är:
\n”Formulär”: Det bundna formuläret.
fält: Alla bundna fält, utom de dolda fälten.
hidden_fields: Alla dolda bundna fält.
fel: Alla formulärfel som inte är fältrelaterade eller som är relaterade till dolda fält.
template_name_labelLink to this heading#Den mall som används för att rendera ett fälts <label>, används vid anrop av BoundField.label_tag()/legend_tag(). Kan ändras per formulär genom att åsidosätta detta attribut eller mer generellt genom att åsidosätta standardmallen, se även Åsidosätta inbyggda formulärmallar.
Det rekommenderade tillvägagångssättet för att ändra formulärets utmatningsstil är att ange en anpassad formulärmall antingen för hela webbplatsen, per formulär eller per instans. Se Återanvändbara formulärmallar för exempel.
\nFöljande hjälpfunktioner tillhandahålls för bakåtkompatibilitet och är en proxy till Form.render() som skickar ett visst värde för template_name.
Varje helper parar ihop en formulärmetod med ett attribut som anger det lämpliga mallnamnet.
\nas_div()Link to this heading#Den mall som används av as_div(). Standard: 'django/forms/div.html'.
as_div() renderar formuläret som en serie av <div> element, där varje <div> innehåller ett fält, t.ex:
>>> f = ContactForm()\n>>> f.as_div()\n… gives HTML like:
\n<div>\n<label for="id_subject">Subject:</label>\n<input type="text" name="subject" maxlength="100" required id="id_subject">\n</div>\n<div>\n<label for="id_message">Message:</label>\n<textarea name="message" cols="40" rows="10" required id="id_message"></textarea>\n</div>\n<div>\n<label for="id_contact_email">Contact email:</label>\n<input type="email" name="contact_email" required id="id_contact_email">\n</div>\n<div>\n<label for="id_urgent">Urgent:</label>\n<input type="checkbox" name="urgent" id="id_urgent">\n</div>\nas_p()Link to this heading#Den mall som används av as_p(). Standard: 'django/forms/p.html'.
as_p() återger formuläret som en serie <p> taggar, där varje <p> innehåller ett fält:
>>> f = ContactForm()\n>>> f.as_p()\n… gives HTML like:
\n<p><label for="id_subject">Subject:</label> <input type="text" name="subject" maxlength="100" required id="id_subject"></p>\n<p><label for="id_message">Message:</label> <textarea name="message" cols="40" rows="10" required id="id_message"></textarea></p>\n<p><label for="id_contact_email">Contact email:</label> <input type="email" name="contact_email" maxlength="320" required id="id_contact_email"></p>\n<p><label for="id_urgent">Urgent:</label> <input type="checkbox" name="urgent" id="id_urgent"></p>\nas_ul()Link to this heading#Den mall som används av as_ul(). Standard: 'django/forms/ul.html'.
as_ul() renderar formuläret som en serie av <li> taggar, med varje <li> som innehåller ett fält. Den inkluderar *inte*<ul>``` eller `,</ul> så att du kan ange HTML-attribut på ``<ul> för flexibilitet:
>>> f = ContactForm()\n>>> f.as_ul()\n… gives HTML like:
\n<li><label for="id_subject">Subject:</label> <input type="text" name="subject" maxlength="100" required id="id_subject"></li>\n<li><label for="id_message">Message:</label> <textarea name="message" cols="40" rows="10" required id="id_message"></textarea></li>\n<li><label for="id_contact_email">Contact email:</label> <input type="email" name="contact_email" maxlength="320" required id="id_contact_email"></li>\n<li><label for="id_urgent">Urgent:</label> <input type="checkbox" name="urgent" id="id_urgent"></li>\nas_table()Link to this heading#Den mall som används av as_table(). Standard: 'django/forms/table.html'.
as_table() återger formuläret som en HTML <table>:
>>> f = ContactForm()\n>>> f.as_table()\n… gives HTML like:
\n<tr><th><label for="id_subject">Subject:</label></th><td><input type="text" name="subject" maxlength="100" required id="id_subject"></td></tr>\n<tr><th><label for="id_message">Message:</label></th><td><textarea name="message" cols="40" rows="10" required id="id_message"></textarea></td></tr>\n<tr><th><label for="id_contact_email">Contact email:</label></th><td><input type="email" name="contact_email" maxlength="320" required id="id_contact_email"></td></tr>\n<tr><th><label for="id_urgent">Urgent:</label></th><td><input type="checkbox" name="urgent" id="id_urgent"></td></tr>\nDet är ganska vanligt att formatera formulärrader och fält som är obligatoriska eller har fel. Du kanske till exempel vill presentera obligatoriska formulärrader i fetstil och markera fel i rött.
\nKlassen Form har ett par hooks som du kan använda för att lägga till class-attribut till obligatoriska rader eller till rader med fel: ställ in attributen Form.error_css_class och/eller Form.required_css_class:
from django import forms\n\n\nclass ContactForm(forms.Form):\n error_css_class = "error"\n required_css_class = "required"\n\n # ... and the rest of your fields here\nNär du har gjort det kommer raderna att få klasserna "error" och/eller "required", efter behov. HTML kommer att se ut ungefär som:
>>> f = ContactForm(data)\n>>> print(f)\n<div class="required"><label for="id_subject" class="required">Subject:</label> ...\n<div class="required"><label for="id_message" class="required">Message:</label> ...\n<div class="required"><label for="id_contact_email" class="required">Contact email:</label> ...\n<div><label for="id_urgent">Urgent:</label> ...\n>>> f["subject"].label_tag()\n<label class="required" for="id_subject">Subject:</label>\n>>> f["subject"].legend_tag()\n<legend class="required" for="id_subject">Subject:</legend>\n>>> f["subject"].label_tag(attrs={"class": "foo"})\n<label for="id_subject" class="foo required">Subject:</label>\n>>> f["subject"].legend_tag(attrs={"class": "foo"})\n<legend for="id_subject" class="foo required">Subject:</legend>\nDu kan ytterligare modifiera återgivningen av formulärrader genom att använda en custom BoundField.
\nSpecifies the renderer to use for the form.\nDefaults to None which means to use the default renderer specified by the\nFORM_RENDERER setting.
Du kan ange detta som ett klassattribut när du deklarerar ditt formulär eller använda argumentet renderer i Form.__init__(). Till exempel:
from django import forms\n\n\nclass MyForm(forms.Form):\n default_renderer = MyRenderer()\neller:
\nform = MyForm(renderer=MyRenderer())\nIn the as_p(), as_ul() and as_table() shortcuts, the fields are\ndisplayed in the order in which you define them in your form class. For\nexample, in the ContactForm example, the fields are defined in the order\nsubject, message, contact_email, urgent. To reorder the HTML\noutput, change the order in which those fields are listed in the class.
Det finns flera andra sätt att skräddarsy beställningen:
\nSom standard är Form.field_order=None, vilket innebär att den ordning som du definierar fälten i formulärklassen behålls. Om field_order är en lista med fältnamn ordnas fälten enligt listan och återstående fält läggs till enligt standardordningen. Okända fältnamn i listan ignoreras. Detta gör det möjligt att inaktivera ett fält i en underklass genom att ställa in det på None utan att behöva omdefiniera ordningen.
Du kan också använda argumentet Form.field_order till en Form för att åsidosätta fältordningen. Om en Form definierar field_order och du inkluderar field_order när du instansierar Form, så kommer den senare field_order att ha företräde.
Du kan omorganisera fälten när som helst med hjälp av order_fields() med en lista över fältnamn som i field_order.
Om du renderar ett bundet Form-objekt, kommer renderingen automatiskt att köra formulärets validering om det inte redan har skett, och HTML-utmatningen kommer att innehålla valideringsfelen som en <ul class="errorlist">.
Följande:
\n>>> data = {\n... "subject": "",\n... "message": "Hi there",\n... "contact_email": "invalid email address",\n... "urgent": True,\n... }\n>>> ContactForm(data).as_div()\n… gives HTML like:
\n<div>\n <label for="id_subject">Subject:</label>\n <ul class="errorlist" id="id_subject_error"><li>This field is required.</li></ul>\n <input type="text" name="subject" maxlength="100" required aria-invalid="true" aria-describedby="id_subject_error" id="id_subject">\n</div>\n<div>\n <label for="id_message">Message:</label>\n <textarea name="message" cols="40" rows="10" required id="id_message">Hi there</textarea>\n</div>\n<div>\n <label for="id_contact_email">Contact email:</label>\n <ul class="errorlist" id="id_contact_email_error"><li>Enter a valid email address.</li></ul>\n <input type="email" name="contact_email" value="invalid email address" maxlength="320" required aria-invalid="true" aria-describedby="id_contact_email_error" id="id_contact_email">\n</div>\n<div>\n <label for="id_urgent">Urgent:</label>\n <input type="checkbox" name="urgent" id="id_urgent" checked>\n</div>\nDjangos standardformulärsmallar kommer att associera valideringsfel med deras inmatning genom att använda HTML-attributet aria-describedby när fältet har ett auto_id och en anpassad aria-describedby inte tillhandahålls. Om ett anpassat aria-describedby anges när widgeten definieras kommer detta att åsidosätta standardvärdet.
Om widgeten återges i en <fieldset> läggs aria-describedby till i detta element, annars läggs det till i widgetens HTML-element (t.ex. <input>).
Som standard använder formulär django.forms.utils.ErrorList för att formatera valideringsfel. ErrorList är ett listliknande objekt där initlist är listan över fel. Dessutom har denna klass följande attribut och metoder.
De CSS-klasser som ska användas vid rendering av fellistan. Alla angivna klasser läggs till i standardklassen errorlist.
Specifies the renderer to use for\nErrorList. Defaults to None which means to use the default\nrenderer specified by the FORM_RENDERER setting.
Ett id för det fält som felen avser. Detta gör att ett HTML-attribut id kan läggas till i felmallen och är användbart för att associera felen med fältet. Standardmallen använder formatet id="{{ field_id }}_error" och ett värde tillhandahålls av Form.add_error() med hjälp av fältets auto_id.
Namnet på den mall som används vid anrop av __str__ eller render(). Som standard är detta 'django/forms/errors/list/default.html' som är en proxy för mallen 'ul.html'.
Namnet på den mall som används vid anrop av as_text(). Som standard är detta 'django/forms/errors/list/text.html'. Den här mallen återger felen som en lista med punkter.
Namnet på den mall som används vid anrop av as_ul(). Som standard är detta 'django/forms/errors/list/ul.html'. Denna mall återger felen i <li> taggar med en omslags <ul> med CSS-klasserna som definieras av error_class.
Returnerar kontext för återgivning av fel i en mall.
\nDen tillgängliga kontexten är:
\nerrors : En lista över fel.
error_class : En sträng med CSS-klasser.
Renderingsmetoden anropas av __str__ samt av metoden as_ul`().
Alla argument är valfria och kommer att användas som standard:
\ntemplate_name: Värde som returneras av template_name
context: Värde som returneras av get_context()
renderer: Värde som returneras av renderer
Renderar fellistan med hjälp av den mall som definieras av template_name_text.
Renderar fellistan med hjälp av den mall som definieras av template_name_ul.
Om du vill anpassa återgivningen av fel kan detta uppnås genom att åsidosätta attributet template_name eller mer allmänt genom att åsidosätta standardmallen, se även Åsidosätta inbyggda formulärmallar.
Metoderna as_p(), as_ul() och as_table() är genvägar - de är inte det enda sättet som ett formulärobjekt kan visas på.
Används för att visa HTML eller åtkomstattribut för ett enskilt fält i en Form-instans.
Metoden __str__() för detta objekt visar HTML för detta fält.
Du kan använda Form.bound_field_class och Field.bound_field_class för att ange en annan BoundField-klass per formulär respektive per fält.
Se Anpassa BoundField för exempel på åsidosättande av en BoundField.
Om du vill hämta ett enskilt BoundField använder du syntaxen för ordboksuppslagning i formuläret med fältets namn som nyckel:
>>> form = ContactForm()\n>>> print(form["subject"])\n<input type="text" name="subject" maxlength="100" required id="id_subject">\nFör att hämta alla BoundField-objekt, iterera formuläret:
>>> form = ContactForm()\n>>> for boundfield in form:\n... print(boundfield)\n...\n<input type="text" name="subject" maxlength="100" required id="id_subject">\n<textarea name="message" cols="40" rows="10" required id="id_message"></textarea>\n<input type="email" name="contact_email" maxlength="320" required id="id_contact_email">\n<input type="checkbox" name="urgent" id="id_urgent">\nDen fältspecifika utmatningen följer formulärobjektets inställning auto_id:
>>> f = ContactForm(auto_id=False)\n>>> print(f["message"])\n<textarea name="message" cols="40" rows="10" required></textarea>\n>>> f = ContactForm(auto_id="id_%s")\n>>> print(f["message"])\n<textarea name="message" cols="40" rows="10" required id="id_message"></textarea>\nBoundFieldLink to this heading#Returnerar en aria-describedby-referens för att associera ett fält med dess hjälptext och fel. Returnerar None om aria-describedby är inställt i Widget.attrs för att bevara det användardefinierade attributet när formuläret renderas.
HTML ID-attributet för denna BoundField. Returnerar en tom sträng om Form.auto_id är False.
Denna egenskap returnerar data för denna BoundField som extraherats av widgetens value_from_datadict()-metod, eller None om den inte gavs:
>>> unbound_form = ContactForm()\n>>> print(unbound_form["subject"].data)\nNone\n>>> bound_form = ContactForm(data={"subject": "My Subject"})\n>>> print(bound_form["subject"].data)\nMy Subject\nEtt listliknande objekt som visas som en HTML <ul class="errorlist"> när det skrivs ut:
>>> data = {"subject": "hi", "message": "", "contact_email": "", "urgent": ""}\n>>> f = ContactForm(data, auto_id=False)\n>>> print(f["message"])\n<input type="text" name="message" required aria-invalid="true">\n>>> f["message"].errors\n['This field is required.']\n>>> print(f["message"].errors)\n<ul class="errorlist"><li>This field is required.</li></ul>\n>>> f["subject"].errors\n[]\n>>> print(f["subject"].errors)\n\n>>> str(f["subject"].errors)\n''\nVid rendering av ett fält med fel kommer aria-invalid="true" att ställas in på fältets widget för att indikera att det finns ett fel för skärmläsaranvändare.
Formulärets Field-instans från den formulärklass som denna BoundField omsluter.
Den Form-instans som denna BoundField är bunden till.
Fältets help_text.
Det namn som kommer att användas i widgetens HTML-attribut name. Det tar hänsyn till formuläret prefix.
Använd den här egenskapen för att återge fältets ID. Till exempel: om du manuellt konstruerar en <label> i din mall (trots att label_tag()/legend_tag() gör detta åt dig):
<label for="{{ form.my_field.id_for_label }}">...</label>{{ my_field }}\nSom standard kommer detta att vara fältets namn med prefixet id_ (”id_my_field” i exemplet ovan). Du kan ändra ID genom att ställa in attrs på fältets widget. Till exempel:, om du deklarerar ett fält så här:
my_field = forms.CharField(widget=forms.TextInput(attrs={"id": "myFIELD"}))\noch med hjälp av mallen ovan, skulle rendera något liknande:
\n<label for="myFIELD">...</label><input id="myFIELD" type="text" name="my_field" required>\nAnvänd BoundField.initial för att hämta initialdata för ett formulärfält. Den hämtar data från Form.initial om den finns, annars försöker den Field.initial. Kallbara värden utvärderas. Se Initiala formvärden för fler exempel.
BoundField.initial cachar sitt returvärde, vilket är användbart särskilt när man har att göra med anropbara filer vars returvärden kan ändras (t.ex. datetime.now eller uuid.uuid4):
>>> from datetime import datetime\n>>> class DatedCommentForm(CommentForm):\n... created = forms.DateTimeField(initial=datetime.now)\n...\n>>> f = DatedCommentForm()\n>>> f["created"].initial\ndatetime.datetime(2021, 7, 27, 9, 5, 54)\n>>> f["created"].initial\ndatetime.datetime(2021, 7, 27, 9, 5, 54)\nUsing BoundField.initial is recommended over\nget_initial_for_field().
Returnerar True om widgeten i denna BoundField är dold.
Fältets label. Detta används i label_tag()/legend_tag().
Namnet på detta fält i formuläret:
\n>>> f = ContactForm()\n>>> print(f["subject"].name)\nsubject\n>>> print(f["message"].name)\nmessage\nNamnet på den mall som återges med BoundField.as_field_group().
En egenskap som returnerar värdet av template_name om det är inställt på annat sätt field_template_name.
Returnerar värdet på attributet use_fieldset för denna BoundField-widget.
Returnerar det gemena klassnamnet på det omslutna fältets widget, med eventuella efterföljande input eller widget borttagna. Detta kan användas när man bygger formulär där layouten är beroende av widget-typen. Exempelvis:
{% for field in form %}\n {% if field.widget_type == 'checkbox' %}\n # render one way\n {% else %}\n # render another way\n {% endif %}\n{% endfor %}\nBoundFieldLink to this heading#Renderar fältet med hjälp av BoundField.render() med standardvärden som renderar BoundField, inklusive dess etikett, hjälptext och fel med hjälp av mallens template_name om den är inställd annars field_template_name
Returnerar en HTML-sträng för att representera detta som en <input type="hidden">.
**kwargs skickas till as_widget().
Denna metod används främst internt. Du bör använda en widget istället.
\nRenders the field by rendering the passed widget, adding any HTML\nattributes passed as attrs. If no widget is specified, then the\nfield’s default widget will be used.
only_initial används av Django internals och bör inte ställas in explicit.
När du använder Djangos renderingsgenvägar används CSS-klasser för att ange obligatoriska formulärfält eller fält som innehåller fel. Om du manuellt renderar ett formulär kan du komma åt dessa CSS-klasser med hjälp av metoden css_classes:
>>> f = ContactForm(data={"message": ""})\n>>> f["message"].css_classes()\n'required'\nOm du vill tillhandahålla ytterligare klasser utöver de fel- och required-klasser som kan krävas, kan du ange dessa klasser som ett argument:
\n>>> f = ContactForm(data={"message": ""})\n>>> f["message"].css_classes("foo bar")\n'foo bar required'\nReturnerar mallkontexten för rendering av fältet. Den tillgängliga kontexten är field som är instansen för det bundna fältet.
Skapar en etikett för formulärfältet med hjälp av den mall som anges av Form.template_name_label.
Den tillgängliga kontexten är:
\nfield: Denna instans av BoundField.
innehåll: Som standard en konkatenerad sträng av BoundField.label och Form.label_suffix (eller Field.label_suffix, om inställt). Detta kan åsidosättas med argumenten contents och label_suffix.
attrs: En dict som innehåller for, Form.required_css_class och id. id genereras av fältets widget attrs eller BoundField.auto_id. Ytterligare attribut kan anges med argumentet attrs.
use_tag: En boolean som är True om etiketten har ett id. Om False utelämnas taggen i standardmallen.
tag: En valfri sträng för att anpassa taggen, standard är label.
För att separat rendera etikett-taggen för ett formulärfält kan du anropa dess metod label_tag():
>>> f = ContactForm(data={"message": ""})\n>>> print(f["message"].label_tag())\n<label for="id_message">Message:</label>\nOm du vill anpassa renderingen kan du göra det genom att åsidosätta attributet Form.template_name_label eller mer allmänt genom att åsidosätta standardmallen, se även Åsidosätta inbyggda formulärmallar.
Anropar label_tag() med tag='legend' för att rendera etiketten med <legend> taggar. Detta är användbart vid rendering av radio och flera kryssrutor widgets där <legend> kan vara mer lämpligt än en <label>.
Renderingsmetoden anropas av as_field_group. Alla argument är valfria och används som standard:
template_name: BoundField.template_name
kontext: Värde som returneras av BoundField.get_context()
renderer: Värde som returneras av Form.default_renderer
Genom att skicka template_name kan du anpassa den mall som används för bara ett enda anrop.
Använd den här metoden för att återge fältets råvärde så som det skulle återges av en Widget:
>>> initial = {"subject": "welcome"}\n>>> unbound_form = ContactForm(initial=initial)\n>>> bound_form = ContactForm(data={"subject": "hi"}, initial=initial)\n>>> print(unbound_form["subject"].value())\nwelcome\n>>> print(bound_form["subject"].value())\nhi\nBoundFieldLink to this heading#Definiera en anpassad BoundField-klass som ska användas när formuläret renderas. Detta har företräde framför BaseRenderer.bound_field_class på projektnivå (tillsammans med en anpassad FORM_RENDERER), men kan åsidosättas av Field.bound_field_class på fältnivå.
Om den inte definieras som en klassvariabel kan bound_field_class ställas in via argumentet bound_field_class i konstruktören Form eller Field.
For compatibility reasons, a custom form field can still override\nField.get_bound_field() to use a custom class, though any of the\nprevious options are preferred.
Du kanske vill använda en anpassad BoundField om du behöver komma åt ytterligare information om ett formulärfält i en mall och det inte räcker att använda en underklass av Field.
Om du till exempel har en GPSCoordinatesField och vill kunna få tillgång till ytterligare information om koordinaterna i en mall, kan detta implementeras enligt följande:
class GPSCoordinatesBoundField(BoundField):\n @property\n def country(self):\n """\n Return the country the coordinates lie in or None if it can't be\n determined.\n """\n value = self.value()\n if value:\n return get_country_from_coordinates(value)\n else:\n return None\n\n\nclass GPSCoordinatesField(Field):\n bound_field_class = GPSCoordinatesBoundField\nNu kan du få tillgång till landet i en mall med {{ form.coordinates.country }}.
Du kanske också vill anpassa standardrenderingen av formulärfältsmallen. Du kan t.ex. åsidosätta BoundField.label_tag() för att lägga till en anpassad klass:
class StyledLabelBoundField(BoundField):\n def label_tag(self, contents=None, attrs=None, label_suffix=None, tag=None):\n attrs = attrs or {}\n attrs["class"] = "wide"\n return super().label_tag(contents, attrs, label_suffix, tag)\n\n\nclass UserForm(forms.Form):\n bound_field_class = StyledLabelBoundField\n name = CharField()\nDetta skulle uppdatera standardrenderingen av formuläret:
\n>>> f = UserForm()\n>>> print(f["name"].label_tag)\n<label for="id_name" class="wide">Name:</label>\nFör att lägga till en CSS-klass till det omslutande HTML-elementet för alla fält kan en BoundField åsidosättas för att returnera en annan samling CSS-klasser:
class WrappedBoundField(BoundField):\n def css_classes(self, extra_classes=None):\n parent_css_classes = super().css_classes(extra_classes)\n return f"field-class {parent_css_classes}".strip()\n\n\nclass UserForm(forms.Form):\n bound_field_class = WrappedBoundField\n name = CharField()\nDetta skulle uppdatera formulärets rendering enligt följande:
\n>>> f = UserForm()\n>>> print(f)\n<div class="field-class"><label for="id_name">Name:</label><input type="text" name="name" required id="id_name"></div>\nAlternativt, för att åsidosätta klassen BoundField på projektnivå, kan BaseRenderer.bound_field_class definieras på en anpassad FORM_RENDERER:
mysite/renderers.pyfrom django.forms.renderers import DjangoTemplates\n\nfrom .forms import CustomBoundField\n\n\nclass CustomRenderer(DjangoTemplates):\n bound_field_class = CustomBoundField\nsettings.pyFORM_RENDERER = "mysite.renderers.CustomRenderer"\nAtt hantera formulär som har fälten FileField och ImageField är lite mer komplicerat än ett vanligt formulär.
För det första, för att ladda upp filer måste du se till att ditt <form> element korrekt definierar enctype som "multipart/form-data":
<form enctype="multipart/form-data" method="post" action="/foo/">\nFör det andra måste du binda filinformationen när du använder formuläret. Fildata hanteras separat från normal formulärdata, så när ditt formulär innehåller en FileField och ImageField måste du ange ett andra argument när du binder ditt formulär. Så om vi utökar vårt ContactForm så att det innehåller en ImageField som heter mugshot, måste vi binda de fildata som innehåller mugshot-bilden:
# Bound form with an image field\n>>> from django.core.files.uploadedfile import SimpleUploadedFile\n>>> data = {\n... "subject": "hello",\n... "message": "Hi there",\n... "contact_email": "foo@example.com",\n... "urgent": True,\n... }\n>>> file_data = {"mugshot": SimpleUploadedFile("face.jpg", b"file data")}\n>>> f = ContactFormWithMugshot(data, file_data)\nI praktiken anger du vanligtvis request.FILES som källa för fildata (precis som du använder request.POST som källa för formulärdata):
# Bound form with an image field, data from the request\n>>> f = ContactFormWithMugshot(request.POST, request.FILES)\nAtt konstruera ett obundet formulär är samma sak som alltid - utelämna både formulärdata och fildata:
\n# Unbound form with an image field\n>>> f = ContactFormWithMugshot()\nOm du skriver återanvändbara vyer eller mallar kanske du inte vet i förväg om ditt formulär är ett flerdelat formulär eller inte. Metoden is_multipart() talar om för dig om formuläret kräver multipart-kodning för inlämning:
>>> f = ContactFormWithMugshot()\n>>> f.is_multipart()\nTrue\nHär är ett exempel på hur du kan använda detta i en mall:
\n{% if form.is_multipart %}\n <form enctype="multipart/form-data" method="post" action="/foo/">\n{% else %}\n <form method="post" action="/foo/">\n{% endif %}\n{{ form }}\n</form>\nOm du har flera Form-klasser som delar fält kan du använda subklassning för att ta bort redundans.
När du subklassar en anpassad Form-klass kommer den resulterande subklassen att innehålla alla fält i den eller de överordnade klasserna, följt av de fält som du definierar i subklassen.
In this example, ContactFormWithDepartment contains all the fields from\nContactForm, plus an additional field, department. The ContactForm\nfields are ordered first:
>>> class ContactFormWithDepartment(ContactForm):\n... department = forms.CharField()\n...\n>>> f = ContactFormWithDepartment(auto_id=False)\n>>> print(f)\n<div>Subject:<input type="text" name="subject" maxlength="100" required></div>\n<div>Message:<textarea name="message" cols="40" rows="10" required></textarea></div>\n<div>Contact email:<input type="email" name="contact_email" required></div>\n<div>Urgent:<input type="checkbox" name="urgent"></div>\n<div>Department:<input type="text" name="department" required></div>\nDet är möjligt att subklassa flera formulär och behandla formulär som mixins. I det här exemplet är BeatleForm en underklass till både PersonForm och InstrumentForm (i den ordningen), och dess fältlista innehåller fälten från de överordnade klasserna:
>>> from django import forms\n>>> class PersonForm(forms.Form):\n... first_name = forms.CharField()\n... last_name = forms.CharField()\n...\n>>> class InstrumentForm(forms.Form):\n... instrument = forms.CharField()\n...\n>>> class BeatleForm(InstrumentForm, PersonForm):\n... haircut_type = forms.CharField()\n...\n>>> b = BeatleForm(auto_id=False)\n>>> print(b)\n<div>First name:<input type="text" name="first_name" required></div>\n<div>Last name:<input type="text" name="last_name" required></div>\n<div>Instrument:<input type="text" name="instrument" required></div>\n<div>Haircut type:<input type="text" name="haircut_type" required></div>\nDet är möjligt att deklarativt ta bort ett Field som ärvts från en överordnad klass genom att ställa in namnet på fältet till None i underklassen. Ett exempel:
>>> from django import forms\n\n>>> class ParentForm(forms.Form):\n... name = forms.CharField()\n... age = forms.IntegerField()\n...\n\n>>> class ChildForm(ParentForm):\n... name = None\n...\n\n>>> list(ChildForm().fields)\n['age']\nDu kan lägga in flera Django formulär i en <form> tagg. För att ge varje Form sitt eget namnområde, använd nyckelordsargumentet prefix:
>>> mother = PersonForm(prefix="mother")\n>>> father = PersonForm(prefix="father")\n>>> print(mother)\n<div><label for="id_mother-first_name">First name:</label><input type="text" name="mother-first_name" required id="id_mother-first_name"></div>\n<div><label for="id_mother-last_name">Last name:</label><input type="text" name="mother-last_name" required id="id_mother-last_name"></div>\n>>> print(father)\n<div><label for="id_father-first_name">First name:</label><input type="text" name="father-first_name" required id="id_father-first_name"></div>\n<div><label for="id_father-last_name">Last name:</label><input type="text" name="father-last_name" required id="id_father-last_name"></div>\nPrefixet kan också anges på formulärklassen:
\n>>> class PersonForm(forms.Form):\n... ...\n... prefix = "person"\n...\n