颜色字段
让用户把一种颜色作为表单的一个字段来设置——一个可以阅读、键入和粘贴的文本值，文本旁边的颜色样本，以及一个用来唤出选择器的按钮——外观和尺寸与文本字段相同。
- 类别
- 文本输入
- 令牌
comp.field- 层级
- 组合
- 构成自
- Field, Color input
- Web
tanrei-color-fieldschedule - SwiftUI
TanreiColorFieldradio_button_unchecked - Jetpack Compose
TanreiColorFieldradio_button_unchecked - Flutter
TanreiColorFieldradio_button_unchecked - React Native
ColorFieldradio_button_unchecked
- 不提供的变体
- tanrei: filled, outlined
生成自 docs/status/status.json, specs/color-field.spec.json
一个带选择器按钮的颜色字段，以及一个颜色被产品拒绝的颜色字段
在用户把颜色作为一个值来设置的地方使用颜色字段：主题里的品牌色、标签或类别的颜色。用户阅读它、键入它，或者从别的工具里粘贴过来，并在文本旁边看到它的样本。这个字段的绘制方式和尺寸，与相同变体、相同尺寸的文本字段一致。
组成部分是一个字段和一个颜色输入框。字段是框架：标签、必填或选填标记、帮助文本和错误。颜色输入框是控件：方框、色块、以文本形式呈现的值，以及选择器按钮。颜色字段自己什么都不绘制，也没有令牌：它的每个属性都是这两者之一的属性，原样交给它们。
它是一个块，放在哪里就和那里一样宽，它的方框会把它填满。它没有自己的宽度：想要窄一些的字段，就把它放进窄一些的地方。它已经是一个字段，所以绝不放进字段里。
它不绘制自己的选择器。设置 picker 后，末尾的一个按钮会请求一个选择器：浏览器的，或者由产品呈现的一个表面。
在 Web 上它是 <tanrei-color-field>。其他平台尚未实现。
value 是一个井号加六位小写的十六进制数字（#0f766e），或者用空字符串表示没有颜色。它绝不会是键入到一半的文本：输入框里的内容不是颜色时，value 为空。
<form>
<tanrei-color-field name="brand" label="品牌色" value="#0f766e"
required required-text="必填"
supporting-text="六位十六进制数字，例如 #0f766e。"
invalid-text="请输入六位十六进制数字，例如 #0f766e。"
picker picker-label="选择颜色"></tanrei-color-field>
</form>
<script type="module">
import '@tanrei/web/components/color-field';
const brand = document.querySelector('tanrei-color-field');
// 值变了：一种颜色，或者空字符串。读到的已经是新值。
brand.addEventListener('input', () => preview(brand.value));
// 用户确认了一个有变化的值：焦点离开、按下 Enter，或者选择器关闭。
brand.addEventListener('change', () => save(brand.value));
// 确认的文本不是颜色。字段保留这段文本，并显示 invalidText，
// detail.message 带的也是它。
brand.addEventListener('entryerror', (e) => console.log(e.detail.text, e.detail.message));
// 要呈现你自己的选择器：取消这个请求，打开选择器，再把 value 设为选出的颜色。
brand.addEventListener('pickerrequest', (e) => {
e.preventDefault();
openMyPicker(e.detail.value).then((color) => (brand.value = color));
});
</script>import { ColorField } from '@tanrei/react';
<ColorField label="品牌色" value={brand} picker pickerLabel="选择颜色"
invalidText="请输入六位十六进制数字，例如 #0f766e。"
onChange={(event) => setBrand(event.currentTarget.value)} />用它的两个成员手写出来的同一个字段，画面是一样的，对辅助技术来说也是同一个文本框，名称、描述和状态都相同：
<tanrei-field label="品牌色" required required-text="必填"
supporting-text="六位十六进制数字，例如 #0f766e。">
<tanrei-color-input name="brand" value="#0f766e"
invalid-text="请输入六位十六进制数字，例如 #0f766e。"
picker picker-label="选择颜色"></tanrei-color-input>
</tanrei-field>手写出来的同一个字段：里面放着一个颜色输入框的字段
需要颜色字段没有提供的排布方式时，就往下走一层：
| 你需要 | 使用 |
|---|---|
| 标签、方框、帮助文本和错误 | 颜色字段 |
| 在框架里面、方框的旁边或下方放你自己的东西 | 一个字段，里面放一个颜色输入框和你自己的元素 |
| 只要方框，放在已经为颜色命名的行或列里：调色板的各个色调、表格的一个单元格 | 单独的颜色输入框，由它自己的 label 命名 |
到了下一层，变的是各样东西写在哪里。name 和 value 写在颜色输入框上，这时它就是表单遇到的那个控件，它的事件也在它上面监听。label、error、disabled 和必填与否仍然写在字段上，由字段传给控件：不要设置输入框自己的那几个。颜色字段做的事，没有一件是手写的字段和颜色输入框做不到的。
空的颜色字段、白色、黑色、大号的、禁用的——以及只有方框的颜色输入框，放在为它的颜色命名的一行里
| 部件 | 它是什么 |
|---|---|
| 标签 | 位于容器上方（stacked），这时由字段绘制；或者浮在容器里面（filled、outlined），这时由颜色输入框绘制。它就是无障碍名称，无论它是画出来的，还是用 labelHidden 隐藏的 |
| 必填和选填标记 | 位于标签之后：required 时是“必填”小标签、星号，或者什么都不画；optional 时是“选填”小标签 |
| 色块 | 位于容器起始处的值的样本：一个小方块，用的正是值的颜色，外面有一圈细线。为空时，只有这圈细线。它不是控件 |
| 输入框 | 以文本形式呈现的值。只有一行，放不下时滚动 |
| 选择器按钮 | 设置 picker 时：末尾的一个纯图标 text 按钮，由 pickerLabel 命名 |
| 辅助文本 | 一行帮助文本，从色块之后、值的文本开始的位置起笔。字段处于错误状态时，错误文本取代它的位置（设计系统两者都保留时，绘制在它的下方）：error 为 true 时是 errorText；已确认的文本不是颜色时是 invalidText，invalidText 为空时是 errorText |
三种变体，以及 small（32）、medium（40）和 large（56）三种尺寸，都是文本字段的。默认系统只提供 stacked。色块位于文本字段前置图标所在的位置，大小也与那个图标相同，所以放在带前置图标的文本字段下方的颜色字段，起始边与它对齐。
色块里不会混入任何东西：没有悬停，没有错误状态的着色，没有阴影。在指针下会变化的样本是不正确的样本。禁用时，它的填充画得更淡，边线保留。
| 何时 | 发生什么 |
|---|---|
| 用户键入、粘贴或听写 | 什么都不拒绝，什么都不改写。整段文本都会被解读：如果它是颜色，value 就是那种颜色，否则为空。value 有变化时触发 input |
| 焦点离开，或者按下 Enter | 文本被确认。颜色会按值自己的写法改写。值与上一次确认的值不同时触发 change |
| 已确认的文本不是颜色 | 文本保留。字段进入错误状态并显示 invalidText，同时触发 entryerror。下一次编辑时错误结束 |
| 文本为空 | value 为空。这绝不是字段自己的错误 |
产品设置 value |
无论之前键入了什么，都显示这种颜色。不触发任何事件 |
去掉两侧的空格之后，文本恰好是六位十六进制数字时，它就读作颜色——大小写均可，带不带井号都行：0F766E、#0f766e 和 #0F766E 都是 #0f766e。
其余的都不是颜色：三位数字（#0f7）、八位数字（#0f766e80）、名称（teal）、函数写法（rgb(15, 118, 110)）。键入时三位数字还不是颜色，因为键入六位的途中文本会经过三位；文本确认时，三位数字会像 CSS 那样，按每位重复一次读成六位：#0f7 变成 #00ff77。没有 alpha，也没有广色域颜色。
用户还在键入时，什么都不会报告。只有在用户确认时，才会报出输入错误。
设置 picker 后，字段在末尾显示一个按钮。激活它会触发 pickerrequest，事件带有当前的值。
| 产品 | 发生什么 |
|---|---|
| 什么也不做 | 字段呈现浏览器自己的颜色选择器。每一次选取都算用户的一次编辑：文本、色块、input。选择器关闭时触发 change，焦点位于选择器按钮上 |
| 取消这个请求 | 字段什么也不呈现。产品打开自己的表面，锚定在字段上，并把 value 设为选出的颜色。那个表面关闭时把焦点交还给选择器按钮 |
显示选择器按钮时，按色块会像按这个按钮一样打开选择器；焦点不会移到输入框，键盘的操作方式仍是这个按钮。没有这个按钮时，按色块会让输入框获得焦点，与按字段上其他任何地方一样。
- 来自字段：属性
label、labelHidden、supportingText、errorText、error、disabled、required、optional、requiredMark、requiredText和optionalText；插槽label-icon；令牌comp.field.*。 - 来自颜色输入框：属性
variant、size、value、invalidText、picker和pickerLabel；事件input、change、pickerRequest和entryError；令牌方面，方框用comp.input-box.*（每一种输入方框都读取它），色块用comp.color-input.*。
颜色输入框有自己的 label、labelHidden、error 和 disabled。颜色字段设置的不是它们：颜色字段的 label 是字段的 label，它为输入框命名，在 filled 或 outlined 的字段里，浮在方框中的也是它。
颜色字段没有自己的令牌。它的方框读取颜色输入框的令牌，它的各行——标签、标记、帮助文本和错误——读取字段的令牌，无论这些令牌设置在哪里。下面的表格列出的是字段的令牌。要改动某一个实例，就在它上面设置成员的令牌：
<tanrei-color-field label="品牌色"
style="--tanrei-comp-field-label-gap: 12px"></tanrei-color-field>构成
构成
stacked-empty 之上。| 部件 | 说明 |
|---|---|
1 field | The Field: the label row with its glyph and its requirement mark, and the supporting row with the help and the error text. In a look whose input floats the label it draws no label row. |
2 color-input | The color input, as the Field's one control: the box, the swatch, the value as text, the picker button, and the label that floats in the box in the looks that float one. |
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
variant | stacked | filled | outlined | "stacked" | The text input's three looks, so that a color input is drawn as the text inputs beside it. Stacked is a filled box that shows focus and error with a line inside its edge and draws no label: the label of the Field that frames it stands above it. Filled and outlined float the label inside the box. Use one style per form. A design system may leave some out (the Tanrei system ships stacked only) or add values. — Color input |
size | small | medium | large | "medium" | Minimum height of the container: stacked 32 / 40 / 56, as tall as a Button of the same size, so that the box and a Button side by side in one row stand as tall as each other; filled and outlined 40 / 48 / 56, which hold the label that floats inside them. These are the text input's three sizes, small for a bar, a toolbar or a dense row of controls. The hit area always meets the minimum target. A design system may add values. — Color input |
value | string | "" | The color the input holds: a number sign and six hexadecimal digits in lowercase ("#0f766e"), an opaque sRGB color; or empty for no color. It is never a half-typed text: while the input holds something that is not a color, value is empty. — Color input What the color field reports as its own is the value its color input holds, in that value's own form (CLF-43, CLI-16, CLI-21). |
label | string | "" | Names the control, visibly and to assistive technology. Required, unless the control names itself (a checkbox or a switch with its own label): then leave it empty and the field adds only help and an error. — Field Names the color input. In a filled or outlined look the input draws it, floating in its box, and the Field draws no label row (FLD-25, CLI-15). |
labelHidden | boolean | false | Does not draw the label, which stays the accessible name. For a control whose visible label is elsewhere (a table column, a toolbar). — Field Hides the label wherever it would be drawn: the Field's row, or the input's floating label (FLD-25). |
supportingText | string | "" | Help shown below the control and given to assistive technology as the control's description. While the field is in error it gives way to errorText, unless the design system keeps both (comp.field.error-text.placement append). — Field |
errorText | string | "" | Shown while error is true, in supportingText's place — or below it, which then stays, where the design system's comp.field.error-text.placement is append: what is wrong and how to put it right, in words. — Field |
error | boolean | false | Puts the field in the error condition: the error text is drawn, the control is exposed as invalid and, where it has an error condition of its own, drawn in it. What a value means is the product's to validate; the field never sets this itself. — Field The Field puts its color input in the input's own error condition (FLD-8, CLI-9). |
disabled | boolean | false | Disables the control and draws the frame as disabled. Disable a framed control here, not on the control, so that its label follows. — Field The Field disables its color input, the picker button with it (FLD-14, CLI-31); the color field is then left out of its form (CLF-44). |
required | boolean | false | What the form asks of the control: true exposes it as required and draws the required mark beside the label. It never validates: a missing answer is the product's to report with error. — Field The Field exposes its color input as required (FLD-10, CLI-11). |
optional | boolean | false | Draws the optional tag after the label and adds optionalText to the control's description, because assistive technology has no state for it. Ignored while required is true: a control is never both. — Field |
requiredMark | auto | tag | asterisk | none | "auto" | How this control shows that it is required: tag is a small filled Tag with requiredText, asterisk is "*" after the label, none draws nothing and keeps the semantics. Auto takes comp.field.requirement.mark, which follows sys.behavior.requirement-mark, the system's one answer. Ignored unless required is true. — Field |
requiredText | string | "" | The text of the required tag, in the product's language ("Required", "必須"). The product's: Tanrei has no word for it. Empty reads the product's words; with neither, FLD-24 says what is drawn. — Field |
optionalText | string | "" | The text of the optional tag, in the product's language ("Optional", "任意"); also read to assistive technology as part of the description. The product's: Tanrei has no word for it. Empty reads the product's words. — Field |
invalidText | string | "" | The words for an input committed with a text that is not a color ("Enter six hexadecimal digits, like #0f766e"), in the product's language: given to the Field that frames the input, which shows them as its error text (CLI-20). While it is empty that Field shows its own errorText. — Color input Shown by the Field, in its supporting row (FLD-28). |
picker | boolean | false | Shows the picker button. Activated, it emits pickerRequest, and where the platform has a color picker of its own the input presents that picker unless the product cancelled the request. The input draws no picker surface itself. — Color input |
pickerLabel | string | "" | The accessible name of the picker button ("Choose color"). Required while picker is shown. — Color input |
插槽
| 插槽 | 说明 |
|---|---|
label-icon | A glyph before the label. — Field |
事件
| 事件 | 说明 |
|---|---|
input | The person changed the value — by an edit of the text that made it a color, another color or no color, or by a pick in the platform's picker; carries the new value. Not emitted when the product sets value, nor for an edit that leaves value as it was. — Color input |
change | The person committed a changed value: focus left the input, the action key was pressed, or the platform's picker closed; carries the value. — Color input |
pickerRequest | The person activated the picker button; carries the value. Cancelling it keeps the input from presenting the platform's picker: the product then presents its own surface and sets value to what was picked. — Color input |
entryError | The person committed a text that is not empty and is not a color; carries the text as typed and invalidText, the words the input has for it (empty where the product gave none: the Field that frames the input then shows its own errorText). — Color input |
状态
行为
以 EARS 形式写成的需求。每个平台的实现都按这些 ID 逐条测试。需求原文取自规格文件，原样以英文呈现。
| ID | 需求 |
|---|---|
CLF-43 | THE color field SHALL be a Field that frames one color input, and nothing else. It SHALL give label, labelHidden, supportingText, errorText, error, disabled, required, optional, requiredMark, requiredText and optionalText to its Field and variant, size, value, invalidText, picker and pickerLabel to its color input, each unchanged; SHALL hold the label-icon slot for its Field; and SHALL emit its color input's events as its own, each once. THE color field SHALL be as wide as the place it stands in, and its color input SHALL fill it: it is a block with no width of its own, as its Field is (FLD-1), around a control that fills the width it is given (CLI-44). Its value SHALL at every moment be the value its color input holds — a color in the value's own form, or the empty string (CLI-16) — and not the text the product set where the two differ (CLI-21). It SHALL draw no part of its own, hold no state of its own and have no token of its own: what it shows, how it behaves and what it exposes to assistive technology SHALL be exactly what that Field and that color input do when a product places the one in the other (FLD-1 to FLD-28; CLI-1 to CLI-44) — the label row and its requirement mark (FLD-2 to FLD-6), or the label that floats in the box with the Field's row left out (FLD-25, CLI-15, CLI-7); the supporting row, started at the value's text, after the swatch (FLD-7 to FLD-9, FLD-26, CLI-43); the name, the description and the states (FLD-10, FLD-11, FLD-14, CLI-11); and the entry error of a text that is not a color, shown in the Field's row (FLD-28, CLI-20). |
CLF-44 | WHERE the platform has forms (the web) THE color field SHALL be the one control the form sees: it SHALL take name, submit its color input's value, reset to the value it was first given, restore it on navigation, report to the form's constraint validation exactly what its color input would report there (CLI-11, CLI-20), and be left out WHILE disabled is true or a disabled group of the form holds it; its color input and its Field SHALL take no part in the form themselves. WHEN the action key asks for the form's submission (CLI-19) the form asked SHALL be the color field's own. |
CLF-45 | WHEN the color field is given focus — by the product, by a press on any part of it that FLD-12 or CLI-24 gives to the input, or by a form that reports its validity — THE color field SHALL pass the focus to the input of its color input, never to the picker button, and SHALL add no stop to the focus order: the stops inside it are its color input's, in that input's order (the input, then the picker button while it is shown, CLI-13). WHILE focus is anywhere inside it, the picker button included, THE color field SHALL count as focused for its Field, whose rows take their focused colors (FLD-13); the box takes its own only WHILE its input has focus (CLI-22). WHEN a picker the color input presented closes, focus SHALL be on the picker button (CLI-29), inside the color field. |
CLF-46 | IF the color field is placed in a Field THE color field SHALL in debug builds report that it is a field already and that the bare control is the color input, and both SHALL still render (FLD-15). WHILE it stands in a field group THE color field SHALL follow that group's disabled, through its own Field, and take nothing else from the group (FGR-20). |
CLF-47 | THE color field SHALL have no words of its own and SHALL read none: requiredText and optionalText are read by its Field (FLD-24), each from the instance's prop and then from the product's words; invalidText and pickerLabel are the instance's alone and are given to its color input as they are (CLI-42). |
CLF-48 | WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE color field SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on the element that carries its role — an id reference by the elements it names in the host's tree or a tree around it, an error message as part of the description while the color field is invalid — except those the color field owns (aria-label, aria-labelledby, aria-disabled), which it SHALL move and not expose: its name is label (CLF-43). WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE color field SHALL take it off that element. WHEN the product sets an aria- attribute the color field owns THE color field SHALL report it in debug builds. |
各平台名称对照
对等并不意味着 API 完全相同。同一份契约，由各平台以自己的惯用方式表达。
| 规格 | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
|---|---|---|---|---|---|
| 组件 | tanrei-color-field | TanreiColorField | TanreiColorField | TanreiColorField | ColorField |
variant · 属性 | variant | variant | variant | variant | variant |
size · 属性 | size | size | size | size | size |
value · 属性 | value | hex | value | controller | value |
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 |
invalidText · 属性 | invalidText | invalidText | invalidText | invalidText | invalidText |
picker · 属性 | picker | showsPicker | onPickerRequest | onPickerRequest | onPickerRequest |
pickerLabel · 属性 | pickerLabel | pickerLabel | pickerContentDescription | pickerSemanticLabel | pickerAccessibilityLabel |
input · 事件 | input | hex | onValueChange | onChanged | onValueChange |
change · 事件 | change | onCommit | onCommit | onCommit | onEndEditing |
pickerRequest · 事件 | pickerrequest | onPickerRequest | onPickerRequest | onPickerRequest | onPickerRequest |
entryError · 事件 | entryerror | onEntryError | onEntryError | onEntryError | onEntryError |
| 备注 | The tag tanrei-color-field, the class TanreiColorField, the React name ColorField. The element is composed as every composed element on the web is (the web package's README, Composed elements); what follows is what is particular to it. Members: <tanrei-field> holding one <tanrei-color-input> in its default slot; the product places none. The host is display: block. Value member: tanrei-color-input. The host is the form's element — name, the value and its state, validity anchored on the input, reset to the value attribute, restore, form, a disabled fieldset — and the input inside has no name. Props, set as properties on the member each is from. On the Field: label, labelHidden, supportingText, errorText, error, disabled, required, optional, requiredMark, requiredText, optionalText. On the color input: variant, size, value, invalidText, picker, pickerLabel. Attributes are the members' own, kebab-case: label-hidden, supporting-text, error-text, required-mark, required-text, optional-text, invalid-text, picker-label. Props of one name on both members — label, labelHidden, error, disabled — are the Field's; the input's are never set by the element and reach the input through the connection. Events: input, change, pickerrequest and entryerror are the color input's own composed events and leave by themselves, with the host as their target and value already new; pickerrequest stays cancelable from outside, and the input reads the result of its own dispatch before it opens the browser's picker. None is stopped and none is copied. Their detail types are the member's, re-exported: TanreiColorInputPickerRequestDetail, TanreiColorInputEntryErrorDetail. The color input changes a value the product sets without an event — it holds 0F766E as #0f766e, and a text that is not a color as empty (CLI-21) — so the host's value is the value member's at every moment, read back changed with no event (CLF-43). Slots: label-icon is passed to the Field by a slot element of the same name, rendered only while the host has a child for it. The element has no default slot. Parts: the member hosts are field and color-input. Exported from the Field: label, label-icon, requirement-label, supporting-text. Exported from the color input: container, outline, active-indicator, label, requirement-label, swatch, input, picker-button. Two names collide, label and requirement-label. Each is exported with its member's name before it, always (field-label, color-input-label, field-requirement-label, color-input-requirement-label), and under the bare name from both members as well, because the two are one thing to a person and are never drawn at once: FLD-25 is the sentence that holds it. Focus: the shadow root does not delegate. focus() and blur() call the color input's; a press on the label row focuses the input by FLD-12, a press on the box by CLI-24, and a press on the help does nothing. The browser's picker is opened by the color input from inside its own shadow root, in the user activation of the press on its picker button: two shadow roots deep, which showPicker() allows. The connection is the Field's with its control (FLD-25, FLD-26, FLD-28; CLI-43); the element takes no part in it. Parts and tokens of its own: none. The element writes no custom property: --tanrei-comp-field-*, --tanrei-comp-input-box-* and --tanrei-comp-color-input-* reach the members by inheritance, and one color field is set apart by setting any of them on the element. What its twin cannot do that it does: nothing. The twin: <tanrei-field label="Brand color" required supporting-text="Six hexadecimal digits, like #0f766e."><tanrei-color-input name="brand" value="#0f766e" picker picker-label="Choose color"></tanrei-color-input></tanrei-field>. Words: the element has none and reads none (CLF-47). | Not built on this platform yet: the color input as a view of its own and the color field as the Field around it, reading comp.input-box, comp.color-input and comp.field tokens. TanreiColorField(_ label:, hex: Binding<String>, showsPicker:, pickerLabel:, onCommit:, onPickerRequest:, onEntryError:); labelHidden follows the .labelsHidden() environment and disabled follows .disabled(_:). The text element, the system color picker and the swatch are the color input's and are in its note. The product's words are read by the Field from the \.tanreiWords environment value. | Not built on this platform yet: the color input as a composable of its own and the color field as the Field around it, reading comp.input-box, comp.color-input and comp.field tokens. Compose idiom, as TextField: TanreiColorField(value, onValueChange, label, …); the caller keeps value (state hoisting), enabled is the inverse flag and isError keeps Compose's name. The picker button is shown when onPickerRequest is not null. The rest is the color input's and is in its note. The product's words are read by the Field from LocalTanreiWords. | Not built on this platform yet: the color input as a widget of its own and the color field as the Field around it, reading comp.input-box, comp.color-input and comp.field tokens. Flutter idiom, as TextField and InputDecoration: labelText, helperText, errorText and enabled keep Flutter's names, enabled being the inverse flag. TanreiColorFormField wraps it as a FormField<String>. The rest is the color input's and is in its note. The product's words are read by the Field from the TanreiWords inherited widget. | Not built on this platform yet: the color input as a component of its own and the color field as the Field around it, reading comp.input-box, comp.color-input and comp.field tokens. <ColorField label="Brand color" value={value} onValueChange={setValue} />. The rest is the color input's and is in its note. The product's words are read by the Field from the TanreiWordsProvider context. |
令牌
| 令牌 | 引用 | 解析值（浅色） |
|---|---|---|
--tanrei-comp-field-counter-gap | sys.space.space200 | 16px |
--tanrei-comp-field-error-text-gap | sys.space.space50 | 4px |
--tanrei-comp-field-error-text-placement | — | 0 |
--tanrei-comp-field-label-icon-gap | sys.space.space100 | 8px |
--tanrei-comp-field-label-icon-size | sys.icon.small | 20px |
--tanrei-comp-field-label-gap | sys.space.space100 | 8px |
--tanrei-comp-field-motion-state-duration | sys.motion.role.state.default | 250ms |
--tanrei-comp-field-motion-state-easing | sys.motion.easing.state | cubic-bezier(0.2, 0, 0, 1) |
--tanrei-comp-field-requirement-asterisk-gap | sys.space.space25 | 2px |
--tanrei-comp-field-requirement-gap | sys.space.space100 | 8px |
--tanrei-comp-field-requirement-mark | sys.behavior.requirement-mark | 0 |
--tanrei-comp-field-standard-counter-color | sys.color.on-surface-variant | |
--tanrei-comp-field-standard-disabled-counter-color | — | |
--tanrei-comp-field-standard-disabled-error-text-color | — | |
--tanrei-comp-field-standard-disabled-error-counter-color | — | |
--tanrei-comp-field-standard-disabled-error-label-icon-color | — | |
--tanrei-comp-field-standard-disabled-error-label-color | — | |
--tanrei-comp-field-standard-disabled-error-required-asterisk-color | — | |
--tanrei-comp-field-standard-disabled-error-supporting-text-color | — | |
--tanrei-comp-field-standard-disabled-error-value-text-color | — | |
--tanrei-comp-field-standard-disabled-label-icon-color | — | |
--tanrei-comp-field-standard-disabled-label-color | — | |
--tanrei-comp-field-standard-disabled-required-asterisk-color | — | |
--tanrei-comp-field-standard-disabled-supporting-text-color | — | |
--tanrei-comp-field-standard-disabled-value-text-color | — | |
--tanrei-comp-field-standard-error-text-color | sys.color.error | |
--tanrei-comp-field-standard-error-counter-color | sys.color.on-surface-variant | |
--tanrei-comp-field-standard-error-label-icon-color | sys.color.on-surface-variant | |
--tanrei-comp-field-standard-error-label-color | sys.color.on-surface | |
--tanrei-comp-field-standard-error-required-asterisk-color | sys.color.primary | |
--tanrei-comp-field-standard-error-supporting-text-color | sys.color.on-surface-variant | |
--tanrei-comp-field-standard-error-value-text-color | sys.color.on-surface-variant | |
--tanrei-comp-field-standard-focused-counter-color | — | |
--tanrei-comp-field-standard-focused-error-text-color | — | |
--tanrei-comp-field-standard-focused-error-counter-color | — | |
--tanrei-comp-field-standard-focused-error-label-icon-color | — | |
--tanrei-comp-field-standard-focused-error-label-color | — | |
--tanrei-comp-field-standard-focused-error-required-asterisk-color | — | |
--tanrei-comp-field-standard-focused-error-supporting-text-color | — | |
--tanrei-comp-field-standard-focused-error-value-text-color | — | |
--tanrei-comp-field-standard-focused-label-icon-color | — | |
--tanrei-comp-field-standard-focused-label-color | — | |
--tanrei-comp-field-standard-focused-required-asterisk-color | — | |
--tanrei-comp-field-standard-focused-supporting-text-color | — | |
--tanrei-comp-field-standard-focused-value-text-color | — | |
--tanrei-comp-field-standard-label-icon-color | sys.color.on-surface-variant | |
--tanrei-comp-field-standard-label-color | sys.color.on-surface | |
--tanrei-comp-field-standard-required-asterisk-color | sys.color.primary | |
--tanrei-comp-field-standard-supporting-text-color | sys.color.on-surface-variant | |
--tanrei-comp-field-standard-value-text-color | sys.color.on-surface-variant | |
--tanrei-comp-field-supporting-text-gap | sys.space.space50 | 4px |
--tanrei-comp-field-value-text-gap | sys.space.space200 | 16px |
--tanrei-comp-field-label-typescale | sys.typescale.label | 500 14px/1.4286 |
--tanrei-comp-field-supporting-text-typescale | sys.typescale.label-small | 500 12px/1.3333 |
--tanrei-comp-field-value-text-typescale | sys.typescale.label | 500 14px/1.4286 |
测试样例
作为基准的渲染结果。所有平台都以相同的 ID 为每个样例截取快照，以便相互比较。
variant: stacked (27)
stacked-empty
label: Brand color stacked-filled
value: #0f766e label: Brand color stacked-large
size: large value: #0f766e label: Brand color stacked-label-hidden
value: #0f766e label: Brand color labelHidden: true stacked-supporting
value: #0f766e label: Brand color supportingText: Six hexadecimal digits, like #0f766e. stacked-white
value: #ffffff label: Page background stacked-black
value: #000000 label: Text stacked-picker
value: #0f766e label: Brand color picker: true pickerLabel: Choose color stacked-picker-empty
label: Brand color picker: true pickerLabel: Choose color stacked-picker-large
size: large value: #0f766e label: Brand color picker: true pickerLabel: Choose color stacked-error
value: #fde047 label: Brand color errorText: Too light for white text. Choose a darke… error: true stacked-error-picker
value: #fde047 label: Brand color errorText: Too light for white text. Choose a darke… error: true picker: true pickerLabel: Choose color stacked-disabled
value: #0f766e label: Brand color disabled: true stacked-picker-disabled
value: #0f766e label: Brand color disabled: true picker: true pickerLabel: Choose color stacked-label-icon
value: #0f766e label: Brand color slots: label-icon stacked-required
value: #0f766e label: Brand color required: true requiredText: Required stacked-optional
label: Accent color optional: true optionalText: Optional stacked-required-asterisk
value: #0f766e label: Brand color required: true requiredMark: asterisk stacked-required-label-icon
value: #0f766e label: Brand color required: true requiredText: Required slots: label-icon stacked-required-error
label: Brand color errorText: Choose a brand color. error: true required: true requiredText: Required stacked-required-disabled
value: #0f766e label: Brand color disabled: true required: true requiredText: Required stacked-required-ja
value: #0f766e label: ブランドカラー required: true requiredText: 必須 picker: true pickerLabel: 色を選択 stacked-optional-ja
label: アクセントカラー supportingText: # と 6 桁の 16 進数で入力します。 optional: true optionalText: 任意 stacked-required-rtl
value: #0f766e label: لون العلامة required: true requiredText: مطلوب picker: true pickerLabel: اختيار اللون direction: rtl stacked-error-rtl
value: #fde047 label: צבע המותג errorText: בהיר מדי לטקסט לבן. בחרו צבע כהה יותר. error: true direction: rtl slots: label-icon ltr-label-rtl
value: #0f766e label: Brand color (HEX) supportingText: sRGB, 6 digits direction: rtl long-label
value: #0f766e label: The color of the primary buttons, the li… supportingText: Six hexadecimal digits after a number si… required: true requiredText: Required variant: filled (5)
filled-empty
variant: filled label: Brand color filled-filled
variant: filled value: #0f766e label: Brand color filled-picker
variant: filled value: #0f766e label: Brand color picker: true pickerLabel: Choose color filled-error
variant: filled value: #fde047 label: Brand color errorText: Too light for white text. Choose a darke… error: true filled-disabled
variant: filled value: #0f766e label: Brand color disabled: true variant: outlined (7)
outlined-empty
variant: outlined label: Brand color outlined-filled
variant: outlined value: #0f766e label: Brand color outlined-large
variant: outlined size: large value: #0f766e label: Brand color outlined-picker
variant: outlined value: #0f766e label: Brand color picker: true pickerLabel: Choose color outlined-error
variant: outlined value: #fde047 label: Brand color errorText: Too light for white text. Choose a darke… error: true outlined-disabled
variant: outlined value: #0f766e label: Brand color disabled: true outlined-required
variant: outlined value: #0f766e label: Brand color required: true requiredText: Required 生成自 specs/color-field.spec.json, tokens/comp/field.tokens.json, design/tokens/
- 这个元素的 shadow root 里有一个
<tanrei-field>，其中放着一个<tanrei-color-input>，此外什么都没有。导入这个元素，两个成员也随之完成定义。 - 颜色字段是与表单关联的元素。它接受
name，并提交value：颜色，或者空字符串。重置时回到value属性（attribute）的值；在required且value为空时报告缺少值，在输入错误持续期间报告输入有误。它的两个成员不向表单添加任何条目。 value始终是颜色输入框的值：设为0F766E的值读回来是#0f766e，不是颜色的值读回来是空字符串。input和change是普通事件：从元素上读取value。pickerrequest和entryerror是 CustomEvent，前者带有detail.value，后者带有detail.text和detail.message。它们是颜色输入框自己的事件，以这个元素为目标。detail.message是invalidText，你没有提供时为空——字段在它的位置显示errorText时也是如此。- 部件：
field和color-input是两个成员。成员自己的部件在这里的名称与下一层相同：label-icon、supporting-text；container、outline、active-indicator、swatch、input、picker-button。label和requirement-label是画出来的那一个，无论由哪个成员绘制；field-label、color-input-label、field-requirement-label和color-input-requirement-label指的是某一个成员的。 - 这个元素自己不能获得焦点，也没有角色：
focus()会把焦点交给输入框，绝不交给选择器按钮。按标签行、方框、色块（没有选择器按钮时）或浮动标签，都会让输入框获得焦点。按帮助文本或错误文本，什么都不会发生。 - 只要焦点在字段里的任何位置，包括选择器按钮，标签和帮助文本就采用聚焦时的颜色。方框只在它的输入框获得焦点时才采用自己的聚焦颜色。
- 用
label为它命名——不该绘制标签的地方再加上label-hidden——绝不要用aria-label，它在这里不为任何东西命名。 - 元素自己不带任何文字。
requiredText和optionalText在你提供之前是空的。没有requiredText的必填字段，会在小标签本该在的位置显示星号。 - 浏览器的选择器因浏览器而异：在 Chromium 中是页面的一个弹出层，在 Firefox 和 Safari 中是系统的颜色窗口。它的外观、位置和按键都由浏览器决定。
- 用全角字符写的文本（
＃０ｆ７６６ｅ）不会读作颜色。 - 在元素定义之前，它没有尺寸。请预留高度。
| 方面 | 颜色字段 | 文本字段 |
|---|---|---|
| 里面是什么 | 一种颜色，写成 # 加六位数字 |
任意文本 |
| 显示什么 | 文本旁边的颜色样本 | 文本 |
| 检查什么 | 文本是不是颜色 | 什么也不检查 |
只显示而不编辑的颜色，请画一个样本，并在旁边用文本写出它的值或名称。颜色字段用于由用户设置的颜色。
- 写一个标签，说明这种颜色用在哪里，并让它在表单中保持可见。
- 在
supportingText里说明值的写法。字段处于错误状态时它仍然保留，所以invalidText不必再说一遍。 - 在要紧的地方，在
supportingText里用文字说出颜色的名称（“青绿色”）。十六进制的值很难让人知道颜色看起来是什么样。 - 只要设置了
picker，就要提供pickerLabel。 - 颜色的含义由你自己校验——它与背景的对比度、已经被占用的颜色——并用
error和errorText说明。 - 在已经为每种颜色命名的一行里（例如调色板的各个色调），使用颜色输入框：它只有方框，由自己的
label命名。
- 不要只靠色块来说明颜色。值是文本；分辨不出两个样本的用户，读到的是两个不同的值。
- 不要把空的
value本身当作错误。required从不做校验。 - 不要在用户键入时设置
aria-invalid或error。请等到change或entryerror。 - 不要把颜色字段放进字段。它已经是一个字段；字段框住的控件是颜色输入框。
- 角色
textbox- 标注
- The color field adds nothing to what its members expose and coordinates nothing: the Field gives the color input its name, its description and its required, invalid and disabled states (FLD-8, FLD-10, FLD-11, FLD-14), and the color input carries them on its own element (CLI-11). Assistive technology meets one text box named by label whose value is the color as text, and, while picker is true, one button named by pickerLabel — exactly as it meets a Field around a color input written by hand.
- 最小目标
- 即使外观尺寸更小，点击区域也满足最小目标尺寸。 minimum 32px · pointer 44px · spacing 8px · touch 48px
键盘操作
| 按键 | 动作 |
|---|---|
| Every key | The color input's (its accessibility block; CLI-13, CLI-19, CLI-28). The color field handles no key and adds no focus stop (CLF-45). |
备注
- One level down is the same thing: a Field with a color input in it. Every fixture has that pair as its twin, and the accessibility tree of the two is the same (CLF-43).
- On the web the two members stand in the color field's own shadow root, so the form meets the color field and not the input (CLF-44); focus passes through to the input (CLF-45).
- The color is never told by the swatch alone (WCAG 1.4.1), an error is always words (WCAG 3.3.1), and the swatch alone keeps its color in forced colors: each is the color input's or the Field's, and is said there (CLI-25, CLI-35, FLD-7, FLD-17).
生成自 specs/color-field.spec.json, tokens/sys/measure.tokens.json
- 输入框是一个文本框。它的名称是
label，无论是画出来的还是隐藏的；它的值是它显示的文本。 - 显示出来的辅助文本或错误文本是它的描述；字段为选填时，还会加上
optionalText。 error为 true 或输入错误持续期间，它暴露为无效；设置了required时，暴露为必填。- 字段获得焦点期间出现的错误，会以礼貌（polite）的方式朗读一次。它绝不会把焦点夺走。
- 色块是装饰性的，并且对辅助技术隐藏：说明颜色的是值的文本。
- 选择器按钮是一个独立的按钮，由
pickerLabel命名，暴露为会打开一个对话框。它是输入框之后的一个焦点停靠点。交给字段本身的焦点，总是落到输入框上。 - 值变化时不会朗读任何内容，字段也不会给颜色加上名称。
- 输入法正在组合输入时，字段不解读任何内容，也不处理任何按键。
- 字段的点击区域满足最小目标，选择器按钮是完整的目标。
- 文本放大到 200% 时，标签和帮助文本会换行。值保持在一行里，并且可以滚动；色块保持自己的大小。
- 在强制颜色模式下，字段会多出一道边线，并采用用户的颜色。只有色块保留值的颜色，因为显示这种颜色正是它的用途；它的边线用文本颜色。
- 在从右到左的布局中，字段会镜像：色块在右端，选择器按钮在左端。值本身仍然从左到右书写。
Web 上的已知差距：
- 浏览器的选择器不是 Tanrei 的：它的无障碍由浏览器自己负责。
- 在元素定义之前，什么都不绘制。
- 为每个颜色字段提供
label。 - 用页面所用的语言，在字段上编写
invalidText和pickerLabel。requiredText和optionalText可以写在字段上，也可以用setWords({ requiredText, optionalText })为整个产品只给一次。参见产品的文字。 - 自己校验颜色，设置
error，并编写说明如何改正这种颜色的errorText。 - 如果你呈现自己的选择器，请从选择器按钮打开它，给它一个名称，并在它关闭时把焦点交还给这个按钮。