下拉选择字段
以表单里一个完整字段的形式，让用户从一个封闭的列表中选择一个值——一个可以说明字段必填或选填的标签，一个显示选中的选项并打开选项列表的触发器，以及下方的一行帮助文本或错误——它们为辅助技术关联在一起，并作为一个控件参与表单。
- 类别
- 选择
- 令牌
comp.field- 层级
- 组合
- Web
tanrei-select-fieldschedule - SwiftUI
TanreiSelectFieldradio_button_unchecked - Jetpack Compose
TanreiSelectFieldradio_button_unchecked - Flutter
TanreiSelectFieldradio_button_unchecked - React Native
SelectFieldradio_button_unchecked
- 不提供的变体
- tanrei: filled, outlined
生成自 docs/status/status.json, specs/select-field.spec.json
一个必填的下拉选择字段，以及一个分了组、并用一个字形代表这个字段的下拉选择字段
在表单里，要从一个已知且封闭的列表中选出一个值时，就使用下拉选择字段：国家/地区、时区、套餐。它对应的是最常见的情况，可以直接使用：一个标签、一个显示选中的选项并打开列表的方框、一行帮助文本，以及值被拒绝时的文字。
组成部分是一个字段和一个下拉选择框。字段是框架：标签、必填或选填标记、帮助文本和错误。下拉选择框是控件：触发器、列表，以及用户在其中做的一切。下拉选择字段自己什么都不绘制，也没有令牌：它的每个属性都是这两者之一的属性，原样交给那一个成员；你给它的选项，就是它里面那个下拉选择框的选项。
它的宽度与所在的位置相同，方框填满这个宽度。想要窄一些的方框，就给它一个窄一些的位置。
在 Web 上它是 <tanrei-select-field>，子元素是 <tanrei-option>。其他平台尚未实现。
选项是下拉选择字段的子元素：每个选项有一个值和一个标签。value 指明选中的是哪一个。change 和 toggle 是下拉选择框自己的事件；监听到其中任何一个时，字段的 value 和 open 都已经是新的值。
<form>
<tanrei-select-field name="country" label="国家/地区" value="jp" required required-text="必填"
supporting-text="发票将寄往该国家/地区。">
<tanrei-option value="ca">加拿大</tanrei-option>
<tanrei-option value="jp">日本</tanrei-option>
</tanrei-select-field>
</form>
<!-- 分组，标签下方带一行文字，并用一个字形代表这个字段。 -->
<tanrei-select-field label="时区" value="Europe/Lisbon">
<span slot="leading-icon">public</span>
<tanrei-option-group label="亚洲">
<tanrei-option value="Asia/Tokyo" supporting-text="UTC+9">东京</tanrei-option>
</tanrei-option-group>
<tanrei-option-group label="欧洲">
<tanrei-option value="Europe/Lisbon" supporting-text="UTC+0">里斯本</tanrei-option>
</tanrei-option-group>
</tanrei-select-field>
<script type="module">
import '@tanrei/web/components/select-field';
const country = document.querySelector('[name="country"]');
// 用户选择了另一个选项。value 已经是新的值。
country.addEventListener('change', () => save(country.value));
// 由用户打开或关闭；关闭时带有原因。
country.addEventListener('toggle', (e) => console.log(e.detail.open, e.detail.reason));
// 校验由你来做：下拉选择字段自己绝不会设置 error。
country.error = submitted && !ships(country.value);
country.errorText = '暂不支持配送到该国家/地区。请选择其他国家/地区。';
</script>import { Option, SelectField } from '@tanrei/react';
<SelectField label="国家/地区" value={country} required requiredText="必填" onChange={(event) => setCountry(event.currentTarget.value)}>
<Option value="ca">加拿大</Option>
<Option value="jp">日本</Option>
</SelectField>用它的两个成员手写出来的同一个字段，画面是一样的，对辅助技术来说也是同一个控件：
<tanrei-field label="国家/地区" required required-text="必填"
supporting-text="发票将寄往该国家/地区。">
<tanrei-select name="country" placeholder="请选择国家/地区">
<tanrei-option value="jp">日本</tanrei-option>
<tanrei-option value="ke">肯尼亚</tanrei-option>
</tanrei-select>
</tanrei-field>手写出来的同一个字段：一个字段，里面有一个下拉选择框
当你需要下拉选择字段没有提供的排布方式时，就往下走一层：
| 你需要 | 使用 |
|---|---|
| 标签、方框、帮助文本和错误 | 下拉选择字段 |
| 在框架里面、方框旁边或下方放你自己的东西 | 一个字段，里面放一个下拉选择框和你自己的元素 |
| 只要方框，标签位于别处：栏里的主题、工具栏里的排序方式、表格的单元格 | 单独使用的下拉选择框，由它自己的 label 命名 |
| 列表长到用户宁愿键入也不愿滚动 | 组合框 |
下到这一层之后，变的是各样东西写在哪里。name、value 和选项写在下拉选择框上，这时它就是表单面对的控件，它的事件也在它上面监听。label、error 和 disabled 仍然写在字段上，由字段转交给控件：不要设置下拉选择框自己的这几项。
带辅助文本和一个禁用选项、选填、错误、只读和禁用
filled 和 outlined：字段的标签浮在下拉选择框的方框里，必填的字段带一个星号
m3-like 显示| 方面 | 来自字段 | 来自下拉选择框 |
|---|---|---|
| 属性 | label, labelHidden, supportingText, errorText, error, disabled, required, optional, requiredMark, requiredText, optionalText |
variant, size, value, placeholder, readOnly, open, separation, iconSpace, status, statusText, emptyText |
| 事件 | — | change, toggle |
| 插槽 | label-icon |
leading-icon，以及选项 |
| 令牌 | comp.field.* |
方框用 comp.input-box.*，每一种输入方框都读取它；列表用 comp.select.* |
下拉选择框有它自己的 label、labelHidden、error 和 disabled。它们不是下拉选择字段的属性：字段的 label 为控件命名，字段的 error 让方框进入错误状态，字段的 disabled 禁用它。所以每一项你都只设置一次，设置在下拉选择字段上，它的标签也随控件一起变化。
在 stacked 外观下，标签是字段位于方框上方的那一行。在 filled 和 outlined 外观下，下拉选择框自己画出同一个标签，让它浮在方框里，字段不绘制标签行；这时，无论设计系统指定的是哪一种标记，必填的字段都用标签后面的一个星号来标记。帮助文本从值开始的位置开始，也就是越过前置图标之后。列表打开期间，标签和帮助文本与方框一样，画成聚焦的样子。
触发器和列表做什么，也就是打开、方向键、键入、选择和分组，写在下拉选择框的页面上。框架做什么，也就是必填标记、帮助文本、错误以及错误怎样朗读，写在字段的页面上。
下拉选择字段没有自己的令牌。它的框架读取字段的令牌，它的方框和列表读取下拉选择框的令牌，无论这些令牌设置在哪里。要改动某一个实例，就在它上面设置成员的令牌：
<tanrei-select-field label="国家/地区"
style="--tanrei-comp-field-label-gap: 12px"></tanrei-select-field>构成
构成
stacked-empty 之上。| 部件 | 说明 |
|---|---|
1 field | The Field: the label row with its glyph and its requirement mark, and the supporting row with the help and the error text. In a look whose select floats the label it draws no label row. |
2 select | The select, as the Field's one control: the trigger with the value it shows, its leading icon and its chevron, the label that floats in it in the looks that float one, and the list of options that opens from it. |
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
variant | stacked | filled | outlined | "stacked" | The text input's three looks, so that a select is drawn as the text inputs beside it. Stacked is a filled box that shows focus and error with a line inside its edge and draws no label: the label of the Field that frames it stands above it. Filled and outlined float the label inside the box. Use one style per form. A design system may leave some out (the Tanrei system ships stacked only) or add values. — Select |
size | small | medium | large | "medium" | Minimum height of the container: stacked 32 / 40 / 56, as tall as a Button of the same size, so that the box and a Button side by side in one row stand as tall as each other; filled and outlined 40 / 48 / 56, which hold the label that floats inside them. The text input's three sizes: medium and large for forms, small for a select in an app bar, a toolbar or a dense row of controls, where nothing frames it. The hit area always meets the minimum target. A design system may add values. — Select |
value | string | "" | The value of the chosen option. The select shows that option's label; while value names no option it shows the placeholder. An option whose value is the empty string is a choice like any other ("None", "Any") and is the chosen one while value is empty. — Select |
label | string | "" | Names the control, visibly and to assistive technology. Required, unless the control names itself (a checkbox or a switch with its own label): then leave it empty and the field adds only help and an error. — Field Names the select. In a filled or outlined look the select draws it, floating in its box, and the Field draws no label row (FLD-25, SEL-15). |
labelHidden | boolean | false | Does not draw the label, which stays the accessible name. For a control whose visible label is elsewhere (a table column, a toolbar). — Field Hides the label wherever it would be drawn: the Field's row, or the select's floating label (FLD-25). |
placeholder | string | "" | A hint shown while nothing is chosen and the label is not in the line ("Choose a country"). Never a replacement for label, and never a choice. — Select |
supportingText | string | "" | Help shown below the control and given to assistive technology as the control's description. While the field is in error it gives way to errorText, unless the design system keeps both (comp.field.error-text.placement append). — Field |
errorText | string | "" | Shown while error is true, in supportingText's place — or below it, which then stays, where the design system's comp.field.error-text.placement is append: what is wrong and how to put it right, in words. — Field |
error | boolean | false | Puts the field in the error condition: the error text is drawn, the control is exposed as invalid and, where it has an error condition of its own, drawn in it. What a value means is the product's to validate; the field never sets this itself. — Field The Field puts its select in the select's own error condition (FLD-8, SEL-9). |
disabled | boolean | false | Disables the control and draws the frame as disabled. Disable a framed control here, not on the control, so that its label follows. — Field The Field disables its select (FLD-14, SEL-46); the select field is then left out of its form (SEF-2). |
readOnly | boolean | false | The value is shown, can be focused and is submitted, but cannot be changed: the list does not open and no chevron is drawn. — Select |
required | boolean | false | What the form asks of the control: true exposes it as required and draws the required mark beside the label. It never validates: a missing answer is the product's to report with error. — Field The Field exposes its select as required (FLD-10, SEL-11). |
optional | boolean | false | Draws the optional tag after the label and adds optionalText to the control's description, because assistive technology has no state for it. Ignored while required is true: a control is never both. — Field |
requiredMark | auto | tag | asterisk | none | "auto" | How this control shows that it is required: tag is a small filled Tag with requiredText, asterisk is "*" after the label, none draws nothing and keeps the semantics. Auto takes comp.field.requirement.mark, which follows sys.behavior.requirement-mark, the system's one answer. Ignored unless required is true. — Field |
requiredText | string | "" | The text of the required tag, in the product's language ("Required", "必須"). The product's: Tanrei has no word for it. Empty reads the product's words; with neither, FLD-24 says what is drawn. — Field |
optionalText | string | "" | The text of the optional tag, in the product's language ("Optional", "任意"); also read to assistive technology as part of the description. The product's: Tanrei has no word for it. Empty reads the product's words. — Field |
open | boolean | false | Whether the list is shown. The select opens and closes itself and emits toggle; the product may also set it. Ignored while the select is disabled or read-only or has nothing to show: no option, no status row and no empty text (SEL-61). — Select |
separation | auto | divider | gap | "auto" | How a group of options is told from what is next to it. divider: a line between them. gap: empty space and no line. Auto takes comp.select.separation, which follows the design system's choice. — Select |
iconSpace | auto | always | never | "auto" | Whether an option keeps the room of the leading icon column where it has no icon, so that the labels of a section start on one line — a section being an option group, or a run of adjacent options outside any group. auto: an option keeps the column while another option of its section has a leading icon, so that a section without icons starts its labels where the row's content starts. always: every option keeps it. never: only an option that has an icon has the column. The menu's iconSpace, with the same values and default (SEL-66). — Select |
density | regular | compact | "regular" | How much room an option of the list takes: its least height, its paddings, the gap between its columns and the size of its glyphs (the leading icon, the check), and never its text style. regular (a 48 row in the default system) is for a product used by touch as well as by pointer; compact (a 32 row with 20 glyphs, the menu's compact row) is for a tool used with a pointer, whose lists are long. For touch an option is never lower than the touch target in either (SEL-37). The field's own box is not changed: its height is size's. A design system may add values. — Select |
status | idle | loading | error | "idle" | What the product's source of options is doing, which the product sets: idle (the options given are final), loading (options are on their way: the status row shows a loading indicator and the list is marked busy) or error (the source failed: the status row shows statusText in the error color, announced at once). The combobox's and the search's values, with the same meaning. The select never loads anything itself. — Select |
statusText | string | "" | The status row's text, in the product's language, read to assistive technology when the list opens and when it changes: a count ("20 of 340 projects shown"), that loading failed ("Projects could not be loaded"), or, while status is loading, the loading indicator's name ("Loading projects"). Empty draws no status row unless status is loading. — Select |
emptyText | string | "" | Shown in the list while the select holds no option, status is idle and statusText is empty, in the product's language ("No projects yet"), so that the select still opens and says why there is nothing to choose. The product's: Tanrei has no words for it. Empty reads the product's words (noOptionsText); with neither, the select has nothing to show and does not open (SEL-61), and it is reported. — Select |
插槽
| 插槽 | 说明 |
|---|---|
leading-icon | A glyph at the start of the container that stands for the field whatever is chosen (a globe before a language). It takes the place of the chosen option's own glyph. — Select |
label-icon | A glyph before the label. — Field |
事件
| 事件 | 说明 |
|---|---|
change | The person chose an option whose value differs from the select's; carries the new value. Not emitted when the product sets value, when the chosen option is chosen again, or while the person only moves through the list. — Select |
toggle | The list was opened or closed by the person; carries the new open and, for a close, the reason: select, escape, back, outside, focus-out, anchor-hidden, press or tab (in the platform's casing). After a choice it follows change. — Select |
条目
该组件重复排列的条目种类。测试样例按顺序列出条目；各平台以各自的惯用方式为每个种类命名。
option
One choice of the select: a label, the value it stands for, and optionally a supporting line and a glyph.
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
label | string | "" | The option's text and its accessible name; the container shows it once the option is chosen. Required. |
value | string | "" | Identifies the choice: the option is the chosen one while the select's value equals it. Unique within the select. The empty string is a value like any other, for an option that stands for no choice ("None"). |
supportingText | string | "" | A line below the label that says more about the choice. Shown in the list, not in the container. |
leadingIcon | string | "" | The name of an icon (a glyph of the system's icon set) before the label; the container shows it too while the option is chosen and the select has no leading icon of its own. |
disabled | boolean | false | Prevents the option from being chosen. It stays reachable with the arrow keys. |
| 规格 | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
|---|---|---|---|---|---|
| 条目 | tanrei-option | TanreiSelectOption | TanreiSelectOption | TanreiSelectOption | SelectOption |
label · 属性 | label | title | text | label | label |
value · 属性 | value | tag | value | value | value |
supportingText · 属性 | supportingText | supportingText | supportingText | supportingText | supportingText |
leadingIcon · 属性 | leadingIcon | leadingIcon | leadingIcon | leadingIcon | leadingIcon |
disabled · 属性 | disabled | disabled | enabled | enabled | disabled |
| 备注 | <tanrei-option> children of <tanrei-select-field>, exactly as of <tanrei-select>: the product's elements in the light DOM, passed to the select inside through the default slot and read by it as data (web-options.md). | The select's own option, under the same name: the select field passes it to its select and reads nothing of it. | The select's own option, under the same name: the select field passes it to its select and reads nothing of it. | The select's own option, under the same name: the select field passes it to its select and reads nothing of it. | The select's own option, under the same name: the select field passes it to its select and reads nothing of it. |
option-group · 分组 — 包含条目
A run of related options, optionally titled. The select separates a group from what is next to it by a divider or a gap.
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
title | string | "" | A short heading drawn above the group's options, which also names the group; empty draws none and leaves the group unnamed. |
| 规格 | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
|---|---|---|---|---|---|
| 条目 | tanrei-option-group | TanreiSelectSection | TanreiSelectGroup | TanreiSelectGroup | SelectOptionGroup |
title · 属性 | label | title | title | title | title |
| 备注 | As the option: the same element, the product's child, with its options inside it. | The select's own option group, under the same name: the select field passes it to its select and reads nothing of it. | The select's own option group, under the same name: the select field passes it to its select and reads nothing of it. | The select's own option group, under the same name: the select field passes it to its select and reads nothing of it. | The select's own option group, under the same name: the select field passes it to its select and reads nothing of it. |
状态
行为
以 EARS 形式写成的需求。每个平台的实现都按这些 ID 逐条测试。需求原文取自规格文件，原样以英文呈现。
| ID | 需求 |
|---|---|
SEF-1 | THE select field SHALL be a Field that frames one select, and nothing else. It SHALL give label, labelHidden, supportingText, errorText, error, disabled, required, optional, requiredMark, requiredText and optionalText to its Field and every other prop to its select, each unchanged; SHALL hold the label-icon slot for its Field and the leading-icon slot for its select; SHALL give its select every option and option group the product gives it, in the order given, as that select's own items, read, drawn and chosen by the select (SEL-17, SEL-31 to SEL-45); and SHALL emit its select's events as its own, each once. It SHALL draw no part of its own, hold no state of its own and have no token of its own: what it shows, how it behaves and what it exposes to assistive technology SHALL be exactly what that Field and that select do when a product places the one in the other (FLD-1 to FLD-28; SEL-1 to SEL-64) — the label row and its requirement mark (FLD-2 to FLD-6), or the label that floats in the box with the Field's row left out (FLD-25, SEL-15, SEL-7); the supporting row and the error, started where the value starts (FLD-7 to FLD-9, FLD-26); the rows drawn focused while the list is open (FLD-13, SEL-20); the name, the description and the states (FLD-10, FLD-11, FLD-14, SEL-11); and the width, which is the Field's and which the select fills (FLD-1, SEL-49). |
SEF-2 | WHERE the platform has forms (the web) THE select field SHALL be the one control the form sees: it SHALL take name, submit its select's value, reset to the value it was first given, restore it on navigation, report to the form's constraint validation exactly what its select would report there (SEL-11), be submitted WHILE readOnly is true (SEL-47), and be left out WHILE disabled is true or a disabled group of the form holds it (SEL-46); its select and its Field SHALL take no part in the form themselves. |
SEF-3 | WHEN the select field is given focus — by the product, by a press on its label row (FLD-12), or by a form that reports its validity — THE select field SHALL pass the focus to its select's container and SHALL add no stop to the focus order: the one stop inside it is its select's (SEL-13). WHILE focus is anywhere inside it, or its select's list is open, THE select field SHALL count as focused for its Field (FLD-13). |
SEF-4 | IF the select field is placed in a Field THE select field SHALL in debug builds report that it is a field already and that the bare control is the select, and both SHALL still render (FLD-15). WHILE it stands in a field group THE select field SHALL follow that group's disabled, through its own Field, and take nothing else from the group (FGR-20). |
SEF-5 | THE select field SHALL have no words of its own and SHALL read none: requiredText and optionalText are read by its Field (FLD-24), emptyText by its select (SEL-62), each from the instance's prop and then from the product's words. |
SEF-6 | WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE select field SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on the element that carries its role — an id reference by the elements it names in the host's tree or a tree around it, an error message as part of the description while the select field is invalid — except those the select field owns (aria-label, aria-labelledby, aria-disabled, aria-haspopup, aria-expanded, aria-controls), which it SHALL move and not expose: its name is label (SEF-1). WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE select field SHALL take it off that element. WHEN the product sets an aria- attribute the select field owns THE select field SHALL report it in debug builds. |
各平台名称对照
对等并不意味着 API 完全相同。同一份契约，由各平台以自己的惯用方式表达。
| 规格 | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
|---|---|---|---|---|---|
| 组件 | tanrei-select-field | TanreiSelectField | TanreiSelectField | TanreiSelectField | SelectField |
variant · 属性 | variant | variant | variant | variant | variant |
size · 属性 | size | size | size | size | size |
value · 属性 | value | selection | value | value | value |
label · 属性 | label | label | label | labelText | label |
labelHidden · 属性 | labelHidden | labelsHidden | labelHidden | labelHidden | labelHidden |
placeholder · 属性 | placeholder | prompt | placeholder | hintText | placeholder |
supportingText · 属性 | supportingText | supportingText | supportingText | helperText | supportingText |
errorText · 属性 | errorText | errorText | errorText | errorText | errorText |
error · 属性 | error | error | isError | isError | error |
disabled · 属性 | disabled | disabled | enabled | enabled | disabled |
readOnly · 属性 | readOnly | readOnly | readOnly | readOnly | readOnly |
required · 属性 | required | isRequired | required | required | required |
optional · 属性 | optional | isOptional | optional | optional | optional |
requiredMark · 属性 | requiredMark | requiredMark | requiredMark | requiredMark | requiredMark |
requiredText · 属性 | requiredText | requiredText | requiredText | requiredText | requiredText |
optionalText · 属性 | optionalText | optionalText | optionalText | optionalText | optionalText |
open · 属性 | open | isPresented | expanded | controller | open |
separation · 属性 | separation | separation | separation | separation | separation |
iconSpace · 属性 | iconSpace | iconSpace | iconSpace | iconSpace | iconSpace |
density · 属性 | density | density | density | density | density |
status · 属性 | status | status | status | status | status |
statusText · 属性 | statusText | statusText | statusText | statusText | statusText |
emptyText · 属性 | emptyText | emptyText | emptyText | emptyText | emptyText |
change · 事件 | change | selection | onValueChange | onChanged | onValueChange |
toggle · 事件 | toggle | isPresented | onExpandedChange | onOpenChanged | onOpenChange |
| 备注 | The tag tanrei-select-field, the class TanreiSelectField, the React name SelectField. It takes every attribute, property, event and child of the select and of its Field, under the same names. The element is composed as every field element is; what follows is what is particular to it. Members: <tanrei-field> holding one <tanrei-select> in its default slot; the product places none, and gives the options. The host is display: block, as the Field is. Value member: tanrei-select. The host is the form's element — name, the value and its state, validity anchored on the select's trigger, reset to the value attribute, restore, form, a disabled fieldset — and the select inside has no name. Props, set as properties on the member each is from. On the Field: label, labelHidden, supportingText, errorText, error, disabled, required, optional, requiredMark, requiredText, optionalText. On the select: variant, size, value, placeholder, readOnly, open, separation, iconSpace, status, statusText, emptyText, and inline, the select's attribute for tests and fixtures, which is no prop of the spec and is passed on so that an open fixture and its twin are staged alike. Attributes are the members' own: kebab-case, except readonly. Props of one name on both members — label, labelHidden, error, disabled — are the Field's; the select's are never set by the element and reach the select through the connection. Events: change is the select's own composed, bubbling Event and leaves by itself with the host as its target. toggle is the select's CustomEvent, composed and not bubbling: it is heard on the host, as on any shadow host, and by no ancestor. Two props are the select's at every moment and are read through to it, never copied — value (the element's value is its value member's) and open, by the same accessor, as the combobox field reads its three — so each is already new in every listener of change and of toggle, capturing or bubbling, and when open is taken back with no event. No listener of the element's takes either. None is stopped and none is copied. Slots: label-icon is passed to the Field and leading-icon to the select, each by a slot element of the same name rendered only while the host has a child for it. The default slot is passed to the select — <tanrei-select><slot></slot></tanrei-select> — and is always rendered, where a field element otherwise has no default slot: the product's <tanrei-option> and <tanrei-option-group> children are assigned to it, and the select reads them through it. A child that is neither, and has no slot name the element has, is not rendered and is reported in a debug build. Parts: the member hosts are field and select. Exported from the Field: label, label-icon, requirement-label, supporting-text, counter (never drawn here). Exported from the select: container, outline, active-indicator, label, requirement-label, value, placeholder, leading-icon, chevron, list, option, option-label, option-supporting-text, option-leading-icon, mark, group, group-title, divider, status. Two names collide, label and requirement-label. Each is exported with its member's name before it, always (field-label, select-label, field-requirement-label, select-requirement-label), and under the bare name from both members as well, because the two are one thing to a person and are never drawn at once: FLD-25 is the sentence that holds it. Focus: the shadow root does not delegate. focus() and blur() call the select's; a press on the label row focuses the trigger by FLD-12 and opens nothing, a press on the trigger opens the list, and a press on the help does nothing. The list is the select's own popover in the top layer: it is placed against the trigger, both in the select's shadow tree, and a press on the Field's rows is a press outside it (SEL-27). The connection is the Field's with its control, with one value more upward, drawnFocused (SEL-63, FLD-13), the same value the combobox says; the element takes no part in it. Parts and tokens of its own: none. The element writes no custom property: --tanrei-comp-field-*, --tanrei-comp-input-box-* and --tanrei-comp-select-* reach the members by inheritance, and one select field is set apart by setting any of them on the element. What its twin cannot do that it does: nothing. The twin: <tanrei-field label="Country" required supporting-text="Where your invoices are addressed."><tanrei-select name="country" value="jp"><tanrei-option value="jp">Japan</tanrei-option></tanrei-select></tanrei-field>. Before the element is defined its options are running text in the page, as a select's are: hide tanrei-select-field:not(:defined) > * and reserve the block size. Words: none of its own; required-text and optional-text left empty are read by the Field from the product's words. | TanreiSelectField("Country", selection: $country, supportingText: "…") { TanreiSelectOption("Japan").tag("jp") … }: a view whose body is TanreiField(…) { TanreiSelect(selection:) { options } } with each argument passed to the member it is from, and nothing else. The option content is the select's own, passed through as a view builder. labelHidden follows .labelsHidden() and disabled follows .disabled(_:), both read by the Field. The product's words are read by the Field from the \.tanreiWords environment value. Not built on this platform yet, nor is the select itself. | TanreiSelectField(value, onValueChange, label, supportingText = …) { TanreiSelectOption("Japan", "jp") … }: a composable that calls TanreiField(…) { TanreiSelect(…) { content() } } with each argument passed to the member it is from, and nothing else; the content lambda is the select's. enabled is the inverse flag and isError keeps Compose's name, both the Field's. The product's words are read by the Field from LocalTanreiWords. Not built on this platform yet, nor is the select itself. | TanreiSelectField(value:, onChanged:, labelText:, helperText:, options: […]): a widget that builds TanreiField(child: TanreiSelect(…)) with each argument passed to the member it is from, and nothing else; labelText, hintText, helperText, errorText and enabled keep InputDecoration's names. TanreiSelectFormField wraps it as a FormField<String> (validator, onSaved, autovalidateMode), which is how a Flutter form takes part, and its errorText is the Field's. The product's words are read by the Field from the TanreiWords inherited widget. Not built on this platform yet, nor is the select itself. | <SelectField label="Country" value={value} onValueChange={setValue} supportingText="…" options={[…]} />: a component that renders <Field …><Select … /></Field> with each prop passed to the member it is from, and nothing else; options is the select's array. The product's words are read by the Field from the TanreiWordsProvider context. Not built on this platform yet, nor is the select itself. |
令牌
| 令牌 | 引用 | 解析值（浅色） |
|---|---|---|
--tanrei-comp-field-counter-gap | sys.space.space200 | 16px |
--tanrei-comp-field-error-text-gap | sys.space.space50 | 4px |
--tanrei-comp-field-error-text-placement | — | 0 |
--tanrei-comp-field-label-icon-gap | sys.space.space100 | 8px |
--tanrei-comp-field-label-icon-size | sys.icon.small | 20px |
--tanrei-comp-field-label-gap | sys.space.space100 | 8px |
--tanrei-comp-field-motion-state-duration | sys.motion.role.state.default | 250ms |
--tanrei-comp-field-motion-state-easing | sys.motion.easing.state | cubic-bezier(0.2, 0, 0, 1) |
--tanrei-comp-field-requirement-asterisk-gap | sys.space.space25 | 2px |
--tanrei-comp-field-requirement-gap | sys.space.space100 | 8px |
--tanrei-comp-field-requirement-mark | sys.behavior.requirement-mark | 0 |
--tanrei-comp-field-standard-counter-color | sys.color.on-surface-variant | |
--tanrei-comp-field-standard-disabled-counter-color | — | |
--tanrei-comp-field-standard-disabled-error-text-color | — | |
--tanrei-comp-field-standard-disabled-error-counter-color | — | |
--tanrei-comp-field-standard-disabled-error-label-icon-color | — | |
--tanrei-comp-field-standard-disabled-error-label-color | — | |
--tanrei-comp-field-standard-disabled-error-required-asterisk-color | — | |
--tanrei-comp-field-standard-disabled-error-supporting-text-color | — | |
--tanrei-comp-field-standard-disabled-error-value-text-color | — | |
--tanrei-comp-field-standard-disabled-label-icon-color | — | |
--tanrei-comp-field-standard-disabled-label-color | — | |
--tanrei-comp-field-standard-disabled-required-asterisk-color | — | |
--tanrei-comp-field-standard-disabled-supporting-text-color | — | |
--tanrei-comp-field-standard-disabled-value-text-color | — | |
--tanrei-comp-field-standard-error-text-color | sys.color.error | |
--tanrei-comp-field-standard-error-counter-color | sys.color.on-surface-variant | |
--tanrei-comp-field-standard-error-label-icon-color | sys.color.on-surface-variant | |
--tanrei-comp-field-standard-error-label-color | sys.color.on-surface | |
--tanrei-comp-field-standard-error-required-asterisk-color | sys.color.primary | |
--tanrei-comp-field-standard-error-supporting-text-color | sys.color.on-surface-variant | |
--tanrei-comp-field-standard-error-value-text-color | sys.color.on-surface-variant | |
--tanrei-comp-field-standard-focused-counter-color | — | |
--tanrei-comp-field-standard-focused-error-text-color | — | |
--tanrei-comp-field-standard-focused-error-counter-color | — | |
--tanrei-comp-field-standard-focused-error-label-icon-color | — | |
--tanrei-comp-field-standard-focused-error-label-color | — | |
--tanrei-comp-field-standard-focused-error-required-asterisk-color | — | |
--tanrei-comp-field-standard-focused-error-supporting-text-color | — | |
--tanrei-comp-field-standard-focused-error-value-text-color | — | |
--tanrei-comp-field-standard-focused-label-icon-color | — | |
--tanrei-comp-field-standard-focused-label-color | — | |
--tanrei-comp-field-standard-focused-required-asterisk-color | — | |
--tanrei-comp-field-standard-focused-supporting-text-color | — | |
--tanrei-comp-field-standard-focused-value-text-color | — | |
--tanrei-comp-field-standard-label-icon-color | sys.color.on-surface-variant | |
--tanrei-comp-field-standard-label-color | sys.color.on-surface | |
--tanrei-comp-field-standard-required-asterisk-color | sys.color.primary | |
--tanrei-comp-field-standard-supporting-text-color | sys.color.on-surface-variant | |
--tanrei-comp-field-standard-value-text-color | sys.color.on-surface-variant | |
--tanrei-comp-field-supporting-text-gap | sys.space.space50 | 4px |
--tanrei-comp-field-value-text-gap | sys.space.space200 | 16px |
--tanrei-comp-field-label-typescale | sys.typescale.label | 500 14px/1.4286 |
--tanrei-comp-field-supporting-text-typescale | sys.typescale.label-small | 500 12px/1.3333 |
--tanrei-comp-field-value-text-typescale | sys.typescale.label | 500 14px/1.4286 |
测试样例
作为基准的渲染结果。所有平台都以相同的 ID 为每个样例截取快照，以便相互比较。
variant: stacked (41)
stacked-empty
variant: stacked label: Country items: 5 stacked-value
variant: stacked value: jp label: Country items: 5 stacked-open
variant: stacked value: jp label: Country open: true items: 5 单独绘制在 312 × 472 的窗口中stacked-large
variant: stacked size: large value: jp label: Country items: 5 stacked-small
variant: stacked size: small value: jp label: Country items: 5 stacked-error
variant: stacked label: Country errorText: Choose a country. error: true items: 5 stacked-disabled
variant: stacked value: jp label: Country disabled: true items: 5 stacked-placeholder
label: Country placeholder: Choose a country items: 5 stacked-open-none-chosen
label: Country placeholder: Choose a country open: true items: 5 单独绘制在 312 × 473 的窗口中stacked-label-hidden
value: fr label: Country labelHidden: true items: 5 stacked-supporting
value: jp label: Country supportingText: Where your invoices are addressed. items: 5 stacked-error-value
value: ke label: Country errorText: We cannot ship there yet. error: true items: 5 stacked-read-only
value: jp label: Country readOnly: true items: 5 stacked-required
label: Country required: true requiredText: Required items: 5 stacked-optional
label: Country placeholder: Choose a country optional: true optionalText: Optional items: 5 stacked-required-asterisk
label: Country required: true requiredMark: asterisk items: 5 stacked-required-disabled
value: jp label: Country disabled: true required: true requiredText: Required items: 5 stacked-required-error
label: Country errorText: Choose a country. error: true required: true requiredText: Required items: 5 stacked-required-ja
label: 国 placeholder: 国を選択 required: true requiredText: 必須 items: 3 stacked-optional-ja
value: jp label: 国 optional: true optionalText: 任意 items: 3 stacked-label-icon
value: Asia/Tokyo label: Time zone items: 3 slots: label-icon stacked-option-icon
value: dark label: Theme items: 3 stacked-leading-icon
value: ja label: Language items: 2 slots: leading-icon open-icons
value: dark label: Theme open: true items: 3 单独绘制在 312 × 473 的窗口中open-supporting-text
value: team label: Plan open: true items: 3 单独绘制在 312 × 473 的窗口中open-disabled-chosen
value: enterprise label: Plan open: true items: 3 单独绘制在 312 × 473 的窗口中open-groups
value: Europe/Lisbon label: Time zone open: true items: 3 单独绘制在 312 × 473 的窗口中open-groups-divider
value: Europe/Lisbon label: Time zone open: true separation: divider items: 3 单独绘制在 312 × 473 的窗口中open-groups-gap
value: Europe/Lisbon label: Time zone open: true separation: gap items: 3 单独绘制在 312 × 473 的窗口中open-many
value: corner.small label: Token open: true items: 24 单独绘制在 312 × 473 的窗口中open-long-options
value: weekly label: Email me open: true items: 3 单独绘制在 312 × 473 的窗口中long-value
value: all label: Email me items: 3 empty-value-option
value: label: Contrast items: 3 small-label-hidden
size: small value: high label: Contrast labelHidden: true items: 3 small-label-hidden-icons
size: small value: light label: Theme labelHidden: true items: 3 small-label-hidden-leading-icon
size: small value: en label: Language labelHidden: true items: 2 slots: leading-icon small-label-hidden-open
size: small value: light label: Theme labelHidden: true open: true items: 3 单独绘制在 312 × 473 的窗口中small-open
size: small value: jp label: Country open: true items: 5 单独绘制在 312 × 473 的窗口中stacked-required-rtl
value: Asia/Tokyo label: المنطقة الزمنية supportingText: تُعرض المواعيد بهذا التوقيت. required: true requiredText: مطلوب direction: rtl items: 2 slots: label-icon open-rtl
value: Asia/Tokyo label: المنطقة الزمنية open: true direction: rtl items: 2 单独绘制在 312 × 473 的窗口中long-value-rtl
value: all label: Email me direction: rtl items: 3 variant: filled (7)
filled-empty
variant: filled label: Country items: 5 filled-value
variant: filled value: jp label: Country items: 5 filled-open
variant: filled value: jp label: Country open: true items: 5 单独绘制在 312 × 473 的窗口中filled-large
variant: filled size: large value: jp label: Country items: 5 filled-small
variant: filled size: small value: jp label: Country items: 5 filled-error
variant: filled label: Country errorText: Choose a country. error: true items: 5 filled-disabled
variant: filled value: jp label: Country disabled: true items: 5 variant: outlined (9)
outlined-empty
variant: outlined label: Country items: 5 outlined-value
variant: outlined value: jp label: Country items: 5 outlined-open
variant: outlined value: jp label: Country open: true items: 5 单独绘制在 312 × 473 的窗口中outlined-large
variant: outlined size: large value: jp label: Country items: 5 outlined-small
variant: outlined size: small value: jp label: Country items: 5 outlined-error
variant: outlined label: Country errorText: Choose a country. error: true items: 5 outlined-disabled
variant: outlined value: jp label: Country disabled: true items: 5 outlined-required
variant: outlined label: Country required: true requiredText: Required items: 5 outlined-rtl
variant: outlined value: Europe/Lisbon label: المنطقة الزمنية direction: rtl items: 2 生成自 specs/select-field.spec.json, tokens/comp/field.tokens.json, design/tokens/
- 这个元素的 shadow root 里有一个
<tanrei-field>，其中放着一个<tanrei-select>，此外什么都没有。导入这个元素，两个成员也随之完成定义。 - 选项仍然是你写在
<tanrei-select-field>里的子元素。它们绝不会被移动或复制：它们通过一个插槽到达里面的下拉选择框，一有变化，下拉选择框就会重新读取。手动替换它们（replaceChildren()）的效果与在下拉选择框上相同。 - 这个元素是与表单关联的元素。它接受
name和form；提交的只有值，禁用时什么都不提交，只读时照常提交；重置为value属性（attribute）的值；跟随被禁用的<fieldset>；设置了required而值为空时，报告缺少值。它的两个成员不向表单添加任何条目。 change是下拉选择框的事件，composed 并且冒泡。toggle是下拉选择框的 CustomEvent，带有detail.open和detail.reason：它是 composed 的，但不冒泡，所以要在这个元素上监听，<details>之类的祖先绝不会收到它。它们的 target 是这个元素，在每个监听器里，event.target.value和event.target.open都已经是新的值。- 部件：
field和select是两个成员。成员自己的部件在这里的名称与下一层相同：label-icon、supporting-text；container、outline、active-indicator、value、placeholder、leading-icon、chevron、list、option、option-label、option-supporting-text、option-leading-icon、mark、group、group-title、divider、status。label和requirement-label指两者之中画出来的那一个——字段的标签行，或者下拉选择框的浮动标签——而field-label、select-label、field-requirement-label和select-requirement-label只指其中一个成员的。 - 这个元素本身不能获得焦点：
focus()会把焦点交给触发器，页面自己的<label for>也会把焦点移到那里。按下标签行会让触发器获得焦点，不打开任何东西；按下触发器会打开列表；按下帮助文本什么都不会发生。 - 这个元素没有角色。用
label为它命名，标签绘制在别处时再加上label-hidden；绝不要用aria-label，它在这里不为任何东西命名。 - 属性（attribute）就是成员自己的那些：
label-hidden、supporting-text、error-text、required-mark、required-text、optional-text、readonly。 - 既不是选项、不是选项组，也不是
label-icon或leading-icon的字形的子元素，不会绘制；调试构建会报告这一点。 - 在元素完成定义之前，它的选项是连续文本。请隐藏
tanrei-select-field:not(:defined) > *，并预留高度。必须在没有脚本时也能工作的页面，使用原生的<select>和它自己的<label>。
- 写一个标签，说明选择的是什么，并让它在表单中保持可见。
- 按用户查找的方式排列选项：按字母顺序、按数字顺序，或者把常用的放在前面。
- 给长列表分组，并给每个组一个简短的标题。
- 只有在大多数用户都会选择某个值时，才预先选中它。
- 让字段靠所在的位置得到宽度：表单的一列。方框会填满它。
- 不要在栏或工具栏里使用带
labelHidden的下拉选择字段。那里该用的是单独的下拉选择框，由它自己的label命名。 - 不要把占位符当作标签。一旦选择了某个选项，它就消失了。
- 不要在没有说明的情况下，在
change时跳转、提交或删除。用户在列表中移动，是为了阅读它。 - 不要把下拉选择字段放进字段。它本身已经是字段；调试构建会报告这一点。字段框住的控件是下拉选择框。
- 不要用
aria-label为它命名。不该绘制标签的地方，给出label和labelHidden。
- 角色
combobox- 标注
- The select field adds nothing to what its members expose and coordinates nothing: the Field gives the select its name, its description and its required, invalid and disabled states (FLD-8, FLD-10, FLD-11, FLD-14), and the select carries them on its own trigger and names its list by the same name (SEL-11, SEL-48). Assistive technology meets one control that opens a list of choices, named by label, with the chosen option's label as its value — exactly as it meets a Field around a select written by hand.
- 最小目标
- 即使外观尺寸更小，点击区域也满足最小目标尺寸。 minimum 32px · pointer 44px · spacing 8px · touch 48px
键盘操作
| 按键 | 动作 |
|---|---|
| Every key | The select's (its accessibility block; SEL-23, SEL-27, SEL-28, SEL-31, SEL-33, SEL-34). The select field handles no key and adds no focus stop (SEF-3). |
备注
- One level down is the same thing: a Field with a select in it, holding the same options. Every fixture has that pair as its twin, and the accessibility tree of the two is the same (SEF-1).
- On the web the two members stand in the select field's own shadow root, so the form meets the select field and not the select (SEF-2), focus passes through to the trigger (SEF-3), and the options, which stay the product's children, reach the select through a slot and are read by it as data.
- A select with no visible label of its own — in a header, a toolbar, a column of a table — is the bare select, named by its own label, not a select field with labelHidden.
生成自 specs/select-field.spec.json, tokens/sys/measure.tokens.json
- 它是一个不可编辑的组合框，也就是下拉选择框的那一个。它的名称是
label，无论标签是否绘制；它的描述是显示出来的辅助文本或错误文本，字段为选填时还加上选填文字。 error为 true 时，它暴露为无效；设置了required时，暴露为必填；disabled为 true 时，暴露为禁用；readOnly为 true 时，暴露为只读；列表打开时，暴露为已展开。- 名称、描述和状态的关联方式，与字段把它们关联到它框住的任何控件时完全一样。在下一层手写的字段，是同一个控件。
- 画出来的标签、必填和选填标记以及字形，不会再暴露第二次。
- 它只是一个 Tab 停靠点。按下标签会把焦点移到触发器上，不打开任何东西；按下帮助文本什么都不会发生。
- 焦点在下拉选择字段里时出现的错误，由它的字段成员以礼貌（polite）的方式朗读一次。
- 列表里的一切——活动选项，选项的名称、描述和状态，以及各个组——都是下拉选择框的，见下拉选择框的页面。
- 方向、放大的文本和强制颜色模式，由各个成员各自应对。
- 它没有自己的文字。
requiredText和optionalText留空时，由字段从产品的文字里读取。
Web 上的已知差距都是它的成员的差距：两个组之间的分隔线没有作为分隔符暴露；键入查找按 JavaScript 的方式比较标签；在元素完成定义之前，除了作为文本的选项之外什么都不绘制。
- 为每个下拉选择字段提供
label，并为每个选项提供标签。 - 自己校验值，设置
error，并编写说明如何改正的errorText。 - 给出必填和选填的文字：把
required-text和optional-text写在下拉选择字段上，或者用setWords({ requiredText, optionalText })为整个产品只给一次。Tanrei 不自带任何文字：没有requiredText时，小标签的位置上是一个星号；没有optionalText时，不绘制小标签，也不朗读任何内容。参见产品的文字。 - 在同一个下拉选择字段里，让各个选项的值保持唯一。