HTML – Native Form 原生表单功能集
前言
以前写过 form 表单, 但很不齐全, 这篇想做一个大整理. 主要讲讲在网站中使用原生 Form 的功能, 不足和扩展.
前端是原生的 HTML/JS, 后端是 ASP.NET Core Razor Pages.
Simplest Form Overview
form 的职责是让 user 可以把信息传递到服务端. 常见的使用场景是 contact / enquiry form.
结构大概长这样
<form method="post"> <input type="text" name="username"> <button type="submit">Submit</button> </form>
一个 form tag 把所有信息包裹在里面
input text 作为 accessor 信息读写器. 还有很多种 accessor 用来输出输入不同种类的信息. 后面会详细讲到.
一个 submit button.
ASP.NET Core
public class FormData { public string Username { get; set; } = ""; } public class IndexModel : PageModel { public void OnGet() { } public void OnPost([FromForm] FormData formData) { var value = formData.Username; } }
一个对象从 form 获取信息, 然后就可以做各做操作了, 比如存入数据库, 发电邮等等.
Form Attribute
form 有 3 个常用的 attribute
method
有 3 种 get, post, dialog
get 我没有用过, 也不知道什么时候会用到.
post 是每次用的
dialog 很新, Safari 15.4 (14-03-2022) 才支持, 我没有用过这篇就不介绍了 (看这篇)
action
action 用来声明 post 去服务端的地址. 没有填写的话就是和当前页面相同地址.
比如 current url : /contact, 那么就是 post to /contact
Razor Pages 注意事项
在 Razor Pages, 如果 post to other page 需要加多一个 attribute asp-antiforgery, 不然会报错 400 error 哦, 详情可以看这篇 ASP.NET Core – CSRF
<form method="post" action="/other-page" asp-antiforgery="true">
在 Razor Pages, 如果 post to same page 但不同 method 的话, 要添加 query params handler
<form method="post" action="?Handler=ExternalLogin" asp-antiforgery="true">
注: 直接添加 handler 会把其它 query params 给覆盖掉哦. 更好的方式是用 QueryHelpers 和 QueryBuilder 做一个完整的
enctype
声明 form 的格式, 类似 Content-Type
application/x-www-form-urlencoded (默认): 信息会以 key-value encodeURIComponent 方式发送出去, 这个格式不支持文件上传哦.
multipart/form-data: 想上传文件就要用这个 (即使没有文件也是可以用的, 只是会有一些多余的信息, 比如分隔符号, 那个是为了 upload file 才需要的)
例子
<form action="/" method="post" enctype="multipart/form-data" asp-antiforgery="true"> <input type="text" name="username"> <input type="file" name="attachment"> <input type="submit" value="Submit"> </form>
ASP.Net Core
public class FormData { public string Username { get; set; } = ""; public IFormFile Attachment { get; set; } = null!; } public class IndexModel : PageModel { public void OnGet() { } public void OnPost([FromForm] FormData formData) { var value = formData.Username; var fileSize = formData.Attachment.Length; } }
Form Submission
Submit Button
<button>Submit</button> <button type="submit">Submit</button> <input type="submit" value="Submit">
这 3 个效果是一样的.
button 默认的 type 就是 submit, 所以 1 和 2 是一样的.
input:submit 和 button 也是一样的, style 都一样.
通常我会用第 2 个. 比较明确.
multiple button in form
复杂的 form 里面会有多个 button 出现. 但通常只会有一个用来 submit.
所以其余的记得要写上 type="button".
input enter trigger submit button click
在任何一个 input (accessor) 按 enter 键, 游览器会找到 form 里面第一个 submit button (type=submit / image / no defined) 点击.
multiple submit button
一个常见的例子是让用户做简单的选择提交. 比如 external login.
<form method="post"> <button type="submit" name="provider" value="Google">Login with Google</button> <button type="submit" name="provider" value="Microsoft">Login with Microsoft Account</button> </form>
在 button 声明 name 和 value, 用户点击后, 被点击的那一个 submit value 会被放入信息中, 一起发送出去
还有一个用法是这样
<form method="post"> <input type="text" name="dataName"> <button type="submit" name="deleteType" value="SoftDelete">Soft Delete Data</button> <button type="submit" name="deleteType" value="HardDelete">Hard Delete Data</button> </form>
这个比较少见. 而且交互有点复杂. 不鼓励使用.
ASP.NET Core
public enum DeleteType { SoftDelete, HardDelete } public class FormData { public string? DataName { get; set; } public DeleteType? DeleteType { get; set; } } public class IndexModel : PageModel { public void OnGet() { } public void OnPost([FromForm] FormData formData) { } }
listen to submission event
通过 JS 可以拦截 submit event
document.querySelector("form").addEventListener("submit", (e) => {
e.preventDefault();
alert("submit");
});
通过 preventDefault 可以阻止游览器发送到服务端. 通常目的是想改成使用 Ajax 发送, 下面会说到细节.
JS trigger submission
document.querySelector("form").submit();
document.querySelector("form").dispatchEvent(new Event("submit"));
.submit() 不会触发 submission event, 它会直接发送到服务端.
相反, dispatch 只会触发 submit event, 而不会发送到服务端 (不管有没有 prevent default).
所以 2 个的用法是不同的哦, 要依据场景来运用. 一般上 Ajax Form 会用 dispatchEvent, 刷新 form 会用 .submit().
Ajax Form
所谓 Ajax Form 就是替代原本的 form submit 刷新体验, 改成通过 Ajax 发送 form 的信息.
XMLHttpRequest
这是平常用来发 Ajax 的方式, Content-Type: application/json
var request = new XMLHttpRequest(); request.onreadystatechange = () => { if (request.readyState == 4 && request.status == 200) { alert("done"); } }; request.open("POST", "/api/create-enquiry"); request.setRequestHeader("Content-Type", "application/json"); const dataJson = JSON.stringify({ username: "Derrick" }); request.send(dataJson);
ASP.NET Core
public class CreateEnquiryData { public string Username { get; set; } = ""; } public class EnquiryController { [HttpPost("api/create-enquiry")] public void CreateEnquiry([FromBody] CreateEnquiryData createEnquiryData) { } }
form 的话, 它不是 JSON
request.open("POST", "/api/create-enquiry");
const searchParams = new URLSearchParams({ username: "Derrick" });
request.send(searchParams);
直接发送 URLSearchParams 相等于是 application/x-www-form-urlencoded.
multipart/form-data 则是发送 FormData
request.open("POST", "/api/create-enquiry");
const formData = new FormData();
formData.append("username", "Derrick");
request.send(formData);
注:
1.在发送 URLSearchParams 和 FormData 时, 不要去设置 Content-Type Header, 游览器会依据类型自动设定好. 诺我们自己去设置反而会破坏掉游览器的机制, 比如 FormData 会自动创建分隔符, 如果手动设置 Content-Type 则不会.
2.JSON 则需要手动设置 Content-Type, 不然会是 text/plain.
3. 小总结
<form> 必须去手动设置 application/x-www-form-urlencoded 或者 multipart/form-data
JSON 必须手动设置 application/json
request.send(formData or searchParams) 不要手动设置, 让游览器自己判断.
FormData From Form Tag
const formData = new FormData(document.querySelector("form"));
直接把 element 丢进去就可以了. (注: disabled 的 input 会自动过滤掉, 不会放入 FormData 的 key value 里)
要添加额外的信息也可以
formData.append('extraInfo', 'value');
有一种 upload 体验是这样的
它的原理是 HTML file 不要放 name, 这样它就排除在 submit 信息里
然后用 JS 去拦截它, 存取来
const files = []; document.querySelector('input[type="file"]').addEventListener("input", (e) => { files.push(e.target.files[0]); // save the file });
最后, 通过 extra info 的方式 append 进去 formData
const formData = new FormData(document.querySelector("form")); for (const file of files) { formData.append("Attachments", file); } request.send(formData);
ASP.NET Core
public class CreateEnquiryData { public string Username { get; set; } = ""; public List<IFormFile> Attachments { get; set; } = new List<IFormFile>(); } public class EnquiryController { [HttpPost("api/create-enquiry")] public void CreateEnquiry([FromForm] CreateEnquiryData createEnquiryData) { } }
FormData value
FormData 的 value 只能是 string | File
通常服务端会 convert from string, 比如 parse string number, parse string date
另外, ASP.NET Core parse boolean 是 "True", "False", 而不是 "0", "1" 哦.
Accessor
原生 form accessor 虽然挺多的, 但是一般上网站的 form 不会太复杂 (不像 control panel), 所以常用到的就那几个.
input: text, email, number, date, checkbox, file
textarea, select
radio group
checkbox group
input text
<input type="text" name="username" autofocus autocomplete="on" readonly disabled placeholder="e.g. example.com">
排除 validation attribute (下面会详细讲 validation part), 常用的 attribute 有
autofocus 进入页面后自动 focus 到当前的 input
autocomplete 游览器会缓存之前填写过的记入, name, phone, email, address 都会, 如果不希望这样就通过 off 把它关掉, 也可以直接在 <form autocomplete="off" > 把所有的关掉.
readonly & disabled
这 2 个共同点是让用户只能看无法修改, 比较大的区别是 readonly 的信息会提交到服务端, 而 disabled 则不会. (注: select 是没有 readonly 的哦).
另外 CSS display none 只能让元素看不到, 依然会提交到服务端哦, 只有 disabled 或者把 name 去掉才能阻止提交.
placeholder 用来写提示的
maxlength 通过 UI 限制 value length, 注: 它不是 validation 哦, 如果通过 JS input.value = 'value' 是可以超过 max length 的, 而且 submit 也不会有 validation error.
size 用来设置 input 的 width, size="4" 不等于 style: 4ch 哦, 游览器有自己的算法, 大约是 8ch.
input text + datalist
类似 autocomplete 的效果, 但是资料由自己设定而不是游览器缓存.
<input list="browsers"> <datalist id="browsers"> <option value="Internet Explorer"> <option value="Firefox"> <option value="Chrome"> <option value="Opera"> <option value="Safari"> </datalist>
input email
email 的特色就是自动加了一个 email 的 validation, 其余的和 text 一样.
input number
number 限制了 value 只能是数字, a-z, 符号都不能输入, JS input.value 也输入不了. 但它接收 e, 因为这个是合格的数字, 但大部分情况业务是不允许 e 的.
右边多了一个上下箭头, 可以 increase 和 decrease value, 很方便
step 设置上下箭头按一下 +- 多少. 比如 step="30" 那么按 2 下加 value 就是 60.
input date
min, max 限制 UI 不能选大过或效果 min, max, 同时 validation 不允许大过或小过 min, max.
注: 限制往往有 2 种方式, 一种是 block from UI, 操作上无法输入不允许的值, 另一种是 validation, 可以输入, 但是提交的时候会 error.
注: date format 是 yyyy-mm-dd 只支持一种 format, 输入其它的会被无视. 参考这篇
input file
multiple 允许一次 select 多个文件
accept 支持的类型, 常用的有:
<input type="file" name="attachment" accept="image/png, image/jpeg, image/*, .sql">
用逗号做分隔符 (可以放空格, 比较好看, 它会清掉的), 也可以写 extension 哦
textarea
<textarea name="text" cols="20" rows="2"></textarea>
rows, cols 类似 input 的 size, 用来控制 width, height
textarea 默认是可以 resize 的, 想关掉可以通过 CSS style resize:none; 或者 vertical / horizontal 表示只允许某一边 resize.
select
<select name="cars"> <option value="">--Select--</option> <optgroup label="Swedish Cars"> <option value="volvo">Volvo</option> <option value="saab">Saab</option> </optgroup> <optgroup label="German Cars"> <option value="mercedes">Mercedes</option> <option value="audi">Audi</option> </optgroup> </select>
select 有几个局限, 所以不是很好用, 如果内容不多建议用 radio group 替代.
1. --select-- 由于它不能 cancel 所以只能通过一个 select empty 让用户清空.
2. value must be string, 不接受 null, number
3. multiple 在 PC 很丑, 手机还可以
4. search 体验差
checkbox
<input type="checkbox" name="rememberMe" value="True" checked>
for ASP.NET Core value 放 "True" 去到 C# 会 binding 成 bool. 当 checked 时, 它才会有 key 传到服务器. 所以服务端不可以 set default true 哦.
radio group
<input type="radio" id="html" name="fav_language" value="HTML"> <label for="html">HTML</label><br> <input type="radio" id="css" name="fav_language" value="CSS"> <label for="css">CSS</label><br> <input type="radio" id="javascript" name="fav_language" value="JavaScript"> <label for="javascript">JavaScript</label>
same name 表示 same group, 最终被选中的 radio 会成为唯一的 fav_language 值
checkbox group
<input type="checkbox" name="phones" value="iPhone"> <input type="checkbox" name="phones" value="HuaWei">
当多选时, 最终的会有多个 phones key-vlaue, 游览器其实并没有正真的 checkbox group, 它只是允许放重复名字的 checkbox 而已.
ASP.NET Core 会把这些放入 List 中
public class FormData { public List<string> Phones { get; set; } = new List<string>(); }
Semantic HTML
参考: MDN – How to structure a web form
所有内容包裹在 form 里, form 不要嵌套 (以前好像 ok, 现在不鼓励了)
<form></form>
分组使用 section
<form> <section> <h2>Contact Information</h2> <!-- accessor here --> </section> <section> <h2>Contact Information</h2> <!-- accessor here --> </section> <p><button type="submit">Submit</button></p> </form>
submit button 用 p 抱着. 如果没有分组则可以不需要 section (不过我觉得 p > button 感觉怪怪的)
accessor 和 label 用 p 包裹 (也有人用 div 或者 ul > li 来包, Exabyte 是用 p 哦)
参考: stackoverflow1 和 stackoverflow2
<p> <label for="number"> <span>Card number:</span> <strong><abbr title="required">*</abbr></strong> </label> <input type="tel" id="number" name="cardnumber"> </p>
input, select 做法一样.
radio, checkbox list 用 fieldset > ul > li
<fieldset> <legend>Title</legend> <ul> <li> <label for="title_1"> <input type="radio" id="title_1" name="title" value="K"> King </label> </li> <li> <label for="title_2"> <input type="radio" id="title_2" name="title" value="Q"> Queen </label> </li> <li> <label for="title_3"> <input type="radio" id="title_3" name="title" value="J"> Joker </label> </li> </ul> </fieldset>
fieldset 长这样, 一个大筐筐加一个 legend title
Validation
参考: W3Schools – JavaScript Validation API
Overview
validation 的玩法大概是这样:
1. 声明条件, 比如在 input 写上 required, pattern="\d" type="number | email" 这些都是条件.
2. 游览器会依据条件来限制用户的输入, 比如 type="number" keydown 不接受 a-z (除了 e) 和符号.
3. 除了阻止用户输入, 另一种方式是 popup error message 告诉用户虽然你成功输入了值, 但值我不接受请你修改, 不然就无法提交.
虽然游览器 build-in 了许多条件, 限制，验证 error, 但依然满足不了所有的需求, 所以我们可以通过 JS 去完善它.
manual trigger validation
虽然可以 manual trigger, 但有些时候会失灵, 比如 minlength, maxlength 只能通过 UI 才会有 error (挺奇葩的)
const valid = input.checkValidity(); // boolean
get error message
console.log(input.validationMessage);
set error or error message
不管是 custom error 还是想修改原本的 error message 都可以用这个接口
input.setCustomValidity('error message');
popup error message
input.reportValidity();
check validation state
console.log('input.validity', input.validity); // validation info
所有条件都在这里了
interface ValidityState { readonly badInput: boolean; readonly customError: boolean; readonly patternMismatch: boolean; readonly rangeOverflow: boolean; readonly rangeUnderflow: boolean; readonly stepMismatch: boolean; readonly tooLong: boolean; readonly tooShort: boolean; readonly typeMismatch: boolean; readonly valid: boolean; readonly valueMissing: boolean; }
badInput input type="number" UI 输入 e 就会是 badInput. 但是 input.value = 'e' 这样是输入不到值的哦, 只有通过 UI 才可以输入 e.
customError 如果有调用 setCustomValidity 就会是 true
patternMismatch 对应 pattern=“\d” input text 的正则验证
rangeOverflow 和 rangeUnderflow 对应 min, max (date or number)
stepMismatch 对应 type="number" step="20" value="18"
tooLong 和 tooShort 对应 maxlength 和 minlength
typeMismatch 对应 type="email"
valueMissing 对应 required。
注: badInput 和 valueMissing 是可能同时发生的，比如 input type number 输入 'e'
由于格式不对，所以 badInput = true，同时格式不对会导致 value = empty，所以 valueMissing 也等于 true。
valid 表示是否全部条件都满足，valid 和 checkValidity 的区别是 checkValidity 会 trigger invalid event，而 valid 只是一个属性。
注: 这些 value 都是 live 的哦, 并不需要调用 checkValidity()。比如我突然 required = true; valueMissing 会立马变成 true，valid 会立马变成 false。
奇葩现象
有时候 validation 会失灵, 唯一确保它可以跑的方式是通过 UI 去操作. JS 输入值会有许多奇葩现象:
JS 无法输入 e
const input = document.createElement('input');
input.type = 'number';
input.value = 'e';
console.log(input.value); // ''
console.log(input.valueAsNumber); // 'NaN'
UI 是可以输入 e 的, 但是会 badInput
stepMismatch 完全正常
const input = document.createElement('input');
input.type = 'number';
input.step = '20';
input.value = '19';
console.log('validity', input.validity.stepMismatch); // true
甚至不需要调用 checkValidity
typeMismatch 完全正常
const input = document.createElement('input');
input.type = 'email';
input.value = 'abc';
console.log('validity', input.validity.typeMismatch); // true
tooShort, tooLong 完成失灵
const input = document.createElement('input');
input.type = 'text';
input.minLength = 3;
input.maxLength = 5;
input.value = 'a';
console.log('validity', input.validity.tooShort); // false
input.value = '123456';
console.log('validity', input.validity.tooLong); // false
input.checkValidity();
console.log(input.value); // 123456
console.log('validity', input.validity.tooLong); // false
如果通过 UI 操作的话是可以弄出 error 的.
替换 error message
原生的 error message 有 3 个大问题,
language problem
它依据游览器的设置来提供语言, 但通常网站的语言是通过 URL 控制的.
consistency problem
不同游览器出的 error message 是不同的. 统一管理会比较方便
checkbox group no build-in
上面有提到, checkbox list 是没有 build-in 的, 它只是没有阻止你 multiple same name 而已
如果想做一个 required 它就不会像 radio group 那样. 所以只能自己处理.
Bootstrap 有 2 种 validation, 一种是原生, 一种是完全用它的 custom
但它的原生也是支持 set error message 的. 由此推断这是很 popular 的需求.
拦截 input event 然后判断当前 validity state 再通过 setCustomValidaity 替换掉 message.
input.setCustomValidity('error message');
注: 如果遇到 conditional validation，那还需要用到 MutationObserver 监听 attribute 变化，比如 required 等等。
ASP.NET Core form string empty become null
踩到一个坑, 前端 submit form string value = '' empty string, 后端接收以后变成了 null
原来是 [FromForm] 搞的鬼, JSON 则不会.
参考:
Asp.Net Core Model binding, how to get empty field to bind as a blank string?
Handling multipart requests with JSON and file uploads in ASP.NET Core
ConvertEmptyStringToNull stopped being honored after upgrading from RC1
2 个 solution, 一个是在 property 上面加 attribute
public class FormData { [DisplayFormat(ConvertEmptyStringToNull = false)] public string Name { get; set; } = ""; }
另一个是在 Program.cs 配置 MvcOptions (参考上面的链接, 这个动作很大, 不推荐)
