- Web
tanrei-codeschedule - SwiftUI
TanreiInlineCoderadio_button_unchecked - Jetpack Compose
TanreiInlineCoderadio_button_unchecked - Flutter
TanreiInlineCoderadio_button_unchecked - React Native
InlineCoderadio_button_unchecked
生成自 docs/status/status.json, specs/inline-code.spec.json
在句子里、在标题里，以及 plain
在 package.json 所在的文件夹里运行
npm install，然后用
npm run dev -- --port 4000 启动服务器。
在组上设置 size
Plain：comp.button.container.shape
行内代码在句子里指出代码中的某样东西：一条命令、一个属性、一个文件、一个值。供人阅读和复制的多行代码用代码块。要按的键用键盘快捷键，它会读出修饰键的名称。
在 Web 上，行内代码不是一个元素，而是加在你自己的 code 元素上的一个类。文字就在文档里，所以在任何脚本运行之前，搜索、页面内查找和复制都能用。.tanrei-prose 里每个不在 pre 中的 code 不加类也会以同样的方式绘制，所以渲染出来的 Markdown 什么都不用加。
SwiftUI、Compose、Flutter 和 React Native 尚在计划中：本页开头各平台旁边的名称是规格为它们定下的，这些平台目前还没有提供任何实现。
<link rel="stylesheet" href="@tanrei/web/tokens.css" />
<link rel="stylesheet" href="@tanrei/web/code.css" />
<!-- Tonal：默认。 -->
<p>请先运行 <code class="tanrei-code" translate="no" spellcheck="false">npm install</code>。</p>
<!-- Plain：只有代码字体，颜色与周围的文本相同。 -->
<code class="tanrei-code" data-variant="plain">comp.button.container.shape</code>
<!-- 由祖先元素为其中的每一段代码做选择。 -->
<table data-tanrei-code="plain">
<tr><td><code class="tanrei-code">variant</code></td><td><code class="tanrei-code">filled</code></td></tr>
</table>import '@tanrei/web/code.css';
<p>请先运行 <code className="tanrei-code" translate="no" spellCheck={false}>npm install</code>。</p>| 属性 | 在 Web 上 |
|---|---|
text |
元素自己的内容 |
variant: tonal |
data-variant="tonal" |
variant: plain |
data-variant="plain" |
variant: auto（默认） |
不加属性。由最近的带 data-tanrei-code="plain" 或 "tonal" 的祖先元素决定；没有这样的祖先元素时为 tonal |
它会换行，每一段都保留自己的填充
令牌 tanrei.comp.navigation-drawer.item.selected.hovered.state-layer.color 比这一行还长。它在行末断开，绝不截断。
在链接里、在加粗文本里，以及一列代码
参见 Button 参考。绝不要在唯一的出路上设置 disabled。
属性默认值
variantfilledsizemedium行内代码没有自己的字号。它的字号是所在文本的字号乘以一个比例（comp.inline-code.label.scale），这个比例让代码字体和正文字体看起来一样大。在正文里是 14 旁边的 13。在标题里则是标题自己的字号。
它绝不会把所在的行撑高。填充与代码字体自身的文本框一样高，上下没有内边距。
一段代码随所在的行换行。它先在空格处断开。不含空格又比一行还长的部分在字符之间断开，并且不加连字符，因为连字符会改变代码。它绝不截断，也绝不滚动。
在链接里，它采用链接的颜色，链接的下划线从它下面穿过。在加粗文本里，它加重一档字重。它绝不倾斜。
它始终从左到右排列，自成一段，在从右到左的句子里也是如此。
构成
| 部件 | 说明 |
|---|---|
1 container · 可选 | The fill behind the text in the tonal form: as tall as the code face's own text box, with small corners and a little room at each end of every piece of the run. Decorative; the plain form has none. |
2 label | The code: its characters exactly as given, in the code face. |
3 outline · 可选 | An edge around the fill, where a design system gives it a width. The default system draws none. |
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
text | string | "" | The code: the characters exactly as they are to be read and copied ("npm install", "comp.button.container.shape"). Spaces inside it are kept. |
variant | auto | tonal | plain | "auto" | How the run is set apart. tonal: the code face on a faint fill. plain: the code face alone, in the color of the text around it, for a column or a list whose every entry is code and for text on a colored container. auto, the default, takes what the nearest ancestor chooses for the inline code inside it, and tonal where none does. |
状态
行为
以 EARS 形式写成的需求。每个平台的实现都按这些 ID 逐条测试。需求原文取自规格文件，原样以英文呈现。
| ID | 需求 |
|---|---|
ICD-1 | THE inline code SHALL set its text in the family, the weight and the letter spacing of comp.inline-code.label.typescale, at the font size of the text it sits in multiplied by comp.inline-code.label.scale — whatever that text is: a paragraph, a heading of any level, a lead paragraph, a caption, a label, a table cell — and SHALL NOT take the font size or the line height of the code role itself. |
ICD-2 | THE inline code SHALL sit on the baseline of the text it is part of, as a part of that text's line, and SHALL NOT make that line taller or change the distance between lines (PRS-17); its fill, where it has one, SHALL be as tall as the code face's own text box (from its ascent to its descent at the drawn size) and SHALL NOT be padded above or below. |
ICD-3 | WHILE the inline code is drawn tonal (ICD-5) THE inline code SHALL draw behind its text a fill of comp.inline-code.container.color with corners comp.inline-code.container.shape eased by sys.shape.corner-smoothing, extend that fill by comp.inline-code.container.padding-inline before the first and after the last character, draw its text in comp.inline-code.label.color, and, where comp.inline-code.outline.width is above 0, draw an edge of that width in comp.inline-code.outline.color inside the fill; it SHALL draw no elevation. |
ICD-4 | WHILE the inline code is drawn plain (ICD-5) THE inline code SHALL draw no fill, no edge and no padding, and SHALL draw its text in the color of the text it sits in, so that it reads on any container that text reads on. |
ICD-5 | WHILE variant is tonal or plain THE inline code SHALL be drawn in that form; WHILE variant is auto THE inline code SHALL be drawn in the form the nearest ancestor chooses for the inline code inside it (a table whose column is code, a callout, a list of names), and tonal where no ancestor chooses one; WHEN that choice changes while the inline code is shown THE inline code SHALL follow it at once. |
ICD-6 | THE inline code SHALL wrap with the line it sits in: it breaks first at the spaces inside it; a part with no space that is longer than the line SHALL break between any two characters rather than run past the edge of its container; and no hyphen or any other character SHALL be drawn at a break. Each piece of a run that breaks SHALL keep the fill, the corners and both paddings of ICD-3. THE inline code SHALL NOT cut its text and SHALL NOT scroll. |
ICD-7 | THE inline code SHALL draw the characters of text as given: every space is kept, a run of spaces is not collapsed, a line break in text is drawn as one space, and the text is not hyphenated, not capitalised or otherwise transformed, not translated by the platform's translation, not spell-checked and not turned into a link by itself. |
ICD-8 | THE inline code SHALL lay out its text as a left-to-right run of its own, isolated from the text around it, in every layout direction (PRS-26): a path, a call and an operator keep their order inside a right-to-left sentence and reorder nothing beside them; the run takes its place in the sentence by the sentence's own direction. |
ICD-9 | THE inline code 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 inline code is shown THE inline code SHALL draw itself for the new direction at once, without a motion of its own, keeping what it shows. |
ICD-10 | WHERE the inline code sits inside a link THE inline code SHALL draw its text in the link's color in place of comp.inline-code.label.color and the link's underline SHALL run under it; WHERE it sits inside strong text it SHALL gain sys.typescale.emphasis.body of weight over the weight of comp.inline-code.label.typescale, as strong text does (PRS-2); WHERE it sits inside emphasised text it SHALL NOT be slanted. |
ICD-11 | THE inline code SHALL NOT take pointer, touch or keyboard input of its own, SHALL NOT take focus or be a stop in the focus order, and SHALL NOT change anything it draws under a pointer, a press or focus: it has no hovered, focused, pressed, selected or disabled state, draws no state layer and no focus indicator, and emits no event. WHERE it is placed inside an element that takes input (a link, a button, a list item) input over it SHALL reach that element, which draws its own states. |
ICD-12 | THE inline code SHALL expose its text as text, read where it sits in the sentence, with the role of code where the platform has one and no name of its own; it SHALL NOT be announced as anything else and SHALL NOT expose its form. Selecting it SHALL select its characters with the text around it, and copying that selection SHALL yield exactly text: no character stands for the padding of ICD-3. |
ICD-13 | THE inline code SHALL draw all of its text in one color: it takes no syntax roles and SHALL NOT highlight, parse or otherwise interpret what it holds. |
ICD-14 | WHERE the platform draws with a person's own forced colors THE inline code SHALL draw its text in the platform's text color (the link color inside a link) and no fill, and an edge only where comp.inline-code.outline.width is above 0, in that text color: the face tells code from words, so nothing rests on the fill. |
ICD-15 | WHILE the text size is enlarged THE inline code SHALL grow with the text it sits in, keeping the proportion of ICD-1, its padding and its corners; at twice the text size in a container 320 wide it SHALL wrap as ICD-6 says and SHALL NOT cause horizontal scrolling. |
ICD-16 | IF text is empty THE inline code SHALL draw nothing, take no space and expose nothing. WHEN variant names a value this spec does not have THE inline code SHALL be drawn as variant auto, and in debug builds report the unknown value. |
各平台名称对照
对等并不意味着 API 完全相同。同一份契约，由各平台以自己的惯用方式表达。
| 规格 | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
|---|---|---|---|---|---|
| 组件 | tanrei-code | TanreiInlineCode | TanreiInlineCode | TanreiInlineCode | InlineCode |
text · 属性 | textContent | text | text | text | children |
variant · 属性 | data-variant | variant | variant | variant | variant |
| 备注 | A class, not an element, as prose is: <code class="tanrei-code">npm install</code> from the optional stylesheet @tanrei/web/code.css, and every code that is prose's own and not inside a pre when prose.css is loaded (the code rules of prose.css move here; PRS-16's islands apply). The text is the element's own content, so it is in the document for search engines, find-in-page and copy without script. variant is data-variant="tonal | plain" on the code; an ancestor chooses with data-tanrei-code="plain" (ICD-5), which rendered Markdown cannot set per run and a table or a callout can set once. ICD-1: font-family, font-weight and letter-spacing from the code role and font-size: calc(1em * var(--tanrei-comp-inline-code-label-scale)), so a heading's size is followed without a rule per level. ICD-2: line-height: 0 on the run, as today, and no block padding. ICD-6: overflow-wrap: anywhere, white-space: pre-wrap, hyphens: none, box-decoration-break: clone. ICD-7: translate="no" and spellcheck="false" are the author's or the renderer's attributes; the README says so. ICD-8: direction: ltr; unicode-bidi: isolate. ICD-14: forced-color-adjust is left alone; the fill is a background, which the mode removes. | TanreiInlineCode(_ text: String, variant:) is a Text that concatenates with the Text around it (Text("Run ") + TanreiInlineCode("npm install")), and AttributedString.tanreiInlineCode(variant:) styles a run of a renderer's attributed string. The ancestor's choice is an environment value. A Text run can carry a background color but neither corners nor padding: inside a sentence the tonal form is a square fill without ICD-3's padding, and the README says so; a run that stands alone is drawn whole. | AnnotatedString.Builder.tanreiInlineCode(text, variant) adds the run with its span style and an annotation, and Modifier.tanreiInlineCode() on the Text that holds it draws the fills behind the annotated ranges from the text layout (one rounded rectangle per line piece). TanreiInlineCode(text, variant) is a composable for a run that stands alone. The ancestor's choice is a composition local. | TanreiInlineCode.span(text, variant:) returns an InlineSpan for Text.rich; the fill is painted behind the run's boxes by TanreiInlineCodeText, which wraps the rich text. TanreiInlineCode(text) is a widget for a run that stands alone. The ancestor's choice is an inherited widget. | <InlineCode>npm install</InlineCode> nested in a <Text>. A nested Text takes a background color but, on iOS, neither corners nor padding: the tonal form inside a sentence is a square fill there, stated in the README. The ancestor's choice is a context. Follows the app's direction where an ancestor's is not known. |
令牌
| 令牌 | 引用 | 解析值（浅色） |
|---|---|---|
--tanrei-comp-inline-code-container-color | sys.color.surface-container-highest | |
--tanrei-comp-inline-code-container-padding-inline | sys.space.space50 | 4px |
--tanrei-comp-inline-code-container-shape | sys.shape.corner.extra-small | 3px |
--tanrei-comp-inline-code-label-color | sys.color.on-surface | |
--tanrei-comp-inline-code-label-scale | — | 0.9286 |
--tanrei-comp-inline-code-outline-color | sys.color.outline-variant | |
--tanrei-comp-inline-code-outline-width | sys.space.space0 | 0px |
--tanrei-comp-inline-code-label-typescale | sys.typescale.code | 400 13px/1.5385 |
测试样例
作为基准的渲染结果。所有平台都以相同的 ID 为每个样例截取快照，以便相互比较。
tonal
text: npm install plain
text: npm install variant: plain spaces
text: git commit -m "fix: a typo" long
text: tanrei.comp.navigation-drawer.item.selec… rtl
text: src/app/main.ts direction: rtl in-paragraph
{} in-heading
{} in-large-text
{} in-link-and-strong
{} wrapping
{} plain-in-table
variant: plain japanese
{} in-rtl-paragraph
direction: rtl 生成自 specs/inline-code.spec.json, tokens/comp/inline-code.tokens.json, design/tokens/
translate="no"和spellcheck="false"是由你或你的 Markdown 渲染器来写的属性。样式表无法设置它们。- 代码里的连字符是可以换行的位置，先于在字符之间断开。
- 对于换行的一段代码，WebKit 会绘制每一段的填充和圆角，但不绘制两端留出的空间：第一段之后的各段从填充的边缘开始。
- 只有在支持
white-space-collapse: preserve-spaces的浏览器里，一段代码内部的换行才会绘制成一个空格。请把一段代码写在一行里。 - 未知的
data-variant按auto绘制，调试构建中不报告任何内容。
| 变体 | 绘制什么 | 何时使用 |
|---|---|---|
| Tonal | 淡淡的填充上的代码字体 | 连续文本中的一个名称 |
| Plain | 只有代码字体，颜色与周围的文本相同 | 每一项都是代码的列或列表，以及有颜色的容器上的文本 |
- 句子要写得把代码当作词语读出来时也读得通。屏幕阅读器默认不朗读代码角色。
- 在语义状态的容器或反色表面这类有颜色的容器上使用 plain。tonal 的填充是一个表面角色，只与表面配对。
- 对于表格或一列名称，在祖先元素上统一设置一次形式（
data-tanrei-code="plain"）。
- 不要用行内代码表示强调。它说的是“这是代码”。
- 不要把要按的键放进行内代码。请使用键盘快捷键。
- 不要在里面放超过一行的内容。请使用代码块。
- 角色
code- 标注
- Inline code has no name of its own: it is text, read in its sentence. Its role is code where the platform has one (the web's code element); elsewhere it is plain text. Nothing announces its form.
- 最小目标
- 即使外观尺寸更小，点击区域也满足最小目标尺寸。 minimum 32px · pointer 44px · spacing 8px · touch 48px
键盘操作
| 按键 | 动作 |
|---|
备注
- Not interactive: inline code takes no input and no focus (ICD-11), so there is no target to size; minimumTarget holds trivially. Inside a link it is part of that link's text and target.
- Told from the words around it by its face, not by color (WCAG 1.4.1): the fill is decorative, and the plain form and forced colors (ICD-14) draw none.
- Contrast in the default system: the tonal form's text is on-surface on surface-container-highest, and a link's color on that fill is held at the same ratio — both by the token invariants that hold text roles at 4.5:1 on every surface (7:1 in the high-contrast schemes). The plain form has the contrast of the text it sits in.
- The tonal form's fill is a surface role, so it is correct on a surface. On a colored container (a callout, an inverse tooltip, a filled button) the text color of ICD-3 is not paired with that container's content color: use plain there. A component that hosts text on such a container chooses plain for the inline code inside it (ICD-5).
- Screen readers do not announce the code role by default, so a sentence must make sense when the code is read as words. Symbols are read as the person's settings say; write a name out in the sentence where its spelling matters.
- It reflows (WCAG 1.4.10): a long name breaks rather than scroll the page (ICD-6, ICD-15). No hyphen is added, because a hyphen would change the code.
- Keys to press are a keyboard shortcut, which reads modifier names aloud; inline code would read the characters.
生成自 specs/inline-code.spec.json, tokens/sys/measure.tokens.json
- 它就是
code元素，所以具有代码角色，它的文字在句子中所在的位置朗读。 - 它靠字体与周围的词语区分开，而不是靠颜色。在强制颜色模式下填充会消失，但什么都不会丢。
- 它不获得焦点，也不接受输入。在链接或按钮里，落在它上面的按下操作会到达那个元素。
- 在任何文本大小下，长名称都会断开，而不会让页面滚动。
- 选中并复制一个句子时，复制到的代码字符完全一致。
- 在拼写要紧的地方，把名称在句子里写出来，因为符号怎么读取决于用户的设置。
- 给这段代码标上
translate="no"，让浏览器的翻译不去动它。