Skip to content
FEE
Frontend Engineering Essentials
Mid Level

[FEE-113] Autocomplete 屬性 Token 對照 ​

INFO

HTML 的 autocomplete 屬性接受以空白分隔的 token 列表,遵循嚴格的順序文法:可選的 section-*、可選的 shipping 或 billing、可選的聯絡類型、必要的 field-name,以及可選的 webauthn 憑證提示。只有 field-name token 是必要的;其他 token 若出現,MUST 依照規定順序排列。將 webauthn 與 username 一同加入,可讓 <input> 在搭配 navigator.credentials.get({ mediation: 'conditional' }) 時成為 passkey Conditional UI 的進入點。本文彙整每個 field-name token、說明分組前綴,並記錄 passkey 整合方式。

背景 ​

WHATWG HTML Living Standard 將 autocomplete 定義為以空白分隔的 token 列表,並規定嚴格順序:[section-*] [shipping|billing] [home|work|mobile|fax|pager] field-name [webauthn]。規範描述此結構為「可選的 section 前綴:section-*;可選的模式:shipping 或 billing;可選的聯絡類型:home、work、mobile、fax 或 pager;Field name(必要);可選的憑證類型:webauthn。」

若 token 順序錯亂便落在文法之外,瀏覽器會將該屬性視為 autofill-unspecified,悄悄丟棄語意提示。field-name token 承載主要訊號;周圍的 token 則細化此欄位所屬的地址、電話或帳號脈絡。

視覺對比 ​

位置Token 類別必要允許值
1Section 前綴否任何 section-* token(不分大小寫;後綴任意)
2地址模式否shipping、billing
3聯絡類型否home、work、mobile、fax、pager
4Field name是field-name 目錄中的一個 token(見 Token 對照表)
5憑證類型否webauthn

範例 ​

單一欄位的最小 autofill 提示只使用 field-name token:

html
<label>
  First name
  <input type="text" name="first" autocomplete="given-name" />
</label>

分組表單使用 section-* 前綴,讓瀏覽器能在同一頁面上區分兩組地址,並搭配模式限定詞:

html
<fieldset>
  <legend>Primary billing address</legend>
  <input autocomplete="section-user1 billing postal-code" name="billing-zip" />
  <input autocomplete="section-user1 billing country" name="billing-country" />
</fieldset>

<fieldset>
  <legend>Secondary billing address</legend>
  <input autocomplete="section-user2 billing postal-code" name="alt-billing-zip" />
  <input autocomplete="section-user2 billing country" name="alt-billing-country" />
</fieldset>

參與 passkey Conditional UI 的登入欄位同時帶有 username 與 webauthn,頁面再以 conditional mediation 呼叫 navigator.credentials.get(),請求保持 pending 直到使用者從 autofill 選單挑選憑證:

html
<form id="login">
  <label>
    Username
    <input name="username" autocomplete="username webauthn" />
  </label>
  <label>
    Password
    <input name="password" type="password" autocomplete="current-password" />
  </label>
</form>
js
if (window.PublicKeyCredential &&
    PublicKeyCredential.isConditionalMediationAvailable) {
  const available = await PublicKeyCredential.isConditionalMediationAvailable();
  if (available) {
    const credential = await navigator.credentials.get({
      mediation: 'conditional',
      publicKey: {
        challenge: new Uint8Array(challengeFromServer),
        // allowCredentials left empty for discoverable credentials
      },
    });
    // The promise stays pending until the user picks a passkey in the autofill sheet.
    verifyOnServer(credential);
  }
}

最佳實踐 ​

  • MUST 在登入表單上將識別欄位的 autocomplete="username" 與密碼欄位的 autocomplete="current-password" 配對。web.dev 記錄在現代瀏覽器中,username 是密碼管理器在 email 型識別欄位上辨識的 token,而 current-password 則是密碼輸入框上的搭配。
  • MUST 在註冊與變更密碼欄位使用 autocomplete="new-password",讓密碼管理器建議產生新憑證並避免填入目前的密碼。MDN:「新密碼。建立新帳號或變更密碼時,應在『輸入新密碼』或『確認新密碼』欄位使用此值。」
  • SHOULD 在「管理員為其他使用者設定密碼」頁面上,以 autocomplete="new-password" 取代 autocomplete="off" 來抑制 autofill。MDN 的安全指引指出:「若你設計一個使用者管理頁面,讓使用者可為他人指定新密碼,並希望阻止密碼欄位被自動填入,可使用 autocomplete=\"new-password\"。」
  • SHOULD 將憑證欄位上的 autocomplete="off" 視為非強制性請求。MDN 指出:「若網站在 <form> 元素上設定 autocomplete=\"off\",且表單包含 username 與 password 輸入欄位,瀏覽器仍會提議記住這組登入資訊。」密碼管理器會在登入流程上刻意覆寫 off,以 off 作為安全手段並不可行。
  • MAY 結合 section-*、shipping 或 billing 以及聯絡類型 token,在同一頁面內區分多組地址或電話欄位。

深入探討 ​

Token 只是瀏覽器參考的訊號之一。Safari 特別會在輸入欄位的 name、placeholder 與 label 之上疊加啟發式,並依此順序評估。Cloudfour 的 autofill 文章記錄:「Safari 使用啟發式偵測要採用的 autofill 值,且執行得相當積極。Safari 並未僅依賴標準化屬性,而是依下列順序評估輸入欄位的屬性:name、placeholder、label。」

實務上的後果為:具 autocomplete="one-time-code" 但 name="email" 的欄位在 Safari 中仍可能觸發 email autofill,因為啟發式的權重高於 token。防禦性的作者會讓 name 屬性與 field-name token 在語意上保持一致(autocomplete="one-time-code" 配 name="otp"、autocomplete="current-password" 配 name="current-password"),並避免 placeholder 描述與 token 宣告不同的欄位。

Token 對照表 ​

field-name token 取自 WHATWG 目錄。以下表格依領域分組整理,所有 token 皆不分大小寫,且都列於 MDN 的參考清單中。

Identity ​

Token預期格式備註
name完整法定姓名儘量採用拆分的姓名 token
honorific-prefix「Mr.」、「Ms.」、「Dr.」
given-name名
additional-name中間名
family-name姓
honorific-suffix「Jr.」、「III」、「PhD」
nickname顯示名稱
username帳號識別登入時與 current-password 配對;passkey Conditional UI 必要
organization-title職稱
organization公司名稱

Credentials ​

Token預期格式備註
new-password明文密碼用於註冊與變更密碼流程;也是推薦的抑制提示
current-password明文密碼登入流程;與 username 配對
one-time-code數字 OTPiOS/macOS Safari 12+ 會解析收到的 SMS 並在鍵盤建議中提供驗證碼;Android Chrome 則使用獨立的 WebOTP API

Contact ​

Token預期格式備註
tel完整電話號碼可結合 home/work/mobile/fax/pager 限定
tel-country-code「+1」、「+44」
tel-national國內格式電話
tel-area-code區碼
tel-local本地號碼部分
tel-extension分機號碼
email電子郵件地址可結合 home/work 限定
impp即時通訊 URL
url首頁 URL
photo頭像 URL

Postal address ​

Token預期格式備註
street-address多行街道地址
address-line1第一行街道
address-line2第二行街道
address-line3第三行街道
address-level4最細的行政層級
address-level3第三層行政區
address-level2市或地區
address-level1州或省
countryISO 3166-1 alpha-2 國家代碼
country-name人類可讀的國家名稱
postal-codeZIP 或郵遞區號

Payment ​

Token預期格式備註
cc-name卡片上姓名
cc-given-name卡片上名
cc-additional-name卡片上中間名
cc-family-name卡片上姓
cc-number卡號
cc-exp到期日,格式為 MM/YY 或 MM/YYYY
cc-exp-month到期月份數字
cc-exp-year到期年份數字
cc-csc卡片安全碼
cc-type卡片發行網路名稱

Transaction ​

Token預期格式備註
transaction-currencyISO 4217 貨幣代碼
transaction-amount小數金額

Demographics ​

Token預期格式備註
bdayYYYY-MM-DD
bday-day日期數字
bday-month月份數字
bday-year年份數字
sex自由字串
languageBCP 47 語言標記

section-*、shipping、billing 以及聯絡類型 token 並不替代 field-name token,而是疊加於其上。MDN 將 section token 描述為「前八個字元為字串 'section-'(不分大小寫)、後接額外字元的 token。凡以相同 token 開頭的表單控制項皆屬於該命名群組。」模式 token 則限定後續內容:「shipping:由後續 token 識別的欄位屬於 shipping 地址或聯絡資訊。billing:由後續 token 識別的欄位屬於 billing 地址或聯絡資訊。」聯絡類型 token(home、work、mobile、fax、pager)則限定電話與電子郵件欄位。

Passkey Conditional UI(webauthn token) ​

webauthn token 是文法末端的憑證提示。WHATWG 規範描述:「可選的 token……代表字串 'webauthn',表示 user agent 應透過 conditional mediation 顯示可用的 public key credentials……webauthn 僅對 input 與 textarea 元素有效。」實務上此 token 只在 <input> 上有意義,因為 Conditional UI 會在 username 欄位的標準 autofill 選單旁顯示 passkey。

使用時機:任何支援 passkey 的登入或帳號復原頁面。整合分為兩部分。HTML 以空白分隔同時帶上兩個 token:

html
<input name="username" autocomplete="username webauthn" />

腳本以 mediation: 'conditional' 呼叫 navigator.credentials.get()。web.dev 記錄此行為:「以 mediation: 'conditional' 呼叫 navigator.credentials.get() 時,呼叫保持 pending,本身不會顯示任何 UI。」Promise 只在使用者從 autofill 選單挑選 passkey 時才會 resolve;在此之前,頁面仍可接受輸入的 username 與 password。

限制與瀏覽器支援:

  • 依規範,webauthn 對 <textarea> 無效,即便文法技術上同時接受兩種元素類型。
  • 與 one-time-code 配對時會被忽略,因為 OTP 欄位並非攜帶憑證的欄位。
  • Firefox 於 122 版(2024 年 1 月)正式支援 webauthn autocomplete token。Chrome、Edge 與 Safari 自 2025 年起支援 Conditional UI。
  • 在呼叫 navigator.credentials.get() 前先以 PublicKeyCredential.isConditionalMediationAvailable() 做功能偵測,讓較舊的瀏覽器能自然回退到 username+password 流程,不會拋出執行期錯誤。

延伸閱讀 ​

參考資料 ​