autocomplete — атрибут

Атрибут HTML autocomplete позволяет веб-разработчикам указать, какие разрешения, если таковые имеются, есть у пользовательского агента на автоматическое заполнение значений полей формы, а также подсказать браузеру, какой тип информации ожидается в поле.

Он доступен для элементов <input>, принимающих текстовое или числовое значение, элементов <textarea>, элементов <select> и элементов <form>.

Попробуйте

<label for="firstName">First Name:</label>
<input name="firstName" id="firstName" type="text" autocomplete="given-name" />

<label for="lastName">Last Name:</label>
<input name="lastName" id="lastName" type="text" autocomplete="family-name" />

<label for="email">Email:</label>
<input name="email" id="email" type="email" autocomplete="off" />

label {
  display: block;
  margin-top: 1rem;
}

Описание

Атрибут autocomplete предоставляет пользовательскому агенту подсказку о том, как следует предварительно заполнить элемент управления формы или нужно ли это делать вообще. Значение атрибута — это ключевое слово off или on либо упорядоченный список токенов, разделённых пробелами.

<input autocomplete="off" />
<input autocomplete="on" />
<textarea autocomplete="shipping street-address"></textarea>
<input autocomplete="section-user1 billing postal-code" />

Если у элемента <input>, <select> или <textarea> нет атрибута autocomplete, браузер будет использовать атрибут autocomplete элемента, владеющего этой формой. Владеющим элементом формы является либо элемент <form>, соответствующий значению id, указанному в атрибуте form элемента (если он есть), либо, что встречается чаще, элемент <form>, внутри которого расположен этот элемент.

Если один и тот же список токенов используется в нескольких элементах управления формы, пользовательский агент будет автоматически заполнять все вхождения одного и того же значения autocomplete одинаковыми данными.

Некоторые токены можно использовать несколько раз для обозначения потенциально разных ожидаемых значений, например токен zip-code в форме, содержащей адреса доставки и выставления счетов. Добавление нескольких разных токенов в список, разделённый пробелами, позволяет задать для соответствующих элементов управления формы уникальные значения автозаполнения: в данном случае — autocomplete="shipping zip-code" и autocomplete="billing zip-code".

Некоторые значения автозаполнения может потребоваться использовать повторно несколько раз. Например, форма может содержать несколько адресов доставки и, следовательно, несколько вхождений "shipping zip-code", при этом для каждого из них ожидается своё значение. Чтобы сделать значение автозаполнения уникальным в таких случаях, первым токеном в списке токенов, разделённых пробелами, может быть токен section-*, первые восемь символов которого всегда представляют собой строку "section-", за которой следует буквенно-цифровая строка. Все поля формы с токеном section-* и одинаковой буквенно-цифровой строкой относятся к одной именованной группе.

Если атрибут autocomplete указан для скрытых элементов input (<input type="hidden">), его значение должно быть упорядоченным списком токенов, разделённых пробелами; ключевые слова on и off использовать нельзя.

Как правило, источник предлагаемых значений выбирает браузер; обычно это ранее введённые пользователем значения, но они также могут поступать из предварительно настроенных данных. Например, браузер может позволить пользователю сохранить своё имя, адрес, номер телефона и адреса электронной почты для автозаполнения. Браузер также может предложить сохранить зашифрованные данные кредитной карты, чтобы подставлять их после прохождения аутентификации.

Значение

Значением атрибута может быть ключевое слово off или on либо разделённый пробелами <token-list>, описывающий назначение значения автозаполнения.

off

Браузеру не разрешено автоматически вводить или выбирать значение для этого поля. Документ или приложение могут предоставлять собственную функцию автозаполнения, либо соображения безопасности могут требовать, чтобы значение поля не вводилось автоматически.

Примечание: в большинстве современных браузеров установка для autocomplete значения "off" не помешает менеджеру паролей спросить пользователя, хочет ли он сохранить имя пользователя и пароль, или автоматически заполнить эти значения в форме входа на сайт. См. раздел Управление автозаполнением полей для входа.

on

Браузеру разрешено автоматически заполнять поле ввода. Тип ожидаемых данных не указан, поэтому браузер может определить его самостоятельно.

<token-list>

Упорядоченный набор токенов, разделённых пробелами, состоящий из токенов с подробными сведениями об автозаполнении, которым могут предшествовать необязательные токен секции и токен группы billing или shipping. Номерам телефонов, адресам электронной почты и токенам протоколов обмена сообщениями предшествует токен, определяющий тип получателя.

Более подробную информацию см. в стандарте WHATWG.

Токены списка

Параметры <token-list> включают следующие элементы в указанном порядке:

1. Токен имени группы
2. Идентификатор группы
3. Токены подробных сведений
4. Веб-аутентификация

Именованные группы

Для создания именованной группы полей формы можно использовать необязательный токен section-*. Если он присутствует, этот токен должен быть первым в списке токенов, разделённых пробелами.

section-*

Задаёт имя группы элементов управления формы. Токен, первые восемь символов которого — строка "section-" без учёта регистра, за которой следуют дополнительные символы. Все элементы управления формы, начинающиеся с одного и того же токена, относятся к именованной группе.

Идентификатор группы

Необязательный идентификатор группы shipping или billing

shipping

Поле, определяемое последующими токенами, относится к адресу доставки или контактной информации для доставки.

billing

Поле, определяемое последующими токенами, относится к платёжному адресу или контактной информации для выставления счёта.

Токены подробных сведений

Каждый разделённый пробелами список токенов подробных сведений содержит либо тип получателя и цифровую контактную информацию (именно в таком порядке), либо список других токенов, разделённых пробелами.

Тип получателя

Токены, определяющие тип получателя:

home

Тип контакта, определяемый последующими токенами, предназначен для связи с получателем по месту его жительства.

work

Тип контакта, определяемый последующими токенами, предназначен для связи с получателем на работе.

mobile

Тип контакта, определяемый последующими токенами, предназначен для связи с получателем независимо от его местоположения.

fax

Получателем, определяемым последующими токенами, является факсимильный аппарат.

pager

Получателем, определяемым последующими токенами, является пейджер.

Токены цифровых контактов

Токен или группа токенов для телефонных номеров и их частей, добавочных номеров, адресов электронной почты или протоколов мгновенного обмена сообщениями.

tel

Полный номер телефона, включая код страны. Если номер телефона необходимо разбить на составляющие, для соответствующих полей можно использовать следующие значения:

tel-country-code

Код страны, например "1" для США, Канады, других регионов Северной Америки и некоторых частей Карибского бассейна.

tel-national

Полный номер телефона без кода страны, включая внутренний префикс. Для номера телефона "1-855-555-6502" значением этого поля будет "855-555-6502".

tel-area-code

Код региона с соответствующим внутренним префиксом страны, если он требуется.

tel-local

Номер телефона без кода страны и региона. Его можно дополнительно разбить на две части для номеров, состоящих из кода АТС и номера внутри этой АТС. Для номера телефона "555-6502" используйте tel-local-prefix для "555" и tel-local-suffix для "6502".

tel-extension

Добавочный номер, например номер комнаты или люкса в отеле либо внутренний номер сотрудника в компании.

email

Адрес электронной почты.

impp

URL конечной точки протокола мгновенного обмена сообщениями, например xmpp:username@example.net.

Другие токены

Если поле формы предназначено не для номера телефона, адреса электронной почты или протокола мгновенного обмена сообщениями, списку токенов, разделённых пробелами, не предшествует тип контакта:

name

Поле предназначено для полного имени человека. Обычно предпочтительно использовать name вместо того, чтобы разбивать имя на составляющие, поскольку это позволяет избежать необходимости учитывать огромное разнообразие человеческих имён и способов их образования. Однако, если имя всё же нужно разбить на составляющие, можно использовать следующие значения autocomplete:

honorific-prefix

Приставка или титул, например "Mrs.", "Mr.", "Miss", "Ms.", "Dr." или "Mlle.".

given-name

Имя.

additional-name

Второе имя.

family-name

Фамилия.

honorific-suffix

Суффикс, например "Jr.", "B.Sc.", "PhD.", "MBASW" или "IV".

nickname

Псевдоним или сетевое имя.

username

Имя пользователя или учётной записи.

new-password

Новый пароль. При создании учётной записи или смене пароля это значение следует использовать для поля «Введите новый пароль» или «Подтвердите новый пароль», а не для обычного поля «Введите текущий пароль», которое может присутствовать в форме. Браузер может использовать это значение, чтобы не подставлять случайно существующий пароль, а также предложить помощь в создании надёжного пароля.

current-password

Текущий пароль пользователя.

one-time-code

Одноразовый пароль (OTP) для подтверждения личности пользователя, используемый как дополнительный фактор при входе. Чаще всего это код, полученный по отдельному каналу, например по SMS, электронной почте или через приложение-аутентификатор.

organization-title

Должность или позиция человека в организации, например «старший технический писатель», «президент» или «помощник руководителя отряда».

organization

Название компании или организации, например "Acme Widget Company" или "Girl Scouts of America".

street-address

Почтовый адрес. Он может занимать несколько строк и должен полностью указывать местоположение в пределах второго административного уровня (обычно города или населённого пункта), но не должен включать название города, почтовый индекс или название страны.

address-line1, address-line2, address-line3

Отдельные строки почтового адреса. Их следует использовать только в том случае, если значение street-address не указано.

address-level4

Самый детальный административный уровень в адресах с четырьмя уровнями.

address-level3

Третий административный уровень в адресах как минимум с тремя административными уровнями.

address-level2

Второй административный уровень в адресах как минимум с двумя такими уровнями. В странах с двумя административными уровнями это обычно город, посёлок, деревня или другой населённый пункт, где находится адрес.

address-level1

Первый административный уровень в адресе. Обычно это провинция, в которой находится адрес. В США это будет штат, в Швейцарии — кантон, а в Великобритании — графство.

country

Код страны или территории.

country-name

Название страны или территории.

postal-code

Почтовый индекс (в США — ZIP-код).

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

Тип платёжного средства, например "Visa" или "Master Card".

transaction-currency

Валюта, в которой должна быть совершена транзакция.

transaction-amount

Сумма транзакции в валюте, указанной в transaction-currency, для платёжной формы.

language

Предпочитаемый язык, указанный в виде допустимого языкового тега BCP 47.

bday

Полная дата рождения.

bday-day

День месяца в дате рождения.

bday-month

Месяц в дате рождения.

bday-year

Год рождения.

sex

Гендерная идентичность (например, "Female", "Fa'afafine", "Hijra", "Male", "Nonbinary"), представленная произвольным текстом без символов переноса строки.

url

URL, например адрес домашней страницы или сайта компании, если это соответствует контексту остальных полей формы.

photo

URL изображения, представляющего человека, компанию или контактную информацию, указанную в других полях формы.

Токен веб-аутентификации

Для элементов <input> и <textarea> токен webauthn можно указать последним, чтобы сообщить пользовательскому агенту о необходимости отображать учётные данные с открытым ключом, когда пользователь взаимодействует с элементом управления.

webauthn

Ключи доступа, созданные с помощью Web Authentication API по запросу условного вызова navigator.credentials.get() (то есть вызова, включающего mediation: 'conditional'). Если этот токен указан, он должен быть последним в списке токенов, разделённых пробелами. Подробнее см. в статье Вход с помощью ключа доступа через автозаполнение формы.

Доступность

Использование подходящих значений autocomplete помогает людям с когнитивными нарушениями, двигательными ограничениями и другими особенностями быстрее и точнее заполнять формы, уменьшая необходимость вводить и запоминать информацию. Когда браузер может определить назначение поля формы по его значению autocomplete, он может предложить сохранённые данные, например имена, адреса и платёжную информацию. Это полезно всем пользователям, но особенно важно для тех, кому сложно вводить данные вручную.

Использование допустимых токенов автозаполнения также обеспечивает соответствие критерию успеха WCAG 2.2 1.3.5 «Определение назначения ввода» (уровень AA), согласно которому назначение полей ввода, собирающих сведения о пользователе, должно определяться программно. Благодаря этому пользовательские агенты и вспомогательные технологии могут применять персонализированное представление, например отображать знакомые значки рядом с полями, помогая пользователям понять и заполнить формы.

Не отключайте автозаполнение

Значение autocomplete="off" не позволяет браузеру предлагать сохранённые данные для поля. Хотя разработчики иногда используют его для предотвращения автозаполнения по соображениям безопасности (например, для одноразовых кодов), это лишает пользователей функции, на которую многие из них полагаются. Пользователи с когнитивными нарушениями могут использовать автозаполнение, чтобы вспомнить личные данные, а пользователи с двигательными ограничениями получают преимущество за счёт уменьшения объёма вводимого текста. Браузеры также могут игнорировать autocomplete="off" в полях входа, чтобы поддерживать работу менеджеров паролей.

Не используйте недопустимые значения автозаполнения

Использование недопустимых или нестандартных значений (например, выдуманных строк для обхода автозаполнения) приводит к тому же результату: браузер не может сопоставить поле с известным назначением и поэтому не может предложить подходящие варианты. Это также нарушает приведённое выше требование WCAG, поскольку назначение ввода больше нельзя определить программно. Если необходимо отключить автозаполнение для определённого поля, используйте autocomplete="off" только там, где это действительно необходимо (например, для CAPTCHA или одноразовых токенов), а не повсеместно во всей форме.

Примеры

<div>
  <label for="cc-number">Enter your credit card number</label>
  <input name="cc-number" id="cc-number" autocomplete="off" />
</div>

Административные уровни в адресах

Четыре поля административных уровней (от address-level1 до address-level4) описывают адрес с возрастающей точностью в пределах страны, где он находится. В каждой стране используется собственная система административных уровней; при записи адреса порядок уровней также может различаться.

address-level1 всегда обозначает самое широкое административное деление; это наименее точная часть адреса, не считая названия страны.

Гибкость макета формы

Поскольку в разных странах адреса записывают по-разному, поля в адресе могут располагаться в разных местах, а набор и количество полей — различаться. Поэтому, если это возможно, полезно позволить сайту переключаться на ожидаемый пользователями макет формы ввода адреса с учётом страны, в которой находится адрес.

Варианты

Использование каждого административного уровня различается в зависимости от страны. Ниже приведены некоторые примеры; этот список не является исчерпывающим.

США

Типичный домашний адрес в США выглядит так:

432 Anywhere St Exampleville CA 95555

В США наименее точная часть адреса — штат, в данном случае "CA" (официальное сокращение "California", используемое Почтовой службой США). Поэтому address-level1 — это штат, в данном случае "CA".

Вторая по степени обобщённости часть адреса — название города или посёлка, поэтому в этом примере address-level2 — это "Exampleville".

В адресах США уровни 3 и выше не используются.

Великобритания

Формы ввода адреса в Великобритании должны содержать один или два уровня адреса и одну, две или три строки адреса — в зависимости от самого адреса. Полный адрес может выглядеть так:

103 Frogmarch Street Upper-Wapping Winchelsea Whereshire TN99 8ZZ

Уровни адреса:

• address-level1: графство — в данном случае "Whereshire".
• address-level2: почтовый город — в данном случае "Winchelsea".
• address-line2: населённый пункт — в данном случае "Upper-Wapping".
• address-line1: номер дома и улица — "103 Frogmarch Street".

Почтовый индекс указывается отдельно. Обратите внимание: для успешной доставки почты в Великобритании достаточно указать только почтовый индекс и address-line1, поэтому обязательными должны быть только эти поля, хотя обычно люди указывают больше подробностей.

Китай

В Китае может использоваться до трёх административных уровней: провинция, город и район.

Шестизначный почтовый индекс требуется не всегда, но если он указан, его приводят отдельно и снабжают меткой для ясности. Например:

北京市东城区建国门北大街 8 号华润大厦 17 层 1708 单元 邮编：100005

Япония

Адрес в Японии обычно записывается в одну строку, от наименее конкретной части к более конкретной (в обратном порядке по сравнению с США). В адресе указывают два или три административных уровня. В дополнительной строке можно указать название здания и номер помещения. Почтовый индекс приводится отдельно. Например:

〒 381-0000 長野県長野市某町 123

Символ "〒" и следующие за ним семь цифр обозначают почтовый индекс.

address-level1 используется для префектур или Токио; в данном случае это "長野県" (префектура Нагано). address-level2 обычно используется для городов, округов, посёлков и деревень; в данном случае это "長野市" (город Нагано). "某町 123" — это address-line1, состоящий из названия района и номера участка.

Спецификации

Совместимость с браузерами

html.elements.form.autocomplete

html.elements.input.autocomplete

html.elements.select.autocomplete

html.elements.textarea.autocomplete

См. также

• Элемент <input>
• Элемент <select>
• Элемент <textarea>
• Элемент <form>
• HTML-формы
• Все глобальные атрибуты