字段

概览

link

Web

tanrei-field

schedule

SwiftUI

TanreiField

radio_button_unchecked

Jetpack Compose

TanreiField

radio_button_unchecked

Flutter

TanreiField

radio_button_unchecked

React Native

Field

radio_button_unchecked

生成自 docs/status/status.json, specs/field.spec.json

滑块和开关，各由一个字段命名、提供帮助文本并加上标记

文本字段可以说明自己是什么、是否必须填写、该怎么填，以及填写的内容为什么被拒绝。字段把同样的四样东西交给做不到这些的控件：滑块、开关、文本输入框、颜色输入框、一次性验证码输入框，或者你的产品自己构建的控件。文本字段本身就是包住一个文本输入框的字段。标签位于控件上方，帮助文本位于控件下方。字段处于错误状态时，错误文本取代帮助文本的位置，所以处于错误状态的表单不会比平时更高；设计系统也可以改为保留帮助文本，把错误文本加在它的下方。

字段只绘制这个框架，别无其他。它没有容器，没有值，也没有事件；控件保留自己的外观、按键、事件，以及在表单中的位置。

在 Web 上它是 <tanrei-field>。其他平台尚未实现。

用法

link

<tanrei-field label="音量" supporting-text="适用于提醒和媒体。" optional optional-text="选填">
  <tanrei-slider name="volume" value="40"></tanrei-slider>
</tanrei-field>

<!-- 校验由产品来做；字段显示原因，并把控件标记为无效。 -->
<tanrei-field label="音量" required required-text="必填" error error-text="请选择大于 0 的音量。">
  <tanrei-slider name="volume" value="0"></tanrei-slider>
</tanrei-field>

<!-- 文本输入框：字段为它命名，帮助文本从文本开始的位置起笔，并画出交给它的计数。 -->
<tanrei-field label="显示名称" supporting-text="显示在你的评论旁边。" count-text="2/40">
  <tanrei-text-input name="display-name" value="李华" maxlength="40" counter></tanrei-text-input>
</tanrei-field>

<!-- 自己有名称的控件：字段的标签留空。 -->
<tanrei-field supporting-text="你可以随时撤回同意。">
  <tanrei-checkbox label="我同意使用条款"></tanrei-checkbox>
</tanrei-field>

<script type="module">
  import '@tanrei/web/components/field';
</script>

import { Field, Slider } from '@tanrei/react';

<Field label="音量" supportingText="适用于提醒和媒体。" error={tooQuiet} errorText="请选择大于 0 的音量。">
  <Slider value={volume} onChange={(event) => setVolume(event.detail.value)} />
</Field>

规格

link

三种必填和选填标记、错误、禁用的字段，以及标签的字形

volume_up

帮助文本与错误：错误文本取代帮助文本的位置

字段里的文本输入框：带帮助文本和计数的，以及处于错误状态的

包住文本输入框

link

包住文本输入框的字段，就是手写出来的文本字段：画面、名称、描述和状态都相同。只有输入框自己知道的事，由它告诉所在的字段，字段照着做：

输入框告诉字段	字段
它的文本离它的边有多远：它的内边距，以及前置图标	让辅助文本那一行从那里开始、到那里结束，于是帮助文本从文本开始的位置起笔
标签由它自己绘制，浮在 filled 或 outlined 的方框里	不绘制标签行，也不绘制必填和选填小标签，但仍然为输入框命名。必填的输入框会在浮动标签后面带一个星号，选填的则带上 optionalText 这个词
它拒绝了一个日期或时间：只填了一半，或者不可用	像 error 为 true 时那样处于错误状态，并显示输入框为此给出的文字

countText 是关于控件的值的计数，写成要画出来的样子（“2/40”）。字段把它画在辅助文本那一行的末尾，此外不拿它做任何事：字段不计数，并且不让辅助技术读到这个画出来的计数，因为控件会说出自己的计数。每次 input 时，用输入框的 countText 来写它。文本字段会自己做这件事。

valueText 是用文字写出的控件当前的值（“40 %”“$100 – $300”），用于从控件本身读不出值的控件：滑块。字段把它画在标签行的末尾，与标签的第一行对齐，此外不拿它做任何事：字段绝不读取值，也不为值设定格式，并且不让辅助技术读到这段画出来的文字，因为控件会说出自己的值。如果它会让标签只剩下不到半行，它就在标签之后单独占一行。标签不绘制时，它也不绘制。每次 input 时，用滑块的 shownValueText 来写它——滑块字段会自己做这件事，它就是为滑块准备好的字段。

里面放着滑块的字段，用文字写出的值位于标签行的末尾

包住下拉选择框

link

包住下拉选择框的字段，就是手写出来的下拉选择字段：画面、名称、描述和状态都相同。下拉选择框的选项是它自己的子元素。只有它自己知道的事，由它告诉所在的字段，字段照着做：

下拉选择框告诉字段	字段
它的值离它的边有多远：它的内边距，以及前置图标	让辅助文本那一行从那里开始、到那里结束，于是帮助文本从值开始的位置起笔
标签由它自己绘制，浮在 filled 或 outlined 的方框里	不绘制标签行，也不绘制必填和选填小标签，但仍然为下拉选择框命名。必填的下拉选择框会在浮动标签后面带一个星号
只要它的列表开着，它就画成聚焦的样子	在这段时间里用聚焦时的颜色绘制标签和帮助文本，无论焦点是否在字段内

构成

部件	说明
1 label	Names the control: above it, from the start edge, still, and never cut. The requirement mark follows it. Left out where the control draws the label itself, floating in its own box (FLD-25).
2 label-icon · 可选	A glyph of the icon set before the label, decorative to assistive technology.
3 requirement-label · 可选	After the label: the Tag component at its small size, drawn as every small tag is and never a control, saying the control is required or optional; or, for required, an asterisk after the label.
4 value-text · 可选	The control's present value in words, at the end of the label row: for a control whose value cannot be read from the control itself (a slider). Words the field is given; it never reads or formats a value.
5 control	The one control the field frames: a control that has no label, help and error of its own (a slider, a switch, a control the product built). It keeps its own tokens, states, keyboard, events and value; the field gives it a name, a description, and its required, invalid and disabled states.
6 supporting-text · 可选	A line of help below the control, from where the control's content starts (FLD-26), It stays while the field is in error, with the error text below it. No row is drawn, and no room kept, while there is neither a help, an error text nor a count.
7 error-text · 可选	The reason the value was refused, in words, in the supporting row: in the help's place, directly below the control, or below the help, which stays, where comp.field.error-text.placement is append (FLD-7, FLD-31). Drawn only while the field is in error; no room is kept for it before.
8 counter · 可选	A count about the control's value, in the words the field is given (countText) — a text input's characters typed and, after a slash, the most allowed — at the end of the supporting row's first line (FLD-27). The field draws it and does not count.

属性

属性	类型	默认值	说明
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.
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).
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).
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.
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.
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.
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.
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.
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.
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.
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.
countText	string	""	A count about the control's value, as it is to be drawn ("12/40"), at the end of the supporting row. For a control that keeps a count (a text input whose counter is true). The product's, or the composed component's that holds the field; kept from assistive technology, because the control says its own count.
valueText	string	""	The control's present value in words ("40 %", "$100 – $300"), drawn at the end of the label row. For a control whose value cannot be read from the control itself (a slider). The product's, or the composed component's that holds the field; kept from assistive technology, because the control says its own value.

插槽

插槽	说明
label-icon	A glyph before the label.

条目

该组件重复排列的条目种类。测试样例按顺序列出条目；各平台以各自的惯用方式为每个种类命名。

slider

A Slider as the field's control: the slider component, named, described and disabled by the field, otherwise drawn and behaving as it does anywhere.

属性	类型	默认值	说明
value	number	0	Its value, as the Slider's value.
startValue	number	0	As the Slider's startValue.
range	boolean	false	As the Slider's range.
min	number	0	As the Slider's min.
max	number	100	As the Slider's max.
step	number	0	As the Slider's step.
valueIndicator	none | active | always	"none"	As the Slider's valueIndicator.
valueText	string	""	As the Slider's valueText.
startValueText	string	""	As the Slider's startValueText.
startLabel	string	""	As the Slider's startLabel.
label	string	""	As the Slider's label.

规格	Web	SwiftUI	Jetpack Compose	Flutter	React Native
条目	tanrei-slider	TanreiSlider	TanreiSlider	TanreiSlider	Slider
value · 属性	value	value	value	value	value
startValue · 属性	startValue	value	value	start	startValue
range · 属性	range	value	value	range	range
min · 属性	min	bounds	valueRange	min	minimumValue
max · 属性	max	bounds	valueRange	max	maximumValue
step · 属性	step	step	step	step	step
valueIndicator · 属性	valueIndicator	valueIndicator	valueIndicator	valueIndicator	valueIndicator
valueText · 属性	valueText	valueText	stateDescription	semanticValue	valueText
startValueText · 属性	startValueText	startValueText	startStateDescription	startSemanticValue	startValueText
startLabel · 属性	startLabel	startLabel	startContentDescription	startSemanticLabel	startAccessibilityLabel
label · 属性	label	label	contentDescription	semanticLabel	accessibilityLabel
备注	A tanrei-slider child in the default slot, as anywhere, without a label of its own: the field names it.

switch

A Switch as the field's control, with no label of its own: the field's label names it.

属性	类型	默认值	说明
checked	boolean	false	Whether it is on, as the Switch's checked.

规格	Web	SwiftUI	Jetpack Compose	Flutter	React Native
条目	tanrei-switch	TanreiSwitch	TanreiSwitch	TanreiSwitch	Switch
checked · 属性	checked	isOn	checked	value	value

checkbox

A Checkbox as the field's control. It names itself with its own label, so the field's label is left empty and the field adds help and an error.

属性	类型	默认值	说明
checked	boolean	false	Whether it is on, as the Checkbox's checked.
label	string	""	Its own label, drawn beside the box, as the Checkbox's label.

规格	Web	SwiftUI	Jetpack Compose	Flutter	React Native
条目	tanrei-checkbox	TanreiCheckbox	TanreiCheckbox	TanreiCheckbox	Checkbox
checked · 属性	checked	isOn	checked	value	value
label · 属性	label	title	label	label	label

one-time-code-input

A One-time-code input as the field's control, with no label of its own: the field names it, describes it and puts it in its error condition.

属性	类型	默认值	说明
value	string	""	The code entered so far, as the One-time-code input's value.
groupSize	number	0	How many cells a group has, as the One-time-code input's groupSize.

规格	Web	SwiftUI	Jetpack Compose	Flutter	React Native
条目	tanrei-one-time-code-input	TanreiOneTimeCodeInput	TanreiOneTimeCodeInput	TanreiOneTimeCodeInput	OneTimeCodeInput
value · 属性	value	code	value	controller	value
groupSize · 属性	groupSize	groupSize	groupSize	groupSize	groupSize

file-upload

A File upload as the field's control, in its button layout and with no label of its own: the field's label names its group, and the field's help, error and requirement join the description of its trigger (FUP-32). The item's content is the label of the trigger, the product's own Button.

属性	类型	默认值	说明
constraintsText	string	""	The limits in words, as the File upload's constraintsText: drawn below the trigger, and still read while the field shows its error.

规格	Web	SwiftUI	Jetpack Compose	Flutter	React Native
条目	tanrei-file-upload	TanreiFileUpload	TanreiFileUpload	TanreiFileUpload	FileUpload
constraintsText · 属性	constraintsText	constraintsText	constraintsText	constraintsText	constraintsText
备注	A tanrei-file-upload child in the default slot, without a label of its own, holding the product's own tanrei-button in its trigger slot.

file-picker

A File picker as the field's control, in its button layout and with no label of its own: the field's label names its group, and the field's help, error and requirement join the description of its trigger (FPK-21). The item's content is the label of the trigger, the product's own Button.

属性	类型	默认值	说明
constraintsText	string	""	The limits in words, as the File picker's constraintsText: drawn below the trigger, and still read while the field shows its error.
selectionText	string	""	What is chosen now, in the product's words, as the File picker's selectionText: beside the trigger.

规格	Web	SwiftUI	Jetpack Compose	Flutter	React Native
条目	tanrei-file-picker	TanreiFilePicker	TanreiFilePicker	TanreiFilePicker	FilePicker
constraintsText · 属性	constraintsText	constraintsText	constraintsText	constraintsText	constraintsText
selectionText · 属性	selectionText	selectionText	selectionText	selectionText	selectionText
备注	A tanrei-file-picker child in the default slot, without a label of its own, holding the product's own tanrei-button in its trigger slot.

text-input

A Text input as the field's control: the pair a text field is. The field names it, describes it and puts it in its error condition; the input says back what only it knows — that it draws the label itself, where its text starts and ends, an entry error (FLD-25, FLD-26, FLD-28).

属性	类型	默认值	说明
variant	stacked | filled | outlined	"stacked"	As the Text input's variant.
size	small | medium | large	"medium"	As the Text input's size.
type	text | email | password | number | search | tel | url | code | date | time | date-time	"text"	As the Text input's type.
value	string	""	As the Text input's value.
placeholder	string	""	As the Text input's placeholder.
readOnly	boolean	false	As the Text input's readOnly.
multiline	boolean	false	As the Text input's multiline.
minRows	number	2	As the Text input's minRows.
maxRows	number	0	As the Text input's maxRows.
resize	auto | manual | fixed	"auto"	As the Text input's resize.
resizeAxis	vertical | both	"vertical"	As the Text input's resizeAxis.
resizeLabel	string	""	As the Text input's resizeLabel.
wrap	boolean	true	As the Text input's wrap.
maxLength	number	0	As the Text input's maxLength.
counter	boolean	false	As the Text input's counter.
prefixText	string	""	As the Text input's prefixText.
suffixText	string	""	As the Text input's suffixText.
locale	string	""	As the Text input's locale.
segmentEmptyText	string	""	As the Text input's segmentEmptyText.
picker	boolean	false	As the Text input's picker.
pickerLabel	string	""	As the Text input's pickerLabel.
entries	strings		What was entered already: each string is drawn as one small input Chip in the Text input's entries slot (TXI-64), in order — disabled while the field is, and without its remove action while the input is read-only. A product writes these chips by hand; a chip field makes them from its value.
entryRemoveLabel	string	""	The accessible name of each entry's remove action, with {entry} standing for the entry's text ("Remove {entry}"): what a product writes on each chip by hand as the Chip's removeLabel.

规格	Web	SwiftUI	Jetpack Compose	Flutter	React Native
条目	tanrei-text-input	TanreiTextInput	TanreiTextInput	TanreiTextInput	TextInput
variant · 属性	variant	variant	variant	variant	variant
size · 属性	size	size	size	size	size
type · 属性	type	type	type	type	type
value · 属性	value	text	value	controller	value
placeholder · 属性	placeholder	prompt	placeholder	hintText	placeholder
readOnly · 属性	readOnly	readOnly	readOnly	readOnly	readOnly
multiline · 属性	multiline	axis	singleLine	multiline	multiline
minRows · 属性	minRows	lineLimit	minLines	minLines	minRows
maxRows · 属性	maxRows	lineLimit	maxLines	maxLines	maxRows
resize · 属性	resize	resize	resize	resize	resize
resizeAxis · 属性	resizeAxis	resizeAxis	resizeAxis	resizeAxis	resizeAxis
resizeLabel · 属性	resizeLabel	resizeLabel	resizeContentDescription	resizeSemanticLabel	resizeAccessibilityLabel
wrap · 属性	noWrap	wrap	softWrap	softWrap	wrap
maxLength · 属性	maxLength	maxLength	maxLength	maxLength	maxLength
counter · 属性	counter	counter	counter	showCounter	counter
prefixText · 属性	prefixText	prefix	prefix	prefixText	prefix
suffixText · 属性	suffixText	suffix	suffix	suffixText	suffix
locale · 属性	locale	locale	locale	locale	locale
segmentEmptyText · 属性	segmentEmptyText	segmentEmptyText	segmentEmptyText	segmentEmptyText	segmentEmptyText
picker · 属性	picker	onPickerRequest	onPickerRequest	onPickerRequest	onPickerRequest
pickerLabel · 属性	pickerLabel	pickerLabel	pickerContentDescription	pickerSemanticLabel	pickerAccessibilityLabel
entries · 属性	entries	entries	entries	entries	entries
entryRemoveLabel · 属性	entryRemoveLabel	entryRemoveLabel	entryRemoveLabel	entryRemoveLabel	entryRemoveLabel
备注	A tanrei-text-input child in the default slot, without a label of its own: the field names it, and floats nothing itself. The two elements by hand are the twin of tanrei-text-field.

number-input

A Number input as the field's control: the pair a number field is. The field names it, describes it and puts it in its error condition; the input says back what only it knows — that it draws the label itself, where its number's line starts and ends, a text that is not a number (FLD-25, FLD-26, FLD-28).

属性	类型	默认值	说明
variant	stacked | filled | outlined	"stacked"	As the Number input's variant.
size	small | medium | large	"medium"	As the Number input's size.
value	number	null	As the Number input's value.
placeholder	string	""	As the Number input's placeholder.
readOnly	boolean	false	As the Number input's readOnly.
min	number	null	As the Number input's min.
max	number	null	As the Number input's max.
step	number	1	As the Number input's step.
steppers	boolean	true	As the Number input's steppers.
incrementLabel	string	""	As the Number input's incrementLabel.
decrementLabel	string	""	As the Number input's decrementLabel.
prefixText	string	""	As the Number input's prefixText.
suffixText	string	""	As the Number input's suffixText.
valueText	string	""	As the Number input's valueText.
align	start | end	"start"	As the Number input's align.
minFractionDigits	number	0	As the Number input's minFractionDigits.
maxFractionDigits	number	3	As the Number input's maxFractionDigits.
locale	string	""	As the Number input's locale.

规格	Web	SwiftUI	Jetpack Compose	Flutter	React Native
条目	tanrei-number-input	TanreiNumberInput	TanreiNumberInput	TanreiNumberInput	NumberInput
variant · 属性	variant	variant	variant	variant	variant
size · 属性	size	size	size	size	size
value · 属性	value	value	value	value	value
placeholder · 属性	placeholder	prompt	placeholder	hintText	placeholder
readOnly · 属性	readOnly	readOnly	readOnly	readOnly	readOnly
min · 属性	min	in	min	min	min
max · 属性	max	in	max	max	max
step · 属性	step	step	step	step	step
steppers · 属性	noSteppers	steppers	steppers	steppers	steppers
incrementLabel · 属性	incrementLabel	incrementLabel	incrementContentDescription	incrementSemanticLabel	incrementAccessibilityLabel
decrementLabel · 属性	decrementLabel	decrementLabel	decrementContentDescription	decrementSemanticLabel	decrementAccessibilityLabel
prefixText · 属性	prefixText	prefix	prefix	prefixText	prefix
suffixText · 属性	suffixText	suffix	suffix	suffixText	suffix
valueText · 属性	valueText	valueText	stateDescription	semanticValue	valueText
align · 属性	align	align	align	align	align
minFractionDigits · 属性	minFractionDigits	minFractionDigits	minFractionDigits	minFractionDigits	minFractionDigits
maxFractionDigits · 属性	maxFractionDigits	maxFractionDigits	maxFractionDigits	maxFractionDigits	maxFractionDigits
locale · 属性	locale	locale	locale	locale	locale
备注	A tanrei-number-input child in the default slot, without a label of its own: the field names it, and floats nothing itself. The two elements by hand are the twin of tanrei-number-field. The input says drawsLabel, inset and refusal through the connection and no count.

color-input

A Color input as the field's control: the pair a color field is. The field names it, describes it and puts it in its error condition; the input says back what only it knows — that it draws the label itself, where the value's text starts, after its swatch, and an entry error (FLD-25, FLD-26, FLD-28).

属性	类型	默认值	说明
variant	stacked | filled | outlined	"stacked"	As the Color input's variant.
size	small | medium | large	"medium"	As the Color input's size.
value	string	""	As the Color input's value.
picker	boolean	false	As the Color input's picker.
pickerLabel	string	""	As the Color input's pickerLabel.

规格	Web	SwiftUI	Jetpack Compose	Flutter	React Native
条目	tanrei-color-input	TanreiColorInput	TanreiColorInput	TanreiColorInput	ColorInput
variant · 属性	variant	variant	variant	variant	variant
size · 属性	size	size	size	size	size
value · 属性	value	hex	value	controller	value
picker · 属性	picker	showsPicker	onPickerRequest	onPickerRequest	onPickerRequest
pickerLabel · 属性	pickerLabel	pickerLabel	pickerContentDescription	pickerSemanticLabel	pickerAccessibilityLabel
备注	A tanrei-color-input child in the default slot, without a label of its own: the field names it, and floats nothing itself. The two elements by hand are the twin of tanrei-color-field.

select

A Select as the field's control: the pair a select field is. The field names it, describes it and puts it in its error condition; the select says back what only it knows — that it draws the label itself in a look that floats one, where its value starts and ends, and that its list is open (FLD-13, FLD-25, FLD-26). In a fixture, an item of this kind holds the select's own options as its items and fills the select's own slots.

属性	类型	默认值	说明
variant	stacked | filled | outlined	"stacked"	As the Select's variant.
size	small | medium | large	"medium"	As the Select's size.
value	string	""	As the Select's value.
placeholder	string	""	As the Select's placeholder.
readOnly	boolean	false	As the Select's readOnly.
open	boolean	false	As the Select's open.
separation	auto | divider | gap	"auto"	As the Select's separation.

规格	Web	SwiftUI	Jetpack Compose	Flutter	React Native
条目	tanrei-select	TanreiSelect	TanreiSelect	TanreiSelect	Select
variant · 属性	variant	variant	variant	variant	variant
size · 属性	size	size	size	size	size
value · 属性	value	selection	value	value	value
placeholder · 属性	placeholder	prompt	placeholder	hintText	placeholder
readOnly · 属性	readOnly	readOnly	readOnly	readOnly	readOnly
open · 属性	open	isPresented	expanded	controller	open
separation · 属性	separation	separation	separation	separation	separation
备注	A tanrei-select child in the default slot, without a label of its own, holding its tanrei-option children: the field names it, describes it and marks it through the connection, and the select says back that it draws the label, where its value starts and that its list is open (SEL-63).	The select as the content of the Field, with its options as its own content.	The select as the content of the Field, with its options as its own content.	The select as the content of the Field, with its options as its own content.	The select as the content of the Field, with its options as its own content.

combobox

A Combobox as the field's control: the pair a combobox field is. The field names it, describes it and puts it in its error condition; the combobox says back what only it knows — that it draws the label itself in a look that floats one, where its input text starts and ends, and that its list is open (FLD-13, FLD-25, FLD-26). In a fixture, an item of this kind holds the combobox's own options as its items and fills the combobox's own slots.

属性	类型	默认值	说明
variant	stacked | filled | outlined	"stacked"	As the Combobox's variant.
size	small | medium | large	"medium"	As the Combobox's size.
value	string	""	As the Combobox's value.
inputValue	string	""	As the Combobox's inputValue.
placeholder	string	""	As the Combobox's placeholder.
readOnly	boolean	false	As the Combobox's readOnly.
open	boolean	false	As the Combobox's open.
allowCustomValue	boolean	false	As the Combobox's allowCustomValue.
filter	contains | none	"contains"	As the Combobox's filter.
chevron	boolean	true	As the Combobox's chevron.
clearable	boolean	false	As the Combobox's clearable.
clearLabel	string	""	As the Combobox's clearLabel.
status	idle | loading | error	"idle"	As the Combobox's status.
statusText	string	""	As the Combobox's statusText.
emptyText	string	""	As the Combobox's emptyText.
separation	auto | divider | gap	"auto"	As the Combobox's separation.

规格	Web	SwiftUI	Jetpack Compose	Flutter	React Native
条目	tanrei-combobox	TanreiCombobox	TanreiCombobox	TanreiCombobox	Combobox
variant · 属性	variant	variant	variant	variant	variant
size · 属性	size	size	size	size	size
value · 属性	value	selection	value	value	value
inputValue · 属性	inputValue	text	inputValue	controller	inputValue
placeholder · 属性	placeholder	prompt	placeholder	hintText	placeholder
readOnly · 属性	readOnly	readOnly	readOnly	readOnly	readOnly
open · 属性	open	isPresented	expanded	menuController	open
allowCustomValue · 属性	allowCustomValue	allowCustomValue	allowCustomValue	allowCustomValue	allowCustomValue
filter · 属性	filter	filter	filter	filter	filter
chevron · 属性	noChevron	chevron	chevron	chevron	chevron
clearable · 属性	clearable	clearable	clearable	clearable	clearable
clearLabel · 属性	clearLabel	clearLabel	clearContentDescription	clearSemanticLabel	clearAccessibilityLabel
status · 属性	status	status	status	status	status
statusText · 属性	statusText	statusText	statusText	statusText	statusText
emptyText · 属性	emptyText	emptyText	emptyText	emptyText	emptyText
separation · 属性	separation	separation	separation	separation	separation
备注	A tanrei-combobox child in the default slot, without a label of its own: the field names it, and floats nothing itself. Its <tanrei-option> and <tanrei-option-group> children are its own. The two elements by hand are the twin of tanrei-combobox-field.	TanreiCombobox as the field's content, with its own options. Planned.	TanreiCombobox as the field's content, with its own options. Planned.	TanreiCombobox as the field's content, with its own options. Planned.	Combobox as the field's content, with its own options. Planned.

chat-composer

A Chat composer as the field's control, with no label of its own: the field's label names it and its typing area, the field's help and, in error, its error text are the last part of the typing area's description, and the field's error and disabled are the composer's (CCM-28). The composer draws its own capsule and none of the field's rows.

属性	类型	默认值	说明
placeholder	string	""	As the Chat composer's placeholder.
sendLabel	string	""	As the Chat composer's sendLabel: the name of its send button, which the field does not give (CCM-31).

规格	Web	SwiftUI	Jetpack Compose	Flutter	React Native
条目	tanrei-chat-composer	TanreiChatComposer	TanreiChatComposer	TanreiChatComposer	ChatComposer
placeholder · 属性	placeholder	prompt	placeholder	hintText	placeholder
sendLabel · 属性	sendLabel	sendLabel	sendContentDescription	sendSemanticLabel	sendAccessibilityLabel
备注	A tanrei-chat-composer child in the default slot, without a label of its own: the field names it, and its texts join the typing area's description (CCM-28).

状态

行为

以 EARS 形式写成的需求。每个平台的实现都按这些 ID 逐条测试。需求原文取自规格文件，原样以英文呈现。

ID	需求
FLD-1	THE field SHALL lay out, from top to bottom and from its start edge: its label row (FLD-2), its control comp.field.label.gap below the last line of that row, and its supporting row (FLD-7) comp.field.supporting-text.gap below the control. It SHALL be as wide as its layout gives it and give the control that whole width to lay itself out in — a control that fills the width it is given fills it, and a control with a size of its own keeps it, at the start edge — and SHALL be as tall as its rows and its control together. THE field SHALL draw no container, edge, fill or elevation of its own, SHALL add no padding around its rows, and SHALL NOT change the size, the look or the behaviour of its control.
FLD-2	WHILE label is not empty, labelHidden is false and its control does not draw the label itself (FLD-25) THE field SHALL draw label above its control, from the field's start edge, in comp.field.label.typescale and comp.field.standard.label.color (comp.field.standard.error.label.color WHILE error is true). The label SHALL keep its place, size and style whatever the control holds, SHALL wrap onto as many lines as it needs, and SHALL never be cut with an ellipsis or drawn over the control, because text enlarged to 200% must lose no content. WHILE labelHidden is true or label is empty THE field SHALL draw neither the label row nor the gap below it, and SHALL draw no label glyph and no requirement mark (FLD-3, FLD-6).
FLD-3	WHILE the label is drawn and the label-icon slot holds a glyph THE field SHALL draw it before the label, comp.field.label-icon.gap from it, at comp.field.label-icon.size, centred on the label's first line, with sys.icon.family.unselected and sys.icon.fill.unselected, sys.icon.weight and an optical size clamped between sys.icon.optical-size.min and sys.icon.optical-size.max, in comp.field.standard.label-icon.color (comp.field.standard.error.label-icon.color WHILE error is true), and SHALL keep it from assistive technology, because the label names the control; WHILE the label is not drawn THE field SHALL NOT draw the label glyph and SHALL report it in debug builds.
FLD-4	THE field SHALL take from required and optional what the form asks of its control: WHILE required is true it exposes the control as required (FLD-10) and draws the required mark (FLD-5, FLD-6); WHILE optional is true it draws the optional tag (FLD-5) and adds optionalText to the control's description (FLD-11), because assistive technology has no state for it; WHILE both are false it says nothing and draws nothing. THE field SHALL NOT validate because of required: it SHALL NOT set the error condition for a missing value or show an error text of its own; what a missing value means is the product's to say with error and errorText. WHILE disabled is true THE field SHALL keep its mark: an asterisk drawn from the field's disabled tokens (FLD-14), a requirement tag drawn as a tag inside something disabled (FLD-5, TAG-21).
FLD-5	WHILE the label is drawn and optional is true, or required is true and the required mark is tag (FLD-6), THE field SHALL draw after the label's text, comp.field.requirement.gap from it and centred on the label's last line, a requirement tag: the Tag component, drawn as every tag is — size small, variant filled for required and tonal for optional, status default, no glyph and no dot, its label requiredText or optionalText on one line (TAG-1, TAG-2, TAG-5) — from the Tag's own tokens (comp.tag.container.height.small, comp.tag.label.typescale.small, comp.tag.filled.container.color, comp.tag.tonal.container.color and the others those sentences name). THE field SHALL have no token for the requirement tag's fill, lettering, text style, paddings or corners and SHALL set none of the Tag's for it, so that a design system or a product that restyles its small tags restyles the requirement tag with them and nothing restyles the requirement tag alone. THE field SHALL draw the requirement tag the same at rest, WHILE focus is inside the field and WHILE error is true, because a tag has no states (TAG-9) and what the form asks has not changed; WHILE disabled is true THE field SHALL have it drawn as a tag inside something disabled (TAG-21), from the Tag's own disabled tokens, so that the tag fades with the label it follows and no part of a disabled field reads as live. The requirement tag is text, never a control: it SHALL take no focus and no hover, focus or press answer of its own (a press on it does what a press on the label does, FLD-12). It SHALL NOT make the label's row taller: where it is taller than the label's line it SHALL reach equally above and below that line. WHEN the label and the requirement tag do not fit on one line THE field SHALL wrap the label (FLD-2) and move the tag whole to a line of its own after the label's last line, never cutting or splitting it. WHILE requiredText or optionalText is empty THE field SHALL NOT draw the tag of that kind and in debug builds SHALL report it. THE field SHALL keep the required tag from assistive technology, because the required state already says it, and SHALL give the optional tag's text as part of the description (FLD-4).
FLD-6	WHILE required is true and the label is drawn THE field SHALL draw the required mark that requiredMark names — tag (FLD-5), asterisk or none — and WHILE requiredMark is auto, the one comp.field.requirement.mark names: that token follows sys.behavior.requirement-mark, the design system's one answer for every field and every set of controls, unless a layer gives comp.field.requirement.mark a value of its own. As asterisk it SHALL draw the character "*" after the label's text, comp.field.requirement.asterisk-gap from it, in the label's text style, in comp.field.standard.required-asterisk.color (comp.field.standard.error.required-asterisk.color WHILE error is true), and SHALL keep it from assistive technology, because the required state already says it; as none it SHALL draw no mark and still expose the required state. WHILE the label is not drawn THE field SHALL draw no mark, and SHALL still expose the required state and the optional description.
FLD-7	THE field SHALL draw its supporting row below the control, from the start edge of the control's content (FLD-26). It holds supportingText, the help, WHILE it is not empty, in comp.field.supporting-text.typescale and comp.field.standard.supporting-text.color (comp.field.standard.error.supporting-text.color WHILE the field is in error), and the error text WHILE the field is in error and has words for it (FLD-31). How the two share the row is the one comp.field.error-text.placement names. WHERE it is replace, its first value, THE field SHALL NOT draw the help WHILE it draws the error text, which stands in the help's place, because what the person must read then is what is wrong with the answer, and a field in error is no taller for it than at rest; WHEN the error text goes THE field SHALL draw the help again where it was. WHERE it is append THE field SHALL keep the help in its place and its words WHILE it draws the error text, and draw the error text below it, because the help says how to answer, which is what the person needs then. Each text SHALL wrap onto as many lines as it needs and never be cut. WHILE countText is not empty THE field SHALL draw it at the end of the row's first line (FLD-27). WHILE there is neither a help, an error text nor a count THE field SHALL draw neither the row nor its gap, and SHALL keep no room for it.
FLD-8	WHILE error is true THE field SHALL draw its label, its label glyph, its asterisk and its help from the error parts of its tokens (FLD-2, FLD-3, FLD-5 to FLD-7), SHALL draw its error text (FLD-31), SHALL expose its control as invalid to assistive technology, and SHALL put its control in the control's own error condition where the control has one (a checkbox's error), so that the control itself is marked and not only its text; a control with no error condition SHALL stay as it is drawn. THE field SHALL never set error itself: what a value means is the product's to validate. The one error it shows without it is its control's own refusal of an entry (FLD-28).
FLD-9	WHEN error becomes true, or errorText changes while error is true, and focus is inside the field THE field SHALL have assistive technology announce the shown error text once, politely; an error set while focus is elsewhere SHALL be read as part of the control's description when the control is next focused. THE field SHALL NOT move focus because of an error, and SHALL announce no other change of its texts: the help is not said again when the error appears, because it has not changed and is still read with the control (FLD-11).
FLD-10	THE field SHALL make label the accessible name of its control, whether or not the label is drawn (labelHidden), WHERE the control has no accessible name of its own; a control that names itself (a checkbox or a switch with its own label, a control the product named) SHALL keep that name, and WHERE such a control stands under a drawn label THE field SHALL in debug builds report that the control has two labels. WHILE label is empty and the control has no name of its own THE field SHALL still render and in debug builds report that the control has no accessible name. WHILE required is true THE field SHALL expose the control as required, whichever mark is drawn and where none is.
FLD-11	THE field SHALL make these the description of its control, in this order, after any description the control has of its own and whether or not the label is drawn: supportingText, WHILE the row draws it (FLD-7); the error text WHILE the field is in error (FLD-31); optionalText WHILE optional is true — the order in which a field group describes its set (FGR-11). The description SHALL say what the row draws: WHERE comp.field.error-text.placement is replace, the error text in the help's place WHILE the field is in error; WHERE it is append, the help and then the error text. WHEN one of these texts comes, goes or changes THE field SHALL expose the new description at once. The label glyph, the required tag and the asterisk SHALL NOT be exposed.
FLD-12	WHEN the user presses the label, the label glyph or the requirement mark THE field SHALL move focus to its control and do nothing else: it SHALL NOT activate, switch or change the control, and SHALL draw no press answer, because a press on a label is not an action. A press on the supporting row SHALL do nothing. THE field SHALL add no stop to the focus order and handle no key: its control is the only thing in it that takes focus, and the control's own keys are the control's.
FLD-13	WHILE focus is inside the field — on its control or on any part of it, however the focus was gained — or its control says that it is drawn focused (for one, a select or a combobox for as long as its list is open) THE field SHALL draw its label, its label glyph, its asterisk, its value text and its supporting row from its focused tokens (their error parts WHILE error is true), as a text input's box does (TXI-6), so that a form shows which field has focus in one way for every field; the control draws its own focus indicator, and THE field SHALL draw none. WHEN focus enters or leaves, or error or disabled changes, THE field SHALL change its colors over comp.field.motion.state-duration with comp.field.motion.state-easing, and at once WHERE motion is reduced.
FLD-14	WHILE disabled is true THE field SHALL draw every part of its own from its disabled tokens (of its error parts WHILE error is true) and its requirement tag as a tag inside something disabled (FLD-5, TAG-21), SHALL make its control disabled as that control's own disabled does — not focusable, not operable, exposed as disabled — and SHALL NOT answer a press on its label (FLD-12); WHILE disabled is false THE field SHALL NOT enable a control the product disabled itself. A disabled field SHALL keep its texts readable by assistive technology.
FLD-15	THE field SHALL frame exactly one control. IF it is given none THE field SHALL draw its rows without one and in debug builds report it; IF it is given more than one THE field SHALL lay them out in the order given, name, describe and mark only the first (FLD-8, FLD-10, FLD-11), and in debug builds report that a set of controls is a field group. IF its control is a component that has this frame already — a composed field, which is a Field and its one control (a text field, a select field) — THE field SHALL in debug builds report that the control is already a field and that the bare control is the one that field frames (for a text field, the text input), and SHALL hide neither frame.
FLD-16	WHILE the text size is enlarged THE field SHALL grow with its texts: the label and the supporting row wrap and never clip, the requirement tag grows with its text and keeps its paddings, the label glyph keeps comp.field.label-icon.size, the value text grows with its text and keeps the line FLD-29 gives it, and the rows keep their order and their gaps; at 200% no text SHALL be lost, lie over another part or need scrolling in two directions.
FLD-17	WHERE the platform draws with a person's own forced colors (the web's forced-colors mode, and a platform's equivalent where it has one) THE field SHALL draw its label, its asterisk, its value text, its supporting text and its error text in the platform's text color and its requirement tag as a tag is drawn there (an edge and a label in the text color, TAG-14), and SHALL rely on no color of its own to tell an error from help: the error is carried by the words of errorText, by the invalid state (FLD-8) and by the control's own error condition; the two texts, drawn in one color there, are told apart by their words and their order, the help first.
FLD-18	WHERE the layout direction is right-to-left THE field SHALL mirror its layout: the label row, the control and the supporting row start at the right edge, the label glyph stands at the right of the label and the requirement mark at its left, and the value text stands at the left end of the label row.
FLD-19	THE field SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the field is shown THE field SHALL draw itself for the new direction at once, without a motion of its own, keeping its control, with that control's value and focus.
FLD-20	WHERE the layout direction is right-to-left THE field SHALL draw the glyph of its label-icon slot mirrored left to right exactly when the system's icon set marks that glyph's name as mirrored or the product forces mirroring for that use, and unmirrored when the product forbids it: the icon helper mirrors the glyph inside its own box, about the box's vertical centre line, changing neither its place, size, color and fill nor the order FLD-18 gives. THE field SHALL NOT mirror a glyph itself, and SHALL NOT mirror content the product gives as an image or a view of its own rather than by a glyph's name.
FLD-21	THE field SHALL lay out its label, its value text, its supporting text and error text and the text of its requirement tag as text of its own direction, isolated from the text around it: each takes the base direction of its first strong character, or the layout direction where it has none, so that a left-to-right word, a number with its sign or unit, a telephone number and an address keep their own order in a right-to-left layout and reorder nothing beside them; THE field SHALL still place each and align its lines by the layout direction, not by the text's own.
FLD-22	WHEN requiredMark names a value the field does not know THE field SHALL behave as auto, and in debug builds THE field SHALL report the unknown value.
FLD-23	THE field SHALL leave its control what it is: the control keeps its own tokens, states, keyboard, events, value and place in a form, and THE field SHALL emit no event, hold no value and take no part in form submission. WHEN the control is replaced by another while the field is shown THE field SHALL name, describe and mark the new one (FLD-8, FLD-10, FLD-11, FLD-14) at once, and SHALL take back from the old one everything it gave it.
FLD-24	THE field SHALL have no words of its own: it SHALL take requiredText and optionalText from the instance's prop and, WHILE that is empty, from the product's words of the same name — the words a product sets once for all its components — and from nowhere else. IF neither gives requiredText WHILE required is true and the required mark is tag THE field SHALL draw the asterisk of FLD-6 in the tag's place, so that the requirement is still shown without a word, SHALL keep the required state on its control (FLD-10), and in debug builds SHALL report the missing words once. IF neither gives optionalText WHILE optional is true THE field SHALL draw no tag, SHALL add nothing to the description for it, and in debug builds SHALL report the missing words once.
FLD-25	WHILE its control draws the label itself — a control whose look floats its name inside its own box (for one, a text input of the filled or the outlined look, TXI-13) — THE field SHALL draw no label row, no gap below it, no label glyph and no requirement tag, as WHILE labelHidden is true (FLD-2), and SHALL still give the control label as its accessible name (FLD-10). With the name it SHALL give the control three things to draw the label by: whether labelHidden is true, so that the control draws none either; and the required mark, as an asterisk WHILE required is true and the mark FLD-6 names is tag or asterisk, and as none otherwise; and optionalText WHILE optional is true, because a person who sees the asterisk on the required fields of a form must also see which ones may be left out, and the optional tag of the label row has no room in a label that floats. The control draws both after the label's text, from its own tokens (for a text input, TXI-50). THE field SHALL keep its supporting row, its error condition, and the description and the states it gives (FLD-7 to FLD-11, FLD-14) unchanged. A press on a label the control draws is a press on the control, and the control's to answer (for a text input, TXI-8): FLD-12 speaks of the row the field draws. WHILE optional is true THE field SHALL keep optionalText in the description as well (FLD-11); WHILE the label-icon slot holds a glyph it SHALL report it as FLD-3 says. WHEN the control starts or stops drawing the label THE field SHALL leave out or draw its label row at once, without motion.
FLD-26	WHERE its control's content is inset from the control's own edges and the control says by how much — for one, a text input: from its start edge to where its text starts, past its inline padding and a leading icon, and the padding it keeps at its end edge (TXI-62) — THE field SHALL start its supporting row that far from its own start edge and end it that far before its end edge, so that the help and the error start where the text starts (FLD-7). The label row SHALL stay at the field's edges (FLD-2). A control that says nothing SHALL have the row at the field's edges, as a slider has. WHEN what the control says changes — its size, an icon that comes or goes, the layout direction — the row SHALL follow at once, without motion.
FLD-27	WHILE countText is not empty THE field SHALL draw it at the end of the supporting row's first line — beside the first line of the help, or of the error text WHILE there is no help — on one line that does not wrap, at least comp.field.counter.gap from every line of the help and of the error text, which both wrap in the room the count leaves beside it, and SHALL keep it in that place WHEN the error text comes or goes below a help, in comp.field.supporting-text.typescale with figures of equal width and in comp.field.standard.counter.color (comp.field.standard.error.counter.color WHILE the field is in error; their focused and disabled tokens as FLD-13 and FLD-14 say), and SHALL draw the row for the count alone WHILE there is no text to show. THE field SHALL draw the count as it is given and SHALL NOT count, format, describe or announce it, and SHALL keep the drawn count from assistive technology: countText is words the field is given — by the composed component that holds it (a text field gives its text input's count, TXF-67) or by the product that writes the pair by hand — about a control that makes the same count part of its own description and announces it (TXI-19). It SHALL lay the count out as text of its own direction (FLD-21), at the left end of the row in a right-to-left layout (FLD-18), in the platform's text color under forced colors (FLD-17), and WHILE the text size is enlarged SHALL keep it whole on its line while the text beside it wraps (FLD-16). A press on the count SHALL do nothing, as on the rest of the row (FLD-12). WHEN countText changes THE field SHALL draw the new text at once, without a motion.
FLD-28	WHILE its control reports that it refused what was entered — an entry error of the control's own (for one, a text input of type date, time or date-time committed half-filled, or with a date or a time that is not available, TXI-30) — THE field SHALL be in the error condition exactly as WHILE error is true (FLD-8): it SHALL draw its error parts, expose the control as invalid, and show as its error text (FLD-31) the words the control gives for the refusal — errorText WHILE the control gives none — in its supporting row, where any error text stands (FLD-7, FLD-31); WHILE the control gives no words and errorText is empty THE field SHALL draw no error text, SHALL still mark itself and in debug builds SHALL report a refusal that has no words. WHEN the report begins, or its words change, while focus is inside the field THE field SHALL announce the error text as FLD-9 says. WHEN the control withdraws the report THE field SHALL return at once to what error and errorText say. THE field SHALL NOT validate for the control, and SHALL forget the report WHEN the control is replaced (FLD-23).
FLD-29	WHILE valueText is not empty and the label is drawn THE field SHALL draw valueText at the end edge of the label row, on the baseline of the label's first line, on one line, in comp.field.value-text.typescale and comp.field.standard.value-text.color (comp.field.standard.error.value-text.color WHILE error is true), and SHALL keep at least comp.field.value-text.gap between it and the label with its requirement mark: the label wraps in the room that is left (FLD-2) and the requirement tag moves to a line of its own as FLD-5 says. WHERE that leaves the label less than half of the row's width THE field SHALL instead draw the value text whole on a line of its own after the label row's last line, from the start edge, wrapping there where it must, and never cut. WHEN valueText changes THE field SHALL draw the new text at once, without a motion, and SHALL move no other part: the text is aligned to the end edge, so that only its own start moves. WHILE the label is not drawn THE field SHALL draw no value text, and it SHALL never draw one in the supporting row.
FLD-30	THE field SHALL keep the drawn value text from assistive technology and SHALL announce no change of it, because the control says its own value and a second reading would say it twice; a control that exposes no value is the product's to mend, not the frame's to speak for. A press on the value text SHALL do what a press on the label does (FLD-12). THE field SHALL NOT read, compute or format a value: valueText is words it is given.
FLD-31	WHILE the field is in error — error is true, or its control reports that it refused an entry (FLD-28) — and has words for it — errorText, or the control's own words for a refusal — THE field SHALL draw those words as its error text, in its supporting row: as the row's first line, comp.field.supporting-text.gap below the control — in the help's place WHERE comp.field.error-text.placement is replace (FLD-7), and WHILE supportingText is empty under either value — and WHERE it is append and supportingText is not empty, comp.field.error-text.gap below the last line of the help. It SHALL start where the help starts (FLD-26), be drawn in comp.field.supporting-text.typescale and comp.field.standard.error-text.color (its focused and disabled tokens as FLD-13 and FLD-14 say), wrap onto as many lines as it needs, never be cut, and never share a line with the help. WHILE the field is not in error, or is in error without words, THE field SHALL draw no error text and no gap for it and SHALL keep no room for one: under replace a field with a help is as tall in error as at rest while its error text takes as many lines as its help, under append it is taller by comp.field.error-text.gap and the lines of its error text, and a form at rest is no taller for errors it does not have. WHEN the error text appears, goes or changes its words THE field SHALL draw the row as it then is at once, with no motion of its own — what stands below the field moves with the layout, and only the colors of FLD-13 ease — so there is nothing here that reduced motion changes. THE field SHALL lay the error text out as text of its own direction (FLD-21), mirror it with its row (FLD-18), draw it in the platform's text color under forced colors (FLD-17), let it wrap and grow with enlarged text (FLD-16), and do nothing WHEN it is pressed (FLD-12).
FLD-32	IF required and optional are both true THEN THE field SHALL behave as WHILE required alone is true — it draws the required mark and no optional tag, and says no optionalText — and in debug builds SHALL report that optional is ignored, because a control is never both required and optional.
FLD-33	WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the field's host, by the attribute or by the ARIA property that reflects it, THE field SHALL move it to the data-aria- attribute of the same name, so that the host — which has no role — is no node of its own with a name, a description or a state, SHALL expose it on no element, and SHALL report it in debug builds, saying to write it on the control: the control is the product's own element, which keeps its own name, states and ARIA (FLD-10, FLD-23), and what the field gives it is its label, its texts and its marks (FLD-8, FLD-10, FLD-11, FLD-14). WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it to null, THE field SHALL take the moved value away.

各平台名称对照

对等并不意味着 API 完全相同。同一份契约，由各平台以自己的惯用方式表达。

规格	Web	SwiftUI	Jetpack Compose	Flutter	React Native
组件	tanrei-field	TanreiField	TanreiField	TanreiField	Field
label · 属性	label	label	label	labelText	label
labelHidden · 属性	labelHidden	labelsHidden	labelHidden	labelHidden	labelHidden
supportingText · 属性	supportingText	supportingText	supportingText	helperText	supportingText
errorText · 属性	errorText	errorText	errorText	errorText	errorText
error · 属性	error	error	isError	isError	error
disabled · 属性	disabled	disabled	enabled	enabled	disabled
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
countText · 属性	countText	countText	countText	countText	countText
valueText · 属性	valueText	valueText	valueText	valueText	valueText
备注	<tanrei-field label="Volume"><tanrei-slider></tanrei-slider></tanrei-field>: the control is the one element in the default slot. It stays in the product's light DOM, so it keeps its place in a <form>, its name and value, its events and its styles; the field is not form-associated and holds no value. The label, the asterisk, the supporting row and the requirement tag (a <tanrei-tag size="small">, filled or tonal, disabled while the field is, with nothing else set on it: it reads the Tag's tokens as every tag where the field stands does) are in the shadow root; the label glyph is the label-icon slot. An id cannot be referenced across a shadow boundary, so the field does not point aria-labelledby or aria-describedby at its own texts: it gives them as strings. A Tanrei control asks for them (it dispatches a composed tanrei-field-connect event when it is connected, the nearest field answers with { label, description, invalid, required, disabled } and tells it of every change), writes them on its inner native element or role holder, and lets its own label win. Any other element receives aria-label (only where it has neither aria-label nor aria-labelledby), aria-description, aria-invalid, aria-required and, where it has the property, disabled; the field removes exactly what it set when the element leaves the slot (slotchange, FLD-23). The announcement of FLD-9 is a visually hidden aria-live="polite" element in the shadow root, written only while :focus-within holds. A press on the label calls focus() on the control; focusin and focusout on the host select the focused tokens. Attributes are kebab-case: label-hidden, supporting-text, error-text, required-mark, required-text, optional-text. The host is display: block. Under forced-colors: active the texts are CanvasText. Words: the element has no words of its own. required-text and optional-text left empty read the product's words, set once with setWords() from @tanrei/web; the element draws again when they change. The exchange with a control runs both ways. Beside the name, the description and the three states, the field gives labelHidden and requiredMark (asterisk or none) to a control that draws the label itself; and a control may say drawsLabel, inset: { start, end } and refusal: { text } of itself through the same connection (FLD-25, FLD-26, FLD-28). A control that says none of them is framed as any other, and a field ignores what it does not know. The supporting row is a flex row whose padding-inline is the inset. The count is not in the exchange: count-text is an attribute of the field, drawn in a part="counter" element at the end of the supporting row, aria-hidden, white-space: nowrap, font-variant-numeric: tabular-nums (FLD-27). The supporting row holds two texts. part="supporting-text" is the help alone, not rendered while the error text stands in its place; part="error-text" is the error text — the row's first line under replace, a block below the help, --tanrei-comp-field-error-text-gap away, under append — in --tanrei-comp-field-standard-error-text-color, rendered only while the field is in error with words (FLD-31). The two are one column that takes the room beside the counter part, which is aligned to the first line. --tanrei-comp-field-error-text-placement is read by name (replace, the first, or append) from the cascade at each render, and the field draws again when the design system is switched. The aria-description the field gives its control is what the row draws (the help, the error text, or the two in that order) and the optional text, joined (FLD-11); the live region of FLD-9 is given the error text alone. shownText() of the frame does not choose between the two. The tag's element carries no custom property and is centred on the label's line without its height being read; required-mark takes tag; and --tanrei-comp-field-requirement-mark is var(--tanrei-sys-behavior-requirement-mark) until a layer sets it.	TanreiField("Volume", supportingText:, errorText:, error:, required:, optional:) { TanreiSlider(value: $volume) }, the glyph given by name through labelIcon:. labelHidden follows the .labelsHidden() environment and disabled follows .disabled(_:), which also disables the content. The content is one view; the field sets .accessibilityLabel, .accessibilityHint (the description) and the invalid and required values on it, and offers the same values in the environment (\.tanreiField) for a control the product built. The product's words are read from the \.tanreiWords environment value. Not built on this platform yet: the supporting row is a VStack of the help and, in error, the error text — in the help's place, or comp.field.error-text.gap below it, as comp.field.error-text.placement names (FLD-7); the hint is what the row draws, then the optional text (FLD-11, FLD-31). Not built on this platform yet: the requirement tag as this platform's Tag at its small size with nothing of the field's set on it (FLD-5); generated tokens with none of the field's values for it and with the system's choice of mark, which the field's own token follows (FLD-6); the first mark named tag.	TanreiField(label = "Volume", supportingText = …, isError = …, required = …, optional = …) { TanreiSlider(…) }, the glyph given by name through labelIcon. enabled is the inverse flag and is offered to the content through LocalTanreiFieldState, with the name, the description and isError; Tanrei controls read it, and a control the product built reads the same composition local. The field adds contentDescription, stateDescription and error(…) to the merged semantics of its content. The product's words are read from LocalTanreiWords. Not built on this platform yet: the supporting row is a Column of the help and, in error, the error text — in the help's place, or comp.field.error-text.gap below it, as comp.field.error-text.placement names (FLD-7); the description offered through LocalTanreiFieldState is what the row draws, then the optional text (FLD-11, FLD-31). Not built on this platform yet: the requirement tag as this platform's Tag at its small size with nothing of the field's set on it (FLD-5); generated tokens with none of the field's values for it and with the system's choice of mark, which the field's own token follows (FLD-6); the first mark named tag.	TanreiField(labelText: 'Volume', helperText: …, errorText: …, isError: …, required: …, optional: …, child: TanreiSlider(…)), the glyph given by name through labelIcon. enabled is the inverse flag. The names follow InputDecoration, as the text field's do. The field wraps its child in a Semantics(label:, hint:, enabled:) node and an inherited TanreiFieldScope that Tanrei controls and the product's own read. The product's words are read from the TanreiWords inherited widget, which the app fills from its own localizations. Not built on this platform yet: errorText takes the helper's place, as InputDecoration's does, under comp.field.error-text.placement replace, and is drawn below helperText, which stays, comp.field.error-text.gap away, under append (FLD-7); the Semantics hint is what the row draws, then the optional text (FLD-11, FLD-31). Not built on this platform yet: the requirement tag as this platform's Tag at its small size with nothing of the field's set on it (FLD-5); generated tokens with none of the field's values for it and with the system's choice of mark, which the field's own token follows (FLD-6); the first mark named tag.	<Field label="Volume" supportingText="…"><Slider … /></Field>; the glyph is the labelIcon prop (a glyph name). The one child receives the name, the description and the states through FieldContext (Tanrei controls read it; a control the product built calls useField()), and on Android the label is also tied with accessibilityLabelledBy. Follows the app's direction where an ancestor's is not known. The product's words are read from the TanreiWordsProvider context. Not built on this platform yet: the supporting row is a column of the help and, in error, the error text — in the help's place, or comp.field.error-text.gap below it, as comp.field.error-text.placement names (FLD-7); the description given through FieldContext is what the row draws, then the optional text (FLD-11, FLD-31). Not built on this platform yet: the requirement tag as this platform's Tag at its small size with nothing of the field's set on it (FLD-5); generated tokens with none of the field's values for it and with the system's choice of mark, which the field's own token follows (FLD-6); the first mark named tag.

令牌

令牌	引用	解析值（浅色）
--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	#4b4b4b
--tanrei-comp-field-standard-disabled-counter-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-text-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-counter-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-label-icon-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-label-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-required-asterisk-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-supporting-text-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-value-text-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-label-icon-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-label-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-required-asterisk-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-supporting-text-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-value-text-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-error-text-color	sys.color.error	#cd262f
--tanrei-comp-field-standard-error-counter-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-standard-error-label-icon-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-standard-error-label-color	sys.color.on-surface	#1b1b1b
--tanrei-comp-field-standard-error-required-asterisk-color	sys.color.primary	#1b1b1b
--tanrei-comp-field-standard-error-supporting-text-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-standard-error-value-text-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-standard-focused-counter-color	—	#4b4b4b
--tanrei-comp-field-standard-focused-error-text-color	—	#cd262f
--tanrei-comp-field-standard-focused-error-counter-color	—	#4b4b4b
--tanrei-comp-field-standard-focused-error-label-icon-color	—	#4b4b4b
--tanrei-comp-field-standard-focused-error-label-color	—	#1b1b1b
--tanrei-comp-field-standard-focused-error-required-asterisk-color	—	#1b1b1b
--tanrei-comp-field-standard-focused-error-supporting-text-color	—	#4b4b4b
--tanrei-comp-field-standard-focused-error-value-text-color	—	#4b4b4b
--tanrei-comp-field-standard-focused-label-icon-color	—	#4b4b4b
--tanrei-comp-field-standard-focused-label-color	—	#1b1b1b
--tanrei-comp-field-standard-focused-required-asterisk-color	—	#1b1b1b
--tanrei-comp-field-standard-focused-supporting-text-color	—	#4b4b4b
--tanrei-comp-field-standard-focused-value-text-color	—	#4b4b4b
--tanrei-comp-field-standard-label-icon-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-standard-label-color	sys.color.on-surface	#1b1b1b
--tanrei-comp-field-standard-required-asterisk-color	sys.color.primary	#1b1b1b
--tanrei-comp-field-standard-supporting-text-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-standard-value-text-color	sys.color.on-surface-variant	#4b4b4b
--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 为每个样例截取快照，以便相互比较。

slider

label: Volume items: 1

slider-supporting

label: Volume supportingText: Applies to alerts and media. valueText: 40 items: 1

slider-required

label: Volume required: true requiredText: Required valueText: 40 items: 1

slider-optional

label: Volume optional: true optionalText: Optional valueText: 40 items: 1

slider-required-asterisk

label: Volume required: true requiredMark: asterisk valueText: 40 items: 1

slider-error

label: Volume supportingText: Applies to alerts and media. errorText: Choose a level above 0. error: true valueText: 0 items: 1

slider-required-error

label: Volume errorText: Choose a level above 0. error: true required: true requiredText: Required valueText: 0 items: 1

slider-error-without-text

label: Volume supportingText: Applies to alerts and media. error: true valueText: 0 items: 1

slider-disabled

label: Volume supportingText: Applies to alerts and media. disabled: true valueText: 40 items: 1

slider-required-disabled

label: Volume disabled: true required: true requiredText: Required items: 1

slider-label-hidden

label: Volume labelHidden: true supportingText: Applies to alerts and media. items: 1

slider-label-icon

label: Volume valueText: 40 items: 1 slots: label-icon

slider-required-label-icon

label: Volume required: true requiredText: Required items: 1 slots: label-icon

switch

label: Notifications supportingText: Sent when a review is waiting for you. items: 1

switch-optional

label: Notifications optional: true optionalText: Optional items: 1

checkbox-own-label

supportingText: You can withdraw at any time. items: 1

checkbox-own-label-error

supportingText: You can withdraw at any time. errorText: Accept the terms to continue. error: true items: 1

long-label

label: How loud alerts, calls and media are pla… supportingText: A level the connected device cannot play… required: true requiredText: Required valueText: 40 items: 1

slider-required-ja

label: 音量 supportingText: 通知とメディアに適用されます。 required: true requiredText: 必須 valueText: 40 items: 1

slider-optional-ja

label: 音量 optional: true optionalText: 任意 items: 1

slider-error-ja

label: 音量 errorText: 0 より大きい値を選んでください。 error: true required: true requiredText: 必須 valueText: 0 items: 1

slider-rtl

label: مستوى الصوت supportingText: ينطبق على التنبيهات والوسائط. required: true requiredText: مطلوب valueText: 40 direction: rtl items: 1 slots: label-icon

slider-error-rtl

label: עוצמת קול errorText: יש לבחור רמה מעל 0. error: true optional: true optionalText: רשות valueText: 0 direction: rtl items: 1

ltr-label-rtl

label: Bluetooth 5.3 supportingText: LE Audio, 2 Mbps direction: rtl items: 1

code-supporting

label: Verification code supportingText: Enter the 6-digit code we sent to your p… items: 1

code-error

label: Verification code supportingText: Enter the 6-digit code we sent to your p… errorText: That code is not right. Check the messag… error: true items: 1

code-disabled

label: Verification code supportingText: Enter the 6-digit code we sent to your p… disabled: true items: 1

code-required-rtl

label: رمز التحقق supportingText: أدخل الرمز المكوّن من 6 أرقام الذي أرسلن… required: true requiredText: مطلوب direction: rtl items: 1

file-upload-required-error

label: Attachment errorText: Choose a PDF of 10 MB or less. error: true required: true requiredText: Required items: 1

file-picker-required-error

label: Attachment errorText: Choose a PDF of 10 MB or less. error: true required: true requiredText: Required items: 1

text-outlined-empty

label: Email items: 1

text-outlined-filled

label: Email items: 1

text-filled-empty

label: Email items: 1

text-filled-filled

label: Email items: 1

text-outlined-large

label: Email items: 1

text-filled-large

label: Email items: 1

text-outlined-label-hidden

label: Search labelHidden: true items: 1

text-outlined-supporting

label: Email supportingText: We only use it to sign you in. items: 1

text-outlined-error

label: Email errorText: Enter a complete email address. error: true items: 1

text-outlined-supporting-error

label: Email supportingText: We never share your address. errorText: Enter a complete email address. error: true items: 1

text-filled-error

label: Email errorText: Enter a complete email address. error: true items: 1

text-outlined-disabled

label: Email disabled: true items: 1

text-filled-disabled

label: Email disabled: true items: 1

text-outlined-read-only

label: Email items: 1

text-outlined-icons

label: Search items: 1

text-outlined-affixes

label: Amount items: 1

text-outlined-counter

label: Display name countText: 12/40 items: 1

text-outlined-multiline

label: Message items: 1

text-filled-multiline

label: Message items: 1

text-outlined-password

label: Password items: 1

text-stacked-empty

label: Email items: 1

text-stacked-filled

label: Email items: 1

text-stacked-placeholder

label: Email items: 1

text-stacked-large

label: Email items: 1

text-stacked-small

label: Search items: 1

text-stacked-label-hidden

label: Search labelHidden: true items: 1

text-stacked-supporting

label: Email supportingText: We never share your address. items: 1

text-stacked-error

label: Email errorText: Enter a complete address. error: true items: 1

text-stacked-supporting-error

label: Password supportingText: At least 8 characters, with one number. errorText: This password is too short. error: true items: 1

text-stacked-supporting-error-long

label: Billing address supportingText: Use the address your bank has on file, w… errorText: We could not find this address. Check th… error: true items: 1

text-stacked-supporting-error-rtl

label: סיסמה supportingText: לפחות 8 תווים, כולל ספרה אחת. errorText: הסיסמה קצרה מדי. error: true direction: rtl items: 1

text-stacked-disabled

label: Email disabled: true items: 1

text-stacked-read-only

label: Email items: 1

text-stacked-icons

label: Search items: 1

text-stacked-label-icon

label: Display name items: 1 slots: label-icon

text-stacked-affixes

label: Amount items: 1

text-stacked-counter

label: Display name countText: 12/40 items: 1

text-stacked-supporting-error-counter

label: Display name supportingText: Shown beside your posts. errorText: This name is taken. Choose another. error: true countText: 3/40 items: 1

text-stacked-multiline

label: Message items: 1

text-stacked-password

label: Password items: 1

text-stacked-date

label: Start date items: 1

text-stacked-date-empty

label: Start date items: 1

text-stacked-date-picker

label: Start date items: 1

text-stacked-date-picker-large

label: Start date items: 1

text-stacked-date-ja

label: 開始日 items: 1

text-stacked-time-picker

label: Start time items: 1

text-stacked-date-time-picker

label: Starts items: 1

text-stacked-date-error

label: Start date errorText: Choose a date after today. error: true items: 1

text-stacked-date-disabled

label: Start date disabled: true items: 1

text-outlined-date-picker

label: Start date items: 1

text-stacked-multiline-auto-grown

label: Message items: 1

text-stacked-multiline-auto-grown-icons

label: Message items: 1

text-stacked-multiline-auto-max

label: Message items: 1

text-stacked-multiline-manual

label: Message items: 1

text-stacked-multiline-manual-both

label: Message items: 1

text-stacked-multiline-manual-rtl

label: הודעה direction: rtl items: 1

text-stacked-multiline-fixed

label: Message items: 1

text-outlined-multiline-manual

label: Message items: 1

text-stacked-time-empty

label: Start time items: 1

text-stacked-time-24h

label: 開始時刻 items: 1

text-stacked-date-rtl

label: תאריך התחלה direction: rtl items: 1

text-stacked-required

label: Email required: true requiredText: Required items: 1

text-stacked-optional

label: Company optional: true optionalText: Optional items: 1

text-stacked-required-asterisk

label: Email required: true requiredMark: asterisk items: 1

text-stacked-required-ja

label: 氏名 required: true requiredText: 必須 items: 1

text-stacked-optional-ja

label: 会社名 optional: true optionalText: 任意 items: 1

text-stacked-required-label-icon

label: Display name required: true requiredText: Required items: 1 slots: label-icon

text-stacked-required-error

label: Email errorText: Enter your email address. error: true required: true requiredText: Required items: 1

text-stacked-required-disabled

label: Email disabled: true required: true requiredText: Required items: 1

text-stacked-required-rtl

label: אימייל required: true requiredText: חובה direction: rtl items: 1

text-outlined-required

label: Email required: true requiredText: Required items: 1

text-outlined-optional

label: Company optional: true optionalText: Optional items: 1

text-stacked-code

label: Pattern items: 1

text-stacked-code-empty

label: Pattern items: 1

text-stacked-code-large

label: Pattern items: 1

text-stacked-code-affixes

label: Pattern supportingText: A regular expression, matched against a… items: 1

text-stacked-code-multiline

label: Layer items: 1

text-stacked-code-multiline-empty

label: Layer items: 1

text-stacked-code-multiline-wrap

label: Rule items: 1

text-stacked-code-multiline-nowrap

label: Rule items: 1

text-stacked-code-multiline-tabs

label: Recipe items: 1

text-stacked-code-multiline-error

label: Layer errorText: Line 3: a name was expected before }. error: true items: 1

text-stacked-code-multiline-counter

label: Layer countText: 41/200 items: 1

text-stacked-code-multiline-manual

label: Rule items: 1

text-stacked-code-multiline-read-only

label: Rule items: 1

text-stacked-code-multiline-disabled

label: Layer disabled: true items: 1

text-outlined-code-multiline

label: Layer items: 1

text-filled-code-multiline

label: Layer items: 1

text-stacked-code-rtl

label: النمط supportingText: معرّف رمز، مع * لأي جزء. direction: rtl items: 1

text-stacked-code-empty-rtl

label: النمط direction: rtl items: 1

text-stacked-code-affixes-rtl

label: النمط direction: rtl items: 1

text-stacked-code-multiline-rtl

label: الطبقة supportingText: الصق ملف الطبقة هنا. required: true requiredText: مطلوب countText: 41/200 direction: rtl items: 1

text-stacked-code-multiline-empty-rtl

label: الطبقة direction: rtl items: 1

text-stacked-code-multiline-brace-rtl

label: الطبقة direction: rtl items: 1

text-stacked-code-multiline-arabic-first-rtl

label: المصادر direction: rtl items: 1

text-stacked-code-multiline-nowrap-rtl

label: القاعدة errorText: السطر 2: القاعدة ينقصها سبب. error: true direction: rtl items: 1

text-stacked-code-multiline-manual-rtl

label: الطبقة direction: rtl items: 1

slider-value-text

label: Volume valueText: 40 items: 1

slider-value-words

label: Text size valueText: 120 % items: 1

slider-value-indicator

label: Volume valueText: 40 items: 1

slider-range

label: Price valueText: 20 – 60 items: 1

slider-range-words

label: Price supportingText: Per night, before taxes. valueText: $100 – $300 items: 1

slider-long-value-text

label: Yearly income before tax valueText: 3,400,000 – 12,500,000 items: 1

slider-range-rtl

label: السعر valueText: $100 – $300 direction: rtl items: 1

number-stacked-empty

label: Quantity items: 1

number-stacked-value

label: Quantity items: 1

number-stacked-placeholder

label: Quantity items: 1

number-stacked-large

label: Quantity items: 1

number-stacked-label-hidden

label: Quantity labelHidden: true items: 1

number-stacked-supporting

label: Quantity supportingText: Up to 99 per order. items: 1

number-stacked-error

label: Quantity supportingText: Up to 99 per order. errorText: Order at least 1. error: true items: 1

number-stacked-disabled

label: Quantity disabled: true items: 1

number-stacked-read-only

label: Quantity items: 1

number-stacked-at-min

label: Quantity items: 1

number-stacked-at-max

label: Quantity items: 1

number-stacked-no-steppers

label: Quantity items: 1

number-stacked-unit

label: Corner radius items: 1

number-stacked-percent

label: Opacity items: 1

number-stacked-prefix

label: Amount items: 1

number-stacked-negative-decimal

label: Letter spacing items: 1

number-stacked-align-end

label: Tone items: 1

number-stacked-long-number

label: Population items: 1

number-stacked-label-icon

label: Duration items: 1 slots: label-icon

number-stacked-required

label: Quantity required: true requiredText: Required items: 1

number-stacked-optional

label: Quantity optional: true optionalText: Optional items: 1

number-stacked-required-asterisk

label: Quantity required: true requiredMark: asterisk items: 1

number-stacked-required-error

label: Quantity errorText: Enter how many you need. error: true required: true requiredText: Required items: 1

number-stacked-required-disabled

label: Quantity disabled: true required: true requiredText: Required items: 1

number-stacked-required-label-icon

label: Duration required: true requiredText: Required items: 1 slots: label-icon

number-stacked-required-ja

label: 数量 required: true requiredText: 必須 items: 1

number-stacked-optional-ja

label: 数量 supportingText: 1 回の注文で 99 個まで。 optional: true optionalText: 任意 items: 1

number-stacked-locale-de

label: Gewicht items: 1

number-stacked-locale-ar

label: الكمية direction: rtl items: 1

number-stacked-required-rtl

label: الكمية supportingText: حتى 99 لكل طلب. required: true requiredText: مطلوب direction: rtl items: 1 slots: label-icon

number-stacked-unit-rtl

label: רוחב direction: rtl items: 1

number-stacked-error-rtl

label: כמות errorText: יש להזמין לפחות 1. error: true optional: true optionalText: רשות direction: rtl items: 1

number-long-label

label: How many copies of the printed annual re… supportingText: Each copy is 180 pages; orders of more t… required: true requiredText: Required items: 1

number-beside-slider

label: Scale labelHidden: true items: 1

number-filled-empty

label: Quantity items: 1

number-filled-value

label: Quantity items: 1

number-filled-large

label: Quantity items: 1

number-filled-error

label: Quantity errorText: Order at least 1. error: true items: 1

number-filled-disabled

label: Quantity disabled: true items: 1

number-filled-unit

label: Corner radius items: 1

number-outlined-empty

label: Quantity items: 1

number-outlined-value

label: Quantity items: 1

number-outlined-large

label: Quantity items: 1

number-outlined-error

label: Quantity errorText: Order at least 1. error: true items: 1

number-outlined-disabled

label: Quantity disabled: true items: 1

number-outlined-required

label: Quantity required: true requiredText: Required items: 1

color-stacked-empty

label: Brand color items: 1

color-stacked-filled

label: Brand color items: 1

color-stacked-large

label: Brand color items: 1

color-stacked-label-hidden

label: Brand color labelHidden: true items: 1

color-stacked-supporting

label: Brand color supportingText: Six hexadecimal digits, like #0f766e. items: 1

color-stacked-white

label: Page background items: 1

color-stacked-black

label: Text items: 1

color-stacked-picker

label: Brand color items: 1

color-stacked-picker-empty

label: Brand color items: 1

color-stacked-picker-large

label: Brand color items: 1

color-stacked-error

label: Brand color errorText: Too light for white text. Choose a darke… error: true items: 1

color-stacked-error-picker

label: Brand color errorText: Too light for white text. Choose a darke… error: true items: 1

color-stacked-disabled

label: Brand color disabled: true items: 1

color-stacked-picker-disabled

label: Brand color disabled: true items: 1

color-stacked-label-icon

label: Brand color items: 1 slots: label-icon

color-stacked-required

label: Brand color required: true requiredText: Required items: 1

color-stacked-optional

label: Accent color optional: true optionalText: Optional items: 1

color-stacked-required-asterisk

label: Brand color required: true requiredMark: asterisk items: 1

color-stacked-required-label-icon

label: Brand color required: true requiredText: Required items: 1 slots: label-icon

color-stacked-required-error

label: Brand color errorText: Choose a brand color. error: true required: true requiredText: Required items: 1

color-stacked-required-disabled

label: Brand color disabled: true required: true requiredText: Required items: 1

color-stacked-required-ja

label: ブランドカラー required: true requiredText: 必須 items: 1

color-stacked-optional-ja

label: アクセントカラー supportingText: # と 6 桁の 16 進数で入力します。 optional: true optionalText: 任意 items: 1

color-stacked-required-rtl

label: لون العلامة required: true requiredText: مطلوب direction: rtl items: 1

color-stacked-error-rtl

label: צבע המותג errorText: בהיר מדי לטקסט לבן. בחרו צבע כהה יותר. error: true direction: rtl items: 1 slots: label-icon

color-ltr-label-rtl

label: Brand color (HEX) supportingText: sRGB, 6 digits direction: rtl items: 1

color-long-label

label: The color of the primary buttons, the li… supportingText: Six hexadecimal digits after a number si… required: true requiredText: Required items: 1

color-filled-empty

label: Brand color items: 1

color-filled-filled

label: Brand color items: 1

color-filled-picker

label: Brand color items: 1

color-filled-error

label: Brand color errorText: Too light for white text. Choose a darke… error: true items: 1

color-filled-disabled

label: Brand color disabled: true items: 1

color-outlined-empty

label: Brand color items: 1

color-outlined-filled

label: Brand color items: 1

color-outlined-large

label: Brand color items: 1

color-outlined-picker

label: Brand color items: 1

color-outlined-error

label: Brand color errorText: Too light for white text. Choose a darke… error: true items: 1

color-outlined-disabled

label: Brand color disabled: true items: 1

color-outlined-required

label: Brand color required: true requiredText: Required items: 1

select-stacked-empty

label: Country items: 1

select-stacked-value

label: Country items: 1

select-stacked-open

label: Country items: 1

select-stacked-large

label: Country items: 1

select-stacked-small

label: Country items: 1

select-stacked-error

label: Country errorText: Choose a country. error: true items: 1

select-stacked-disabled

label: Country disabled: true items: 1

select-filled-empty

label: Country items: 1

select-filled-value

label: Country items: 1

select-filled-open

label: Country items: 1

select-filled-large

label: Country items: 1

select-filled-small

label: Country items: 1

select-filled-error

label: Country errorText: Choose a country. error: true items: 1

select-filled-disabled

label: Country disabled: true items: 1

select-outlined-empty

label: Country items: 1

select-outlined-value

label: Country items: 1

select-outlined-open

label: Country items: 1

select-outlined-large

label: Country items: 1

select-outlined-small

label: Country items: 1

select-outlined-error

label: Country errorText: Choose a country. error: true items: 1

select-outlined-disabled

label: Country disabled: true items: 1

select-stacked-placeholder

label: Country items: 1

select-stacked-open-none-chosen

label: Country items: 1

select-stacked-label-hidden

label: Country labelHidden: true items: 1

select-stacked-supporting

label: Country supportingText: Where your invoices are addressed. items: 1

select-stacked-error-value

label: Country errorText: We cannot ship there yet. error: true items: 1

select-stacked-read-only

label: Country items: 1

select-stacked-required

label: Country required: true requiredText: Required items: 1

select-stacked-optional

label: Country optional: true optionalText: Optional items: 1

select-stacked-required-asterisk

label: Country required: true requiredMark: asterisk items: 1

select-stacked-required-disabled

label: Country disabled: true required: true requiredText: Required items: 1

select-stacked-required-error

label: Country errorText: Choose a country. error: true required: true requiredText: Required items: 1

select-stacked-required-ja

label: 国 required: true requiredText: 必須 items: 1

select-stacked-optional-ja

label: 国 optional: true optionalText: 任意 items: 1

select-outlined-required

label: Country required: true requiredText: Required items: 1

select-stacked-label-icon

label: Time zone items: 1 slots: label-icon

select-stacked-option-icon

label: Theme items: 1

select-stacked-leading-icon

label: Language items: 1

select-open-icons

label: Theme items: 1

select-open-supporting-text

label: Plan items: 1

select-open-disabled-chosen

label: Plan items: 1

select-open-groups

label: Time zone items: 1

select-open-groups-divider

label: Time zone items: 1

select-open-groups-gap

label: Time zone items: 1

select-open-many

label: Token items: 1

select-open-long-options

label: Email me items: 1

select-long-value

label: Email me items: 1

select-empty-value-option

label: Contrast items: 1

select-small-label-hidden

label: Contrast labelHidden: true items: 1

select-small-label-hidden-icons

label: Theme labelHidden: true items: 1

select-small-label-hidden-leading-icon

label: Language labelHidden: true items: 1

select-small-label-hidden-open

label: Theme labelHidden: true items: 1

select-small-open

label: Country items: 1

select-stacked-required-rtl

label: المنطقة الزمنية supportingText: تُعرض المواعيد بهذا التوقيت. required: true requiredText: مطلوب direction: rtl items: 1 slots: label-icon

select-open-rtl

label: المنطقة الزمنية direction: rtl items: 1

select-long-value-rtl

label: Email me direction: rtl items: 1

select-outlined-rtl

label: المنطقة الزمنية direction: rtl items: 1

combobox-stacked-empty

label: City items: 1

combobox-stacked-value

label: City items: 1

combobox-stacked-open

label: City items: 1

combobox-stacked-large

label: City items: 1

combobox-stacked-error

label: City errorText: Choose the city you are sending to. error: true items: 1

combobox-stacked-disabled

label: City disabled: true items: 1

combobox-stacked-placeholder

label: City items: 1

combobox-stacked-label-hidden

label: City labelHidden: true items: 1

combobox-stacked-supporting

label: City supportingText: Where the order is sent. items: 1

combobox-stacked-error-value

label: City supportingText: Where the order is sent. errorText: We do not deliver to Nairobi yet. error: true items: 1

combobox-stacked-read-only

label: City items: 1

combobox-stacked-clearable

label: City items: 1

combobox-stacked-no-chevron

label: Address items: 1

combobox-stacked-custom-value

label: Font family items: 1

combobox-stacked-required

label: City required: true requiredText: Required items: 1

combobox-stacked-optional

label: City optional: true optionalText: Optional items: 1

combobox-stacked-required-asterisk

label: City required: true requiredMark: asterisk items: 1

combobox-stacked-required-error

label: City errorText: Choose the city you are sending to. error: true required: true requiredText: Required items: 1

combobox-stacked-required-disabled

label: City disabled: true required: true requiredText: Required items: 1

combobox-stacked-label-icon

label: City items: 1 slots: label-icon

combobox-stacked-leading-icon

label: Assignee items: 1

combobox-stacked-option-icon

label: Transport items: 1

combobox-open-none-chosen

label: City items: 1

combobox-open-filtered

label: City items: 1

combobox-open-filtered-none

label: City items: 1

combobox-open-icons

label: Transport items: 1

combobox-open-supporting-text

label: Token items: 1

combobox-open-disabled-chosen

label: Token items: 1

combobox-open-groups

label: Time zone items: 1

combobox-open-groups-divider

label: Time zone items: 1

combobox-open-groups-gap

label: Time zone items: 1

combobox-open-groups-filtered

label: Time zone items: 1

combobox-open-many

label: City items: 1

combobox-open-long-options

label: Licence items: 1

combobox-open-custom-suggestions

label: Font family items: 1

combobox-open-loading

label: Assignee items: 1

combobox-open-status

label: Assignee items: 1

combobox-open-status-error

label: Assignee items: 1

combobox-long-value

label: Licence items: 1

combobox-long-label

label: Which of the cities we deliver to is nea… supportingText: If none of them is near enough, leave th… required: true requiredText: Required items: 1

combobox-stacked-required-ja

label: 都市 required: true requiredText: 必須 items: 1

combobox-open-filtered-ja

label: 都市 optional: true optionalText: 任意 items: 1

combobox-stacked-required-rtl

label: المدينة supportingText: إلى أين نرسل الطلب. required: true requiredText: مطلوب direction: rtl items: 1 slots: label-icon

combobox-open-rtl

label: المنطقة الزمنية direction: rtl items: 1

combobox-long-value-rtl

label: רישיון direction: rtl items: 1

combobox-stacked-error-rtl

label: עיר errorText: יש לבחור עיר מהרשימה. error: true optional: true optionalText: רשות direction: rtl items: 1

combobox-filled-empty

label: City items: 1

combobox-filled-value

label: City items: 1

combobox-filled-open

label: City items: 1

combobox-filled-large

label: City items: 1

combobox-filled-error

label: City errorText: Choose the city you are sending to. error: true items: 1

combobox-filled-disabled

label: City disabled: true items: 1

combobox-outlined-empty

label: City items: 1

combobox-outlined-value

label: City items: 1

combobox-outlined-open

label: City items: 1

combobox-outlined-large

label: City items: 1

combobox-outlined-error

label: City errorText: Choose the city you are sending to. error: true items: 1

combobox-outlined-disabled

label: City disabled: true items: 1

combobox-outlined-required

label: City required: true requiredText: Required items: 1

combobox-outlined-rtl

label: المدينة direction: rtl items: 1

entries-email-empty

label: Recipients supportingText: Separate addresses with a comma. items: 1

entries-email-entries

label: Recipients items: 1

entries-email-typing

label: Recipients supportingText: Separate addresses with a comma. items: 1

entries-email-refused

label: Recipients supportingText: Separate addresses with a comma. errorText: Enter a full address, such as name@examp… error: true items: 1

entries-email-error

label: Recipients errorText: [email protected] could not be re… error: true items: 1

entries-email-required

label: Recipients required: true requiredText: Required items: 1

entries-email-required-empty-error

label: Recipients errorText: Add at least one address. error: true required: true requiredText: Required items: 1

entries-email-optional

label: Cc optional: true optionalText: Optional items: 1

entries-email-limit

label: Recipients supportingText: Up to 3 addresses. items: 1

entries-email-many

label: Recipients items: 1

entries-email-many-typing

label: Recipients items: 1

entries-email-long-entry

label: Recipients items: 1

entries-email-large

label: Recipients items: 1

entries-email-filled

label: Recipients items: 1

entries-email-filled-empty

label: Recipients items: 1

entries-email-outlined

label: Recipients items: 1

entries-email-disabled

label: Recipients supportingText: Separate addresses with a comma. disabled: true items: 1

entries-email-disabled-empty

label: Recipients disabled: true items: 1

entries-email-read-only

label: Recipients items: 1

entries-email-label-hidden

label: Recipients labelHidden: true items: 1

entries-email-label-icon

label: Recipients items: 1 slots: label-icon

entries-keywords

label: Keywords supportingText: Press Enter or type a comma after each k… items: 1

entries-keywords-enter-only

label: Authors supportingText: Press Enter after each name. items: 1

entries-telephone

label: Numbers to notify items: 1

entries-keywords-ja

label: キーワード supportingText: キーワードごとに Enter を押してください。 required: true requiredText: 必須 items: 1

entries-keywords-rtl

label: الكلمات المفتاحية supportingText: اضغط Enter بعد كل كلمة. direction: rtl items: 1

entries-email-rtl

label: נמענים errorText: יש להזין כתובת מלאה, למשל [email protected]… error: true direction: rtl items: 1

chat-composer-supporting

label: Message supportingText: Everyone in this channel can read it. items: 1

number-stacked-unit-own-script-rtl

label: الوزن direction: rtl items: 1

number-stacked-prefix-rtl

label: المبلغ direction: rtl items: 1

number-stacked-percent-rtl

label: العتامة direction: rtl items: 1

number-stacked-align-end-unit-rtl

label: גודל direction: rtl items: 1

生成自 specs/field.spec.json, tokens/comp/field.tokens.json, design/tokens/

指南

link

用字段，还是用本身就是字段的控件

link

控件	使用
没有自己的标签、帮助文本和错误：滑块、开关、你自己构建的控件	在它外面套一个字段——滑块也可以用把两者合为一个组件的字段：滑块字段。
是供用户键入的、单独使用的控件：文本输入框、颜色输入框、一次性验证码输入框	在它外面套一个字段——或者用把两者合为一个组件的字段：文本字段、颜色字段、一次性验证码字段。
是单独使用的下拉选择框	在它外面套一个字段——或者用把两者合为一个组件的下拉选择字段。
已经是一个字段：文本字段、一次性验证码字段、滑块字段、下拉选择字段，以及任何自带 supportingText 的控件	只用控件本身。绝不要把它放进字段。
用旁边的标签为自己命名：复选框、自带标签的开关	需要帮助文本或错误时，用一个 label 为空的字段。
是回答同一个问题的一组控件	字段组。

经验法则：如果控件有 supportingText 属性，它就不需要字段。

必填和选填

link

required 和 optional 说明表单对控件的要求。required 是 HTML 给它的名字，它把控件暴露为必填，并画出必填标记：<tanrei-field label="邮箱" required>。optional 画出选填小标签。一个控件不可能既必填又选填：两者都设置时它是必填的，开发构建会报告 optional 被忽略。在 React 中，它们和 <input> 上的 required 一样是 prop。

• required 把控件暴露为必填，并在标签旁边绘制必填标记。
• optional 绘制一个低调的小标签，并把它的文字加入控件的描述。
• 两者都不做校验。缺少回答要由你用 error 和 errorText 来报告。

必填的控件如何标记，是设计系统为每个字段和每一组控件做的一项选择：令牌 sys.behavior.requirement-mark，它的取值是 tag（一个写着“必填”的实色填充小标签）、asterisk 和 none。默认系统用小标签来标记。设计系统只要设置这一个令牌，就能一次改变所有表单。字段通过自己的令牌 comp.field.requirement.mark 读取它，这个令牌跟随它；只有要让单个字段的标记方式不同于成组的控件时，设计系统才设置这个令牌。requiredMark 可以为单个字段覆盖这两者（tag、asterisk 或 none）。

必填和选填小标签就是一个小号的 Tag，必填用 filled，选填用 tonal，仅此而已：字段没有为它准备的令牌。重新设定小号 Tag 样式的设计系统，也就同时重新设定了必填和选填小标签的样式。字段聚焦或处于错误状态时，它看起来都一样；字段禁用时，它按“位于禁用元素之中的 Tag”来绘制，随它所跟随的标签一起变淡。小标签上的文字是你的：把 requiredText 和 optionalText 写在字段上，或者用 setWords() 为整个产品只给一次。Tanrei 不自带任何文字：没有 requiredText 时，小标签的位置上是一个星号；没有 optionalText 时，不绘制小标签。

标记两者中较少的那一种。在几乎每一项都必须填写的表单里，标记选填的；在必须填写的很少的表单里，标记必填的。

帮助文本和错误

link

• supportingText 说明该怎么填：格式、范围，或者这个值的用途。
• errorText 用文字说明这次回答哪里错了、怎样改正。error 为 true 时，它取代帮助文本的位置，所以帮助文本里仍然重要的内容要再说一遍：写“请输入今天之后的日期”，而不是“日期无效”。
• 错误文本放在哪里，是设计系统的一项选择：comp.field.error-text.placement。默认的 replace 把它放在帮助文本的位置：只读一行，处于错误状态的字段也不会比平时更高。append 保留帮助文本，把错误文本加在它下方一小段间隙（comp.field.error-text.gap）之外：这时字段处于错误状态时会更高，错误文本上方的东西都不会动。所有随附的系统都使用 replace，Material 和 Carbon 也是如此；append 适用于像 GOV.UK 那样让帮助文本始终可见的设计系统。
• 在错误出现之前不为它预留空间。没有帮助文本的字段，在帮助文本本该在的位置显示错误文本。
• 错误文本出现或消失时，计数始终留在第一行的末尾。
• 在完成校验之后才设置 error，不要在用户还在填写时设置。字段自己绝不会设置它。

一个控件

link

一个字段只框住一个控件，也就是它默认插槽里的那一个元素。有多个时，它只为第一个命名并提供描述，并在调试构建中报告这一点：一组控件应该用字段组。

要禁用字段里的控件，请在字段上禁用，而不是在控件上禁用，这样标签和帮助文本才会随之变化。

推荐

link

• 用几个词写出标签，说明要填的是什么，并让它保持可见。只有当同一个控件在别处已有可见的标签时（例如表格的列标题），才使用 labelHidden。
• 同一列里的字段保持相同的宽度，让标签和控件各自对齐。

避免

link

• 不要把文本字段，或任何自己绘制标签和帮助文本的控件，放进字段。那样会出现两个标签，调试构建也会报告这一点。字段框住的是不带任何附加功能的那个控件：文本输入框。
• 不要用标签来写操作说明。那是辅助文本的用途。
• 不要只靠错误的颜色。请把错误写出来。

无障碍

link

角色

none

标注

The field has no role of its own: it is a frame, and assistive technology meets the control. label is the control's accessible name, drawn or not (labelHidden), unless the control names itself. The control's description is what the supporting row draws — the help (supportingText) and, while the field is in error, the error text in its place or after it (FLD-11) — then optionalText while optional is true. The control is exposed as invalid while error is true, as required while required is true — whichever mark is drawn, and the mark itself is hidden — and as disabled while disabled is true. The label glyph is decorative.

最小目标

即使外观尺寸更小，点击区域也满足最小目标尺寸。 minimum 32px · pointer 44px · spacing 8px · touch 48px

键盘操作

按键	动作

备注

• Not interactive by itself: the field takes no focus and adds no key (FLD-12), so it has no target of its own to size and minimumTarget holds through its control, whose own spec sizes its hit area. A press on the label moves focus to the control and never operates it; the label therefore widens where a pointer can land without widening what a press does.
• There is one frame: a composed field — a text field — is this Field around its one control and draws no rows of its own. No component draws these rows itself; a composed field placed inside a field is reported (FLD-15).
• Each platform carries the name, the description and the three states to the control in its own way, and a control the product built receives them the same way a Tanrei control does: on the web as ARIA attributes on the slotted element; in SwiftUI through the environment and the accessibility modifiers of the framed view; in Compose through a composition local and merged semantics; in Flutter through an inherited widget and a Semantics node around the control; in React Native through a context and the accessibility props of the wrapper.
• Errors are words (WCAG 3.3.1, 1.4.1): errorText says what is wrong and how to put it right, the control is exposed as invalid, and the error color is one more sign, never the only one. The error text is announced when it appears under the person's focus and is otherwise read with the control (FLD-9); it never takes focus away.
• After a failed submission a product should also say, above the form, how many answers were refused and link to each: that summary is a live Callout in its error status, not a part of any field. The field does not build it, because only the form knows all of its errors.
• While the field is in error the error text takes the help's place under the default system (comp.field.error-text.placement replace): the one line below the control then says what is wrong, and a form in error is no taller than at rest; errorText should then also say how to put the answer right, because the help is not drawn. A design system that keeps the help in view while the person corrects the answer chooses append: the help stays and the error text is added below it, and a field with a help is taller in error by the error text and its gap. Under both, nothing above the error text moves, and no room is held open before an error exists. A field group keeps its description and gives its error a row of its own (FGR-7, FGR-8).
• An asterisk alone does not explain itself: a product that marks required controls with an asterisk says what it means once, near the top of the form. The tag says it in words.
• Heights are the texts': at 200% text size the label and the supporting row wrap and the field grows; nothing is cut (WCAG 1.4.4, 1.4.10).
• Forced colors (FLD-17): the error and the help then look alike, which is why the error must be in words and in the invalid state.
• How a state looks is a value decision of the active design system; components read the state's tokens and never compute the effect themselves.
• A control can say three things back to its field, each by the same channel the field names it by: that it draws the label itself (FLD-25), where its content starts and ends (FLD-26) and a refusal of an entry (FLD-28). They are what makes a Field around a text input by hand the same picture as a text field; a control that says none of them is framed as before.
• A place for words about the control's value is a prop of the field, named for what it holds: the field draws the words it is given, never reads, counts or formats a value, and keeps the drawn text from assistive technology, because the control says the same itself. countText is the first such place (FLD-27). A composed field fills it from its control (a text field, TXF-67); a product that writes the pair by hand writes it, at each change.
• valueText is a place for words about the control's value (FLD-29, FLD-30): the field draws the words it is given at the end of the label row, never reads or formats a value, and keeps the drawn text from assistive technology, because the control says its own value. A slider field fills it from its slider (SLF-3); a product that writes the pair by hand writes it, at each change.

生成自 specs/field.spec.json, tokens/sys/measure.tokens.json

组件负责的部分

link

• 标签就是控件的无障碍名称，无论它是画出来的，还是用 labelHidden 隐藏的。自己已有名称的控件保留自己的名称。
• 控件的描述就是辅助文本那一行显示的内容——帮助文本；字段处于错误状态时，则是取代它的错误文本（在 append 下，是帮助文本之后再接错误文本）——控件为选填时，再接 optionalText。它们排在控件已有的描述之后。
• error 为 true 时，控件暴露为无效；设置了 required 时，暴露为必填；disabled 为 true 时，暴露为禁用。角色没有必填状态的控件（例如滑块），改为在描述里说出 requiredText。
• 自己有错误状态的控件（例如复选框或单选按钮），会以它的错误状态绘制。
• 焦点位于字段内时出现或改了措辞的错误，会以礼貌（polite）的方式朗读一次：只读错误文本，不再重读帮助文本。焦点绝不会因为错误而移动。
• 按下标签会把焦点移到控件上，但不会操作控件。
• 字段不在焦点顺序中增加停靠点，也不处理任何按键。
• 必填和选填小标签、星号和标签的字形对辅助技术隐藏：它们表达的内容，状态和描述已经说明了。画出来的计数也是如此：控件会描述并朗读自己的计数。
• 文本放大到 200% 时，标签和辅助文本会换行，不会有任何内容被截断。
• 在强制颜色模式下，所有文本都采用系统的文本颜色，必填和选填小标签会多出一道边线。这时错误文本和帮助文本看起来一样，要靠它们的文字和先后顺序来区分：帮助文本在前。所以错误必须用文字写出来。
• 在从右到左的布局中，各行从右侧开始，字形移到标签的右侧，标记移到标签的左侧，每段文本保持自己的方向。

在 Web 上，属性（attribute）用 kebab-case 书写：label-hidden、supporting-text、error-text、required-mark、required-text、optional-text、count-text。部件是 label、label-icon、requirement-label、value-text、supporting-text（帮助文本）、error-text 和 counter。

Web 关联控件的方式：id 无法跨 shadow root 引用，所以字段把自己的文本作为值提供出来。Tanrei 的控件向所在的字段索取这些文本，并写到自己内部的元素上。其他任何元素会收到 aria-label（仅当它没有自己的名称时）、aria-description、aria-invalid、aria-required 和 disabled，并在离开字段时原样恢复它原有的值。

Web 上的已知差距：

• 描述是用 aria-description 提供的，它还没有在每一种屏幕阅读器上验证过；已经有自己的 aria-describedby 的元素，也拿不到字段的文本。
• 在元素定义之前，控件出现在页面上时没有标签和帮助文本。

需要你做的事

link

• 为每个字段提供 label，除非控件自己有名称。
• 自己校验值，设置 error，并编写说明如何改正的 errorText。
• 提交失败之后，还要在表单上方说明有多少项回答被拒绝，并逐一链接过去：使用一个带 live、处于错误语义状态的提示块。字段无法生成它，因为只有表单知道自己的全部错误。
• 给出必填和选填的文字：把 required-text 和 optional-text 写在字段上，或者用 setWords({ requiredText, optionalText }) 为整个产品只给一次。Tanrei 不自带任何文字；缺少的文字会在开发时报告。参见产品的文字。
• 如果你用星号标记必填的控件，请在表单靠近顶部的地方说明一次星号的含义。
• 对于你自己构建的控件，要确保名称和状态落在它的语义所在之处：要么它把角色放在自己的元素上，让字段写入的属性直接生效；要么由它自己监听并接收这些值（见 Web 包的 README 中的“Field”一节）。