代码块

类别: 容器
令牌: comp.code-block
层级: 基础

概览

Web: tanrei-code-block; schedule
SwiftUI: TanreiCodeBlock; radio_button_unchecked
Jetpack Compose: TanreiCodeBlock; radio_button_unchecked
Flutter: TanreiCodeBlock; radio_button_unchecked
React Native: CodeBlock; radio_button_unchecked

生成自 docs/status/status.json, specs/code-block.spec.json

标题、语言标签和复制按钮；代码根据它的语言高亮

// 表单的页脚：一个主操作，一条退路。
import { Button } from '@tanrei/react';

type FooterProps = { onSave: () => void; busy: boolean };

export function Footer({ onSave, busy }: FooterProps) {
  const retries = 3;
  return (
    <footer className="footer">
      <Button variant="text">取消</Button>
      <Button disabled={busy} onClick={onSave}>保存</Button>
    </footer>
  );
}

代码块显示供人阅读、比较和复制的代码。句子里的一个名称或一条命令用行内代码。

代码块自己做语法高亮。 把代码和它的 language 交给代码块，它就根据令牌给代码上色：不用安装语法高亮器，也不用编写主题或样式表。所以代码和页面上的其他一切一样，跟随配色方案、对比度级别和设计系统。高亮只涉及颜色和字重，别无其他：字符、行、选中的内容、复制的内容，以及屏幕阅读器朗读的内容，有没有高亮都一样。

用法

在 Web 上，代码留在你的文档里，是一个普通的 <pre><code>。没有脚本它也在那里：脚本加载失败的读者、搜索引擎和页面内查找都读得到。元素负责绘制它周围的框。加载 @tanrei/web/code.css，可以在元素定义之前就给代码块加上填充、圆角、内边距和字体。

SwiftUI、Compose、Flutter 和 React Native 尚在计划中：本页开头各平台旁边的名称是规格为它们定下的，这些平台目前还没有提供任何实现。

<link rel="stylesheet" href="@tanrei/web/tokens.css" />
<link rel="stylesheet" href="@tanrei/web/code.css" />

<tanrei-code-block
  headline="sizes.js"
  language="js"
  language-label="JavaScript"
  copy
  copy-label="复制"
  copied-label="已复制"
  copy-failed-label="无法复制"
>
  <pre><code>const sizes = ['small', 'medium', 'large'];</code></pre>
</tanrei-code-block>

<!-- 行号、带标记的行、提示符。 -->
<tanrei-code-block label="示例" line-numbers start-line="96" highlighted-lines="98, 100-101" highlighted-label="高亮">
  <pre><code>…</code></pre>
</tanrei-code-block>

<tanrei-code-block label="安装" prompt="$" copy copy-label="复制" copied-label="已复制" copy-failed-label="无法复制">
  <pre><code>npm install @tanrei/web</code></pre>
</tanrei-code-block>

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

import { CodeBlock } from '@tanrei/react';
import '@tanrei/web/code.css';

{/* 元素会把代码排成一行一行，所以让它拥有代码：把文本传给它。 */}
<CodeBlock headline="sizes.js" language="js" languageLabel="JavaScript" code={source} copy copyLabel="复制" copiedLabel="已复制" copyFailedLabel="无法复制" />

language 是一个标识符（tsx、css、sh）：代码块依据它来高亮，它本身不会被画出来。页眉里的文字是 language-label。由脚本构建的代码块不放 <pre><code>，而是设置 code 属性，元素会自己写出 <pre><code>。

规格

Filled 和 outlined，medium 和 small

const sizes = ['small', 'medium', 'large'];

for (const size of sizes) {
  const button = document.createElement('tanrei-button');
  button.setAttribute('size', size);
  document.body.append(button);
}

const sizes = ['small', 'medium', 'large'];

for (const size of sizes) {
  const button = document.createElement('tanrei-button');
  button.setAttribute('size', size);
  document.body.append(button);
}

行号、一行高亮，以及新增和删除的行

const sizes = ['small', 'medium', 'large'];

for (const size of sizes) {
  const button = document.createElement('button');
  const button = document.createElement('tanrei-button');
  button.setAttribute('size', size);
  document.body.append(button);
}

长行在代码块内部滚动，或者换行

export const footer = html`<footer class="form-footer"><tanrei-button variant="text" @click=${cancel}>取消</tanrei-button><tanrei-button variant="filled" @click=${save}>保存更改</tanrei-button></footer>`;

// 上面是一整行：它放不下，但绝不截断。

export const footer = html`<footer class="form-footer"><tanrei-button variant="text" @click=${cancel}>取消</tanrei-button><tanrei-button variant="filled" @click=${save}>保存更改</tanrei-button></footer>`;

// 上面是一整行：它放不下，但绝不截断。

提示符，以及显示行数的上限

npm install @tanrei/web
npx tanrei studio

01:00 tide high, gauge 1.55 m
02:00 tide falling, gauge 1.90 m
03:00 tide low, gauge 2.25 m
04:00 tide rising, gauge 2.60 m
05:00 tide high, gauge 1.20 m
06:00 tide falling, gauge 1.55 m
07:00 tide low, gauge 1.90 m
08:00 tide rising, gauge 2.25 m

两种外观。 filled 是柔和的填充，用于页面上的代码。outlined 没有填充，只有一道细线围着，用于已有填充的卡片或面板里的代码。

主体。 默认情况下，行绝不会被折断。放不下的行在代码块内部滚动，页面绝不横向滚动。wrap 则改为折行，续行从代码下方开始，而不是从行号下方开始。max-lines 按行数限制高度，其余部分在代码块内部滚动。

复制按钮始终绘制，绝不只在悬停时出现。它绝不会盖住无法从它下面移开的代码：滚动的主体会在末尾多出这么多空间，折行的各行则在它所在的那一列之前停下。它把代码复制为纯文本，不含行号、提示符、符号和已删除的行。手动选中后复制的，正是选中的那些字符。

带标记的行绝不只靠颜色来标记。

行	左边缘的竖条	色带	符号	在该行之前朗读
高亮	有	有		`highlighted-label`
新增	有	淡绿	+	`added-label`
删除	有	淡红	−	`removed-label`

行的列表由逗号分隔的数字和范围组成（"3, 7-9"）。它们按读者看到的行号计数，从 start-line 算起。

从右到左。 代码始终从左到右：在任何布局中，行、行号和滚动的起点都在左侧。只有外框会镜像，所以标题移到右侧，复制按钮移到左侧。

构成

部件	说明
1 `container`	The block: a quiet fill (filled) or no fill inside one hairline (outlined), with small corners. As wide as its layout gives it.
2 `outline` · 可选	The outlined look's edge: one hairline inside the container.
3 `header` · 可选	A row above the code that holds the title, the language and, where there is one, the copy button. It has no fill and no line of its own: it is the top of the same container.
4 `title` · 可选	What the code is: a file name or a few words. At the start of the header.
5 `language` · 可选	The language label: the language the code is in, in the product's words. At the end of the header, before the copy button.
6 `copy-button` · 可选	A Copy button (its own component) that copies the code: in the header where there is one, at the block's top end corner otherwise.
7 `body`	The part that holds the lines and scrolls inside the container when they do not fit.
8 `code`	The code: its lines, each on one line of the code's text style, each run in the color and weight of its syntax role where the code is highlighted.
9 `line-number` · 可选	A line's number, in the gutter at the left of the code. Drawn, not text.
10 `mark` · 可选	A bar at the left edge of a highlighted, an added or a removed line.
11 `sign` · 可选	A plus or a minus in the gutter of an added or a removed line. Drawn, not text.
12 `prompt` · 可选	A prompt drawn before each line of a block of commands. Drawn, not text.

属性

属性	类型	默认值	说明
`code`	`string`	`""`	The code as plain text, lines separated by line breaks. It is what is drawn, what is highlighted and what is copied. Ignored where runs are given: their texts, joined, are the code.
`variant`	`filled` \| `outlined`	`"filled"`	filled: a quiet fill, for code on a page. outlined: no fill inside one hairline, for code inside a container that is already filled (a card, a panel). A design system may add values.
`size`	`small` \| `medium`	`"medium"`	medium sets the code in the code role (13), for a page and a panel. small sets it in the small code role (12) with less padding, for dense interfaces. A design system may add values.
`title`	`string`	`""`	A file name or a few words that say what the code is ("button.tsx", "Response"). Drawn in the header and used as the block's accessible name.
`language`	`string`	`""`	The language the code is written in, as an identifier ("tsx", "css", "swift", "sh"), read without regard to case. It is what the block highlights by (COD-19, COD-27); it is not drawn. Empty, "text" and "plain" mean code that has no syntax; a language the highlighter does not know is drawn plain.
`languageLabel`	`string`	`""`	The language in the product's words ("TypeScript", "Shell"), drawn in the header. A label only: the block does not highlight by it, and draws no label of its own for language.
`highlight`	`boolean`	`true`	True: the block highlights the code by itself where it can (COD-19). False: it never does, whatever language says; runs the product gives are still drawn in their colors.
`label`	`string`	`""`	The block's accessible name where it has no title ("Example", "Request body"), in the product's language. Not drawn. A block that can scroll needs a title or a label.
`wrap`	`boolean`	`false`	False: a line is never broken, and lines that do not fit scroll sideways inside the block. True: a line that does not fit continues on the next row, and nothing scrolls sideways.
`lineNumbers`	`boolean`	`false`	Draws each line's number in a gutter at the left of the code.
`startLine`	`number`	`1`	The number of the first line: an excerpt of a file keeps the file's numbers. A whole number of 1 or more.
`highlightedLines`	`string`	`""`	The lines the text around the block talks about, by number, as numbers and ranges separated by commas ("3, 7-9"). Numbers are the ones lineNumbers would draw (they count from startLine).
`addedLines`	`string`	`""`	The lines a change adds, written as highlightedLines is.
`removedLines`	`string`	`""`	The lines a change takes away, written as highlightedLines is. They are drawn and are left out of what the copy button copies.
`highlightedLabel`	`string`	`""`	What assistive technology reads before a highlighted line ("Highlighted"), in the product's language. Required while highlightedLines names a line.
`addedLabel`	`string`	`""`	What assistive technology reads before an added line ("Added"). Required while addedLines names a line.
`removedLabel`	`string`	`""`	What assistive technology reads before a removed line ("Removed"). Required while removedLines names a line.
`prompt`	`string`	`""`	A prompt ("$", ">") drawn before every line that is not empty, for a block of commands to type. It is not part of the code: it is not selected, not copied and not read.
`maxLines`	`number`	`null`	The most lines shown at once; more than that scroll up and down inside the block. Null shows every line.
`copy`	`boolean`	`false`	Draws a copy button that copies the code.
`copyLabel`	`string`	`""`	The copy button's accessible name ("Copy"), in the product's language. Required while copy is true.
`copiedLabel`	`string`	`""`	What the copy button announces when the code has been copied ("Copied"). Required while copy is true.
`copyFailedLabel`	`string`	`""`	What the copy button announces when the platform refuses the copy ("Could not copy"). Required while copy is true.

事件

事件	说明
`copied`	The code was copied by the block's copy button; carries the text that was copied.
`copyFailed`	The platform refused the copy asked for by the block's copy button.

条目

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

`run`

A piece of the code that is one kind of thing — a comment, a keyword, a string, a function's name — as the block's highlighter found it, or as the product names it where the product gives the runs. The runs' texts, in order, are the code.

属性	类型	默认值	说明
`text`	`string`	`""`	The run's characters, exactly as in the code. It may hold line breaks: a run may span lines.
`syntax`	`plain` \| `comment` \| `keyword` \| `string` \| `constant` \| `function` \| `type` \| `tag` \| `property` \| `punctuation`	`"plain"`	What the run is. comment: a comment or a documentation comment. keyword: one of the language's own words (a keyword, a storage or modifier word, an at-rule, an annotation, an operator written as a word). string: text written in the code (a string, a character, a regular expression, the value of a markup attribute). constant: a value that is not text (a number, a boolean or null, a named constant, a unit, a color value, an escape inside a string). function: the name of a function or a method, declared or called. type: the name of a type (a class, a structure, an interface, an enumeration, a built-in type, a namespace). tag: what markup and style sheets address (an element's name, a component's name in markup, a selector). property: a name that belongs to something (a property, a key, a markup attribute, a style declaration's property, a command's option). punctuation: brackets, separators and the delimiters of markup. plain: none of these — variables, parameters, operators written as signs, text between tags. The values are those of the token axis comp.code-block.syntax and plain; a design system may add values to that axis.

规格	Web	SwiftUI	Jetpack Compose	Flutter	React Native
条目	`span`	`TanreiCodeRun`	`TanreiCodeRun`	`TanreiCodeRun`	`CodeRun`
`text` · 属性	`textContent`	`text`	`text`	`text`	`text`
`syntax` · 属性	`data-syntax`	`syntax`	`syntax`	`syntax`	`syntax`
备注	A `<span data-syntax="keyword">` inside the light-DOM `<code>`; text outside any such span is plain. Not a custom element. It is what the element's highlighter writes, what `highlightToHtml` writes where the page is made, and what a product's own highlighter writes — one form, so the stylesheet and the element cannot tell them apart and do not need to.	`TanreiCodeRun(_ text: String, _ syntax: TanreiSyntaxRole = .plain)`, given as `runs:`; `AttributedString` ranges carrying a `tanreiSyntax` attribute are accepted in its place, which is what a highlighter that returns an attributed string gives.	`TanreiCodeRun(text, syntax = TanreiSyntaxRole.Plain)` in `runs`; an `AnnotatedString` whose ranges carry a `TanreiSyntaxRole` annotation is accepted in its place.	`TanreiCodeRun(text, [TanreiSyntaxRole syntax = TanreiSyntaxRole.plain])` in `runs:`; `TanreiCodeBlock.fromSpans` takes the `TextSpan` tree of a highlighter with a function that names each span's role.	An entry of the `runs` prop: `{ text: 'const', syntax: 'keyword' }`.

状态

行为

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

ID	需求
`COD-1`	THE code block SHALL draw a container filled with the container color of its variant (comp.code-block.filled.container.color for filled, comp.code-block.outlined.container.color for outlined), with corners comp.code-block.container.shape eased by sys.shape.corner-smoothing and no elevation, as wide as its layout gives it and never wider, and SHALL bring no space outside itself: the layout it sits in spaces it (PRS-15). WHILE variant is outlined it SHALL draw an edge comp.code-block.outline.width wide in comp.code-block.outline.color inside the container's size, following its corners; WHILE variant is filled it SHALL draw no edge.
`COD-2`	THE code block SHALL set the code in the text style of its size, taken whole (comp.code-block.code.typescale.medium for medium, and so on), in comp.code-block.code.color where a run names no syntax role, every line of the code on one line of that style; it SHALL draw the characters as given — every space kept, a tab advancing to the next multiple of comp.code-block.code.tab-size columns, nothing hyphenated, transformed, translated or spell-checked — and SHALL draw no empty last line for one line break at the end of the code.
`COD-3`	THE code block SHALL pad the code by the block padding of its size above the first line and below the last (comp.code-block.container.padding-block.medium for medium, and so on) and by the inline padding of its size (comp.code-block.container.padding-inline.medium for medium, and so on) before the start of the lines, or of the gutter where there is one (COD-13), and after the end of the longest line.
`COD-4`	WHILE wrap is false THE code block SHALL NOT break a line; WHEN a line is wider than the body THE body SHALL scroll sideways inside the container, by pointer, touch, the wheel and the keyboard (COD-7), the page SHALL NOT scroll sideways for it, and the padding after the longest line SHALL scroll with the code, so that its last character can be brought clear of the container's edge. The header and the copy button SHALL NOT scroll with the code. A gesture or a wheel movement up or down over a body that cannot scroll that way SHALL scroll the page.
`COD-5`	WHILE wrap is true THE code block SHALL continue a line that does not fit on following rows: it breaks first at the spaces of the line and, where a part with no space is wider than the row, between any two characters; a following row SHALL begin at the column where the line's code begins (after the gutter and the prompt), draw no mark of its own and add no character; the body SHALL NOT scroll sideways; and what is selected or copied SHALL hold the line breaks of the code alone.
`COD-6`	WHILE maxLines is a number and the code has more lines than that THE body SHALL be maxLines lines of the code's text style high plus its paddings and SHALL scroll up and down inside the container; the header and the copy button SHALL NOT scroll with it. WHILE maxLines is null, or the code has no more lines than it, THE code block SHALL be as tall as its lines.
`COD-7`	WHILE the body can scroll, sideways or up and down, THE body SHALL be one stop in the focus order after the copy button, SHALL scroll by the arrow keys, Page Up, Page Down, Home and End as its platform scrolls any region, and, WHEN it has keyboard focus, SHALL show the focus indicator inside the container's edge, its corners following comp.code-block.container.shape, as sys.behavior.focus-style names (ring or glow), without animation; focus gained by pointer or touch SHALL NOT show it; a platform that cannot draw a choice SHALL fall back to the first value and state that in its README. WHILE the body cannot scroll it SHALL NOT be a stop in the focus order.
`COD-8`	WHILE title or languageLabel is not empty THE code block SHALL draw a header above the code, in the same container, with no fill and no line of its own: the title at the start, in comp.code-block.title.typescale and comp.code-block.title.color, on one line, laid out as text of its own direction and cut with an ellipsis at the end of that direction when it does not fit; the language label (languageLabel) at the end, before the copy button where there is one, in comp.code-block.language.typescale and comp.code-block.language.color, never cut; its items comp.code-block.header.gap apart. The header's row SHALL begin comp.code-block.copy-button.inset from the container's top edge, be as tall as the copy button where there is one and as one line of the title's text style otherwise, with its items centred on it; the title SHALL begin at the inline padding of COD-3; and the code SHALL begin comp.code-block.header.padding-block-end below the row in place of the block padding of COD-3.
`COD-9`	WHILE copy is true THE code block SHALL place a Copy button (CPY) — icon-only, of the text variant and the small size, named by copyLabel, with copiedLabel and copyFailedLabel as its two announcements — comp.code-block.copy-button.inset from the container's top edge and from its end edge: at the end of the header where there is one, and over the top end corner of the body otherwise. THE copy button SHALL be drawn whenever the block is, never only under a pointer or on focus; SHALL come before the body in the focus order and in reading order; and SHALL keep its place and size in every form it takes (CPY-7). THE container SHALL be at least as tall as the copy button plus twice that inset.
`COD-10`	WHILE copy is true and there is no header THE code block SHALL keep code readable beside the button: WHILE wrap is false the padding after the longest line (COD-3, COD-4) SHALL be widened by the button's width and that inset, so that any line's end can be scrolled clear of the button; WHILE wrap is true every row SHALL end before the button's column. THE copy button SHALL stand on a patch of the container's own color where code can pass under it.
`COD-11`	THE copy button of COD-9 SHALL copy the code as plain text: its lines in order, joined by line breaks, without line numbers, prompts, signs or labels, without the lines removedLines names, and with no line break that wrapping added. WHEN the Copy button emits copied or copyFailed THE code block SHALL emit its own event of that name, copied carrying the text.
`COD-12`	WHEN a person selects in the body THE code block SHALL select characters of the code alone: line numbers, prompts, signs, bars and the labels of COD-15 and COD-16 SHALL NOT be selectable and SHALL NOT be part of what a copied selection holds; a copied selection SHALL hold the selected characters, removed lines included where they were selected, with the code's own line breaks.
`COD-13`	WHILE lineNumbers is true THE code block SHALL draw before each line its number, counting from startLine, in the code's text style with digits of one width, in comp.code-block.line-number.color, right-aligned in a column as wide as the widest number drawn; a line that wraps SHALL carry its number on its first row only. The gutter — from the left: the bar's column (COD-15), the numbers, the signs (COD-16) — SHALL stand comp.code-block.line-number.gap from the start of the code, SHALL stay in view on the container's color while the code scrolls sideways under it, and SHALL be kept from assistive technology.
`COD-14`	THE code block SHALL read highlightedLines, addedLines and removedLines as numbers and ranges separated by commas, each number being a line's number as COD-13 counts it whether or not numbers are drawn; it SHALL ignore a number outside the code and an entry it cannot read, and in debug builds report it. A line named as both added and removed SHALL be drawn removed, and in debug builds reported; a line named as highlighted and as added or removed SHALL be drawn as both.
`COD-15`	WHILE a line is highlighted THE code block SHALL draw behind all of its rows a band of comp.code-block.line.highlighted.container.color from the container's left edge to its right, and at the container's left edge a bar comp.code-block.line.mark.width wide in comp.code-block.line.highlighted.mark.color as tall as the line; and SHALL expose highlightedLabel to assistive technology before the line's text, without drawing it. The line's code SHALL keep its colors.
`COD-16`	WHILE a line is added or removed THE code block SHALL draw at the container's left edge a bar comp.code-block.line.mark.width wide, as tall as the line, and in the gutter after the numbers a sign in the code's text style — a plus (+) for an added line, a minus (−) for a removed one — both in comp.code-block.line.added.mark.color for an added line and comp.code-block.line.removed.mark.color for a removed one; and SHALL expose addedLabel or removedLabel before the line's text, without drawing it. THE code block SHALL also draw behind the line, from the container's left edge to its right and under the bar, the sign and the code, a band in comp.code-block.line.added.container.color for an added line and comp.code-block.line.removed.container.color for a removed one, so that a reader scanning the block tells added from removed lines whatever the colors of their code. The line's code SHALL keep its syntax colors, which are held on these bands at the contrast of code text, and SHALL NOT be struck through: the sign and the label say what the line is, never the color alone.
`COD-17`	WHILE prompt is not empty THE code block SHALL draw the prompt and one space of the code's text style before the first row of every line that is not empty, in comp.code-block.prompt.color, after the gutter; following rows of a wrapped line SHALL begin under the code, not under the prompt; the prompt SHALL be kept from assistive technology and is not code (COD-11, COD-12).
`COD-18`	THE code block SHALL draw each run in the color of its syntax role — comp.code-block.syntax.color.comment for comment, comp.code-block.syntax.color.keyword for keyword, comp.code-block.syntax.color.string for string, comp.code-block.syntax.color.constant for constant, comp.code-block.syntax.color.function for function, comp.code-block.syntax.color.type for type, comp.code-block.syntax.color.tag for tag, comp.code-block.syntax.color.property for property, comp.code-block.syntax.color.punctuation for punctuation, and comp.code-block.code.color for plain — and with the weight of the code's text style plus the emphasis of its role (comp.code-block.syntax.emphasis.keyword for keyword, and so on; none for plain), whether the block's highlighter found the run (COD-19) or the product gave it (COD-29). A syntax role SHALL change a run's color and weight alone — never its size, family, spacing, slant, decoration or background — so that highlighted code and the same code drawn plain have the same lines, columns and size. A role a design system added to the axis SHALL be drawn from that role's two tokens in the same way.
`COD-19`	WHILE highlight is true, the product gives no runs (COD-29), language names a language the highlighter knows (COD-27) and the code is no longer than comp.code-block.syntax.max-length characters THE code block SHALL highlight the code by itself: its highlighter reads the code as that language and names the syntax role of every run, and the block draws the runs as COD-18 says. Highlighting SHALL change nothing but colors and weights: the code's characters, its lines, what is selected, what is copied (COD-11, COD-12) and what assistive technology reads (COD-22) are those of the code as given. In every other case THE code block SHALL draw all of the code in comp.code-block.code.color. WHEN a run names a syntax role the active design system does not have THE code block SHALL draw that run as plain, and in debug builds report the unknown role.
`COD-20`	THE code block SHALL lay out the body left to right in every layout direction (PRS-26): lines begin at the left, the gutter, the bars and the bands' start are at the left, the prompt is at the left of its line, and sideways scrolling starts at the left. WHERE the layout direction is right-to-left THE code block SHALL mirror the frame alone: the title at the right of the header, the language and the copy button at the left, and the copy button of a block without a header at the top left corner; the paddings of COD-10 SHALL then apply at the button's side. A comment written in a right-to-left script SHALL be laid out by the bidirectional algorithm inside its left-to-right line.
`COD-21`	THE code block 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 code block is shown THE code block SHALL draw itself for the new direction at once, without a motion of its own, keeping its scroll offsets, its selection and its focus.
`COD-22`	THE code block SHALL expose its code to assistive technology as text in reading order, line after line, with the role of code where the platform has one, inside a group named by title where it is not empty and by label otherwise; the language label SHALL be read as text of the header and language itself SHALL NOT be read; a syntax role SHALL NOT be exposed, and colors arriving or changing (COD-28, COD-30) SHALL NOT be announced; and WHEN code, the runs or a marked line changes THE code block SHALL draw and expose the new content at once, without a motion, SHALL NOT announce the change, and SHALL keep the body's scroll offsets where the content still reaches them.
`COD-23`	WHERE the platform draws with a person's own forced colors THE code block SHALL draw an edge comp.code-block.outline.width wide in the platform's text color inside its container in every variant; its code in the platform's text color whatever syntax role a run names, every run keeping the weight of its role; line numbers, prompts, signs and bars in that text color; and no band: a highlighted line is then marked by its bar, and an added or a removed line by its bar and its sign.
`COD-24`	WHILE the text size is enlarged THE code block SHALL grow its lines, its gutter and its header with the text, keeping its paddings and its corners, and the copy button SHALL keep the size and the target of its own spec; at twice the text size in a container 320 wide the body SHALL scroll inside the container (COD-4) or wrap (COD-5), the title SHALL be cut as COD-8 says, and the page SHALL NOT scroll sideways.
`COD-25`	IF code is empty and no runs are given THE code block SHALL draw nothing, take no space and expose nothing, and in debug builds report that a code block has no code. WHILE copy is true and copyLabel, copiedLabel or copyFailedLabel is empty, WHILE a line is marked and the label of its mark (highlightedLabel, addedLabel, removedLabel) is empty, and WHILE the body can scroll and both title and label are empty THE code block SHALL still draw, and in debug builds report what is missing. WHEN variant or size names a value the active design system does not have THE code block SHALL render with the default value, and in debug builds report the unknown value; a startLine below 1 or not whole SHALL be taken as 1 and a maxLines below 1 as null.
`COD-26`	THE code block SHALL NOT take a press itself and has no hovered, pressed, selected or disabled state: it draws no state layer and no ripple. What is pressed inside it is its Copy button, which answers a press as its own spec says (CPY-12 to CPY-14).
`COD-27`	THE code block SHALL read language as an identifier, without regard to case and to space around it, and match it against the names and the other names of the languages its highlighter knows. THE highlighter the code block brings SHALL know these languages: markup (html, xml, svg), css, javascript (js, mjs, cjs, jsx), typescript (ts, tsx), json (jsonc), shell (sh, bash, zsh), swift, kotlin (kt) and dart; a product SHALL be able to add a language, to replace one, and to replace the highlighter whole, once for all the code blocks it draws. WHILE language is empty, "text", "plain" or "plaintext" THE code block SHALL draw the code plain and report nothing; WHILE language names a language the highlighter does not know it SHALL draw the code plain, and in debug builds report the unknown language once for each name. THE code block SHALL NOT guess a language from the code, from title or from languageLabel.
`COD-28`	THE code block SHALL draw the code at once, plain, without waiting for its highlighter: no part of the highlighter is loaded for a block that will not use it, and a block that waits for it is complete in every other respect. WHEN the runs are ready THE code block SHALL draw every color and weight in one frame, without a motion and without a fade, moving no line and no character, changing the size of nothing, and keeping the body's scroll offsets, the selection and the focus. WHERE the runs are already with the code when the block is first drawn (code highlighted where the page was made) THE code block SHALL draw them in its first frame.
`COD-29`	WHERE the product gives runs THE code block SHALL take the runs' texts, joined in order, as the code, SHALL draw them as COD-18 says, and SHALL NOT highlight the code itself, whatever language and highlight say: code that was highlighted where the page was made, or by a highlighter the product chose for one block, is drawn as it was given. Code given with the statement that it has been highlighted and has no run with a role SHALL be drawn plain in the same way.
`COD-30`	WHEN code, language or highlight changes while the block is shown THE code block SHALL draw the new code at once and highlight it again; a result for code that is no longer the code shown SHALL be dropped, never drawn. WHERE its highlighter can answer in the same frame THE code block SHALL draw the new code with its colors in that frame. Otherwise the lines before the first line that changed SHALL keep their colors until the new runs are ready, and the lines from there on SHALL be drawn plain until then, so that code that grows at its end does not lose and regain its colors with every piece.
`COD-31`	WHILE the code is longer than comp.code-block.syntax.max-length characters THE code block SHALL draw all of it plain — never a part of it highlighted — and in debug builds report that the code is too long to highlight. Runs the product gives are drawn whatever their length.
`COD-32`	IF the highlighter cannot be loaded, fails while it reads the code, or answers with runs whose texts do not join to the code exactly THEN THE code block SHALL draw the code plain, SHALL keep everything else it draws and does — the header, the copy button, the lines, the marks, scrolling — and in debug builds report what failed. A failure in one block SHALL NOT change another block.
`COD-33`	WHILE addedLines or removedLines names a line THE code block SHALL highlight the code as the two texts it holds: the lines that are not removed, in order, are read as one text — the code as it is after the change, which is what is copied (COD-11) — and color the lines that are not removed; the lines that are not added, in order, are read as another — the code as it was before — and color the removed lines. A highlighted line and an added or a removed line SHALL keep the colors of their runs over the band and beside the bar and the sign (COD-15, COD-16).
`COD-34`	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 code block 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 its body, which SHALL be a group WHILE it has a name: its title or label, or one given so — an id reference by the elements it names in the host's tree or a tree around it, a description after its own. WHILE the title or label is not empty it is the body's name, over a name given so; a name given so SHALL count as the body's name for the report of COD-25. 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 code block SHALL take it off that element.

各平台名称对照

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

规格	Web	SwiftUI	Jetpack Compose	Flutter	React Native
组件	`tanrei-code-block`	`TanreiCodeBlock`	`TanreiCodeBlock`	`TanreiCodeBlock`	`CodeBlock`
`code` · 属性	`code`	`code`	`code`	`code`	`code`
`variant` · 属性	`variant`	`variant`	`variant`	`variant`	`variant`
`size` · 属性	`size`	`size`	`size`	`size`	`size`
`title` · 属性	`headline`	`title`	`title`	`title`	`title`
`language` · 属性	`language`	`language`	`language`	`language`	`language`
`languageLabel` · 属性	`languageLabel`	`languageLabel`	`languageLabel`	`languageLabel`	`languageLabel`
`highlight` · 属性	`highlight`	`highlightsSyntax`	`highlightSyntax`	`highlightSyntax`	`highlight`
`label` · 属性	`label`	`label`	`label`	`label`	`label`
`wrap` · 属性	`wrap`	`wrapsLines`	`softWrap`	`softWrap`	`wrap`
`lineNumbers` · 属性	`lineNumbers`	`showsLineNumbers`	`showLineNumbers`	`showLineNumbers`	`showLineNumbers`
`startLine` · 属性	`startLine`	`startLine`	`startLine`	`startLine`	`startLine`
`highlightedLines` · 属性	`highlightedLines`	`highlightedLines`	`highlightedLines`	`highlightedLines`	`highlightedLines`
`addedLines` · 属性	`addedLines`	`addedLines`	`addedLines`	`addedLines`	`addedLines`
`removedLines` · 属性	`removedLines`	`removedLines`	`removedLines`	`removedLines`	`removedLines`
`highlightedLabel` · 属性	`highlightedLabel`	`highlightedLabel`	`highlightedLabel`	`highlightedLabel`	`highlightedLabel`
`addedLabel` · 属性	`addedLabel`	`addedLabel`	`addedLabel`	`addedLabel`	`addedLabel`
`removedLabel` · 属性	`removedLabel`	`removedLabel`	`removedLabel`	`removedLabel`	`removedLabel`
`prompt` · 属性	`prompt`	`prompt`	`prompt`	`prompt`	`prompt`
`maxLines` · 属性	`maxLines`	`lineLimit`	`maxLines`	`maxLines`	`maxLines`
`copy` · 属性	`copy`	`showsCopyButton`	`showCopyButton`	`showCopyButton`	`copy`
`copyLabel` · 属性	`copyLabel`	`copyLabel`	`copyLabel`	`copyLabel`	`copyLabel`
`copiedLabel` · 属性	`copiedLabel`	`copiedLabel`	`copiedLabel`	`copiedLabel`	`copiedLabel`
`copyFailedLabel` · 属性	`copyFailedLabel`	`copyFailedLabel`	`copyFailedLabel`	`copyFailedLabel`	`copyFailedLabel`
`copied` · 事件	`copied`	`onCopied`	`onCopied`	`onCopied`	`onCopied`
`copyFailed` · 事件	`copyfailed`	`onCopyFailed`	`onCopyFailed`	`onCopyFailed`	`onCopyFailed`
备注	`<tanrei-code-block headline="sizes.js" copy copy-label="Copy" …><pre><code>…</code></pre></tanrei-code-block>`: the code stays in the light DOM as an ordinary `<pre><code>`, so it is in the document without script — for a reader whose script failed, for search engines and crawlers, for find-in-page and for the browser's own copy — and the element decorates it. The shadow root draws the header, the copy button (`<tanrei-copy-button>`), the focus ring and the scrolling body, and slots the `<pre>`; the code is read from the slotted `<code>`'s text, and the `code` attribute is for a block built by script (the element then writes the `<pre><code>` itself). Runs are `<span data-syntax="…">` in that `<code>` (COD-18); the stylesheet colors them with `::slotted` being unable to reach them, so the rules live in the optional light-DOM stylesheet `@tanrei/web/code.css`, scoped to `tanrei-code-block`, which also gives a not-yet-upgraded or script-less block its fill, corners, padding, face and `overflow-x: auto` through `tanrei-code-block:not(:defined)` and a bare `.tanrei-prose pre` (the `pre` rules are there, not in `prose.css`). Lines: the element needs one box per line for numbers, marks, the prompt and wrapping; it uses `[data-line]` children of the `<code>` where the highlighter emitted them and otherwise wraps each line in a `<span data-line>` on upgrade, moving nodes and splitting text nodes and spans at line breaks without adding or removing a character, so `textContent` is unchanged. Line numbers, signs and the prompt are `::before` content of the line (`counter()`, with an empty alternative text so they are not read), `user-select: none`; the gutter is `position: sticky; left: 0` on the container's color. `highlighted-lines`, `added-lines` and `removed-lines` are attributes; the element sets `data-highlighted`, `data-added` or `data-removed` on the lines and puts each label in a visually hidden, unselectable prefix referenced from the line. The body is the scroll container with `tabindex="0"`, `role="group"` and `aria-label` only while it overflows (a `ResizeObserver` decides); `dir="ltr"` on the body, and the host mirrors the header by `:dir()` (COD-20). `tab-size` from the token. COD-11 writes through the copy button with a text built from the lines, not from `innerText`. Highlighting. `highlight` is a boolean that is true by default, so its attribute is written to turn it off: `highlight="false"` (the property takes a boolean). The highlighter is the module `@tanrei/web/highlight`: no dependency, no DOM, the same file in a browser and in Node. It exports `highlight(code, language)` (the runs, or null for a language it does not know), `highlightToHtml(code, language, { lines })` (the inner HTML of the `<code>`: escaped text, `<span data-syntax>` runs and, with `lines`, one `<span data-line>` per line), `registerLanguage(names, grammar)` (a grammar, or a function that imports one), `setHighlighter(fn)` (replace it whole; null turns automatic highlighting off for the page), `languages()` and `foldScope(scope)` (the table that folds a dotted scope name into a syntax role, for a product that brings a highlighter of dotted scope names). The element does not import the module: a block that needs it (COD-19) imports it with `import()` the first time, and each grammar is a chunk of its own imported the first time its language is asked for, so a page whose code was highlighted where it was made, or that shows no code, loads none of it. Budget, held by a test of the built files: the core of the module at most 3 kB and each grammar at most 3 kB, compressed; tsx and jsx are the typescript and javascript grammars with markup switched on, not grammars of their own. A grammar is data — named states, each an ordered list of rules (a pattern, the role of what it matches, and the state to enter or leave) — read by one small interpreter; patterns are sticky regular expressions without nested quantifiers, so the time to read a text grows with its length and no text can stall the page. The highlighter answers in the same task once its grammar is loaded, which is what lets COD-30 draw new code with its colors in one frame; the first answer for a language waits for the import and the block is plain until then (COD-28). Code highlighted where the page is made is first-class: `<code data-syntax-of="tsx">` holding `<span data-syntax>` runs, written by `highlightToHtml` in a build, a server or a Markdown plugin, is the product's runs (COD-29) — the element reads the attribute or any `[data-syntax]` it did not write itself and never highlights that code again, so the first paint has its colors and nothing is imported. The element writes its own runs as spans into the same light-DOM `<code>`, splitting at line boundaries, in one synchronous pass that replaces the children of each changed `[data-line]` and touches no other line (COD-30); it marks the runs it wrote so that it can tell them from the product's. Spans, not the CSS Custom Highlight API: a highlight registered by script cannot be in the HTML a server sends, and `::highlight()` may set a color but not a weight, which is how keywords are told (COD-18); for assistive technology the two are the same, since neither adds a role. A framework that owns the children of the `<code>` (it renders them from state) should pass `code` as a property and let the element write the `<pre><code>`, or give the runs itself. `comp.code-block.syntax.max-length` is read from the generated tokens module, not from CSS. The colors are rules of `@tanrei/web/code.css`, one per value of the syntax axis, generated from the tokens so that a role a layer adds gets its rule.	`TanreiCodeBlock(code:, runs:, variant:, size:, title:, …)`. The body is a `ScrollView` (horizontal, and vertical under `lineLimit`) holding a `Text` per line with `textSelection(.enabled)`; the gutter is a separate, non-selectable column pinned beside it. The body's layout direction is forced to left-to-right in the environment (COD-20). The marks' labels are the line's accessibility label prefix. Automatic highlighting is not built on this platform yet; as specified, it is the same grammars, which are data, read by an interpreter written in Swift over `NSRegularExpression`, behind `TanreiCodeHighlighter` — a protocol the product may implement to bring its own — set once in the environment; `highlightsSyntax: Bool = true`. Until then this platform draws runs the product gives and code without runs plain, and says so in its README.	`TanreiCodeBlock(code, runs, variant, size, title, …)`. The body is a `SelectionContainer` over a `BasicText` in `horizontalScroll` (and `verticalScroll` under `maxLines`), inside `CompositionLocalProvider(LocalLayoutDirection provides Ltr)` (COD-20); the gutter is drawn beside it and cleared from semantics. The body is `focusable` only while its scroll state reports a range. Automatic highlighting is not built on this platform yet; as specified, it is the same grammars read by an interpreter written in Kotlin over `kotlin.text.Regex`, behind a `TanreiCodeHighlighter` interface provided by a `CompositionLocal`; the runs are computed off the main thread in a `produceState` keyed by the code and the language, which is this platform's form of COD-30's cancellation. Until then this platform draws runs the product gives and code without runs plain, and says so in its README.	`TanreiCodeBlock(code: …, runs: …, variant:, size:, title:, …)`. The body is a `SelectableText.rich` in a horizontal `SingleChildScrollView` with a `Scrollbar`, under `Directionality(textDirection: TextDirection.ltr)` (COD-20); the gutter is a column beside it wrapped in `ExcludeSemantics`. A `Focus` node on the body exists only while the scroll position has an extent. Automatic highlighting is not built on this platform yet; as specified, it is the same grammars read by an interpreter written in Dart over `RegExp`, behind a `TanreiCodeHighlighter` the theme carries; long code is read in an isolate. Until then this platform draws runs the product gives and code without runs plain, and says so in its README.	`<CodeBlock code="…" runs={…} title="sizes.js" />`. The body is a horizontal `ScrollView` holding `<Text selectable>` lines with `writingDirection: 'ltr'`; the gutter is a sibling column with `importantForAccessibility="no-hide-descendants"` and `accessibilityElementsHidden`. Copying goes through the Copy button (see its note on the clipboard module). Follows the app's direction where an ancestor's is not known. Automatic highlighting is not built on this platform yet; as specified, it is the highlighter module of the web package, which has no DOM, imported as it is; a `highlighter` prop of the provider replaces it. Until then this platform draws runs the product gives and code without runs plain, and says so in its README.

令牌

令牌	引用	解析值（浅色）
`--tanrei-comp-code-block-code-color`	`sys.color.on-surface`	#1b1b1b
`--tanrei-comp-code-block-code-tab-size`	—	2
`--tanrei-comp-code-block-container-padding-block-medium`	`sys.space.space150`	12px
`--tanrei-comp-code-block-container-padding-block-small`	`sys.space.space100`	8px
`--tanrei-comp-code-block-container-padding-inline-medium`	`sys.space.space200`	16px
`--tanrei-comp-code-block-container-padding-inline-small`	`sys.space.space150`	12px
`--tanrei-comp-code-block-container-shape`	`sys.shape.corner.small`	6px
`--tanrei-comp-code-block-copy-button-inset`	`sys.space.space75`	6px
`--tanrei-comp-code-block-filled-container-color`	`sys.color.surface-container`	#f6f6f6
`--tanrei-comp-code-block-header-gap`	`sys.space.space100`	8px
`--tanrei-comp-code-block-header-padding-block-end`	`sys.space.space50`	4px
`--tanrei-comp-code-block-language-color`	`sys.color.on-surface-variant`	#4b4b4b
`--tanrei-comp-code-block-line-number-color`	`sys.color.on-surface-variant`	#4b4b4b
`--tanrei-comp-code-block-line-number-gap`	`sys.space.space200`	16px
`--tanrei-comp-code-block-line-added-container-color`	`sys.color.success-container`	#e2f6df
`--tanrei-comp-code-block-line-added-mark-color`	`sys.color.success`	#077b32
`--tanrei-comp-code-block-line-highlighted-container-color`	`sys.color.surface-container-highest`	#eeeeee
`--tanrei-comp-code-block-line-highlighted-mark-color`	`sys.color.primary`	#1b1b1b
`--tanrei-comp-code-block-line-mark-width`	`sys.border.thick`	2px
`--tanrei-comp-code-block-line-removed-container-color`	`sys.color.error-container`	#ffedeb
`--tanrei-comp-code-block-line-removed-mark-color`	`sys.color.error`	#cd262f
`--tanrei-comp-code-block-outline-color`	`sys.color.outline-variant`	#000000 · 8%
`--tanrei-comp-code-block-outline-width`	`sys.border.hairline`	1px
`--tanrei-comp-code-block-outlined-container-color`	—	#000000 · 0%
`--tanrei-comp-code-block-prompt-color`	`sys.color.on-surface-variant`	#4b4b4b
`--tanrei-comp-code-block-syntax-color-comment`	`sys.color.on-surface-variant`	#4b4b4b
`--tanrei-comp-code-block-syntax-color-constant`	`sys.color.on-surface`	#944b00
`--tanrei-comp-code-block-syntax-color-function`	`sys.color.on-surface`	#005bbe
`--tanrei-comp-code-block-syntax-color-keyword`	`sys.color.on-surface`	#833cb3
`--tanrei-comp-code-block-syntax-color-property`	`sys.color.on-surface`	#0052ac
`--tanrei-comp-code-block-syntax-color-punctuation`	`sys.color.on-surface-variant`	#4b4b4b
`--tanrei-comp-code-block-syntax-color-string`	`sys.color.on-surface`	#206c24
`--tanrei-comp-code-block-syntax-color-tag`	`sys.color.on-surface`	#b02c34
`--tanrei-comp-code-block-syntax-color-type`	`sys.color.on-surface`	#00696c
`--tanrei-comp-code-block-syntax-emphasis-comment`	—	0
`--tanrei-comp-code-block-syntax-emphasis-constant`	—	0
`--tanrei-comp-code-block-syntax-emphasis-function`	—	0
`--tanrei-comp-code-block-syntax-emphasis-keyword`	`sys.typescale.emphasis.body`	100
`--tanrei-comp-code-block-syntax-emphasis-property`	—	0
`--tanrei-comp-code-block-syntax-emphasis-punctuation`	—	0
`--tanrei-comp-code-block-syntax-emphasis-string`	—	0
`--tanrei-comp-code-block-syntax-emphasis-tag`	—	0
`--tanrei-comp-code-block-syntax-emphasis-type`	—	0
`--tanrei-comp-code-block-syntax-max-length`	—	50000
`--tanrei-comp-code-block-title-color`	`sys.color.on-surface`	#1b1b1b
`--tanrei-comp-code-block-code-typescale-medium`	`sys.typescale.code`	400 13px/1.5385
`--tanrei-comp-code-block-code-typescale-small`	`sys.typescale.code-small`	400 12px/1.3333
`--tanrei-comp-code-block-language-typescale`	`sys.typescale.label-small`	500 12px/1.3333
`--tanrei-comp-code-block-title-typescale`	`sys.typescale.label-small`	500 12px/1.3333

测试样例

作为基准的渲染结果。所有平台都以相同的 ID 为每个样例截取快照，以便相互比较。

`variant: filled` (43)

plain

code: <tanrei-button variant="filled">Save</ta… label: Example

small

code: const sizes = ['small', 'medium', 'large… size: small label: Example

titled

code: const sizes = ['small', 'medium', 'large… title: sizes.js

titled-language-copy

code: const sizes = ['small', 'medium', 'large… title: sizes.js languageLabel: JavaScript copy: true copyLabel: Copy copiedLabel: Copied copyFailedLabel: Could not copy

language-only

code: <tanrei-button variant="filled">Save</ta… languageLabel: HTML label: Example

copy

code: const sizes = ['small', 'medium', 'large… label: Example copy: true copyLabel: Copy copiedLabel: Copied copyFailedLabel: Could not copy

one-line-copy

code: npm install @tanrei/web label: Install copy: true copyLabel: Copy copiedLabel: Copied copyFailedLabel: Could not copy

syntax

title: Footer.tsx languageLabel: TSX copy: true copyLabel: Copy copiedLabel: Copied copyFailedLabel: Could not copy items: 87

syntax-small

size: small label: A layer file items: 38

line-numbers

code: const sizes = ['small', 'medium', 'large… label: Example lineNumbers: true

line-numbers-start

code: const sizes = ['small', 'medium', 'large… title: sizes.js lineNumbers: true startLine: 96

highlighted-lines

code: const sizes = ['small', 'medium', 'large… label: Example lineNumbers: true highlightedLines: 1, 4-5 highlightedLabel: Highlighted

diff

code: const sizes = ['small', 'medium', 'large… title: sizes.js lineNumbers: true addedLines: 5-6 removedLines: 4 addedLabel: Added removedLabel: Removed copy: true copyLabel: Copy copiedLabel: Copied copyFailedLabel: Could not copy

diff-without-numbers

code: <tanrei-button variant="filled">Save</ta… label: Example addedLines: 2 removedLines: 1 addedLabel: Added removedLabel: Removed

syntax-marked

title: Footer.tsx lineNumbers: true highlightedLines: 5 addedLines: 9 highlightedLabel: Highlighted addedLabel: Added copy: true copyLabel: Copy copiedLabel: Copied copyFailedLabel: Could not copy items: 87

long-lines

code: export const footer = html`<footer class… label: Example

long-lines-copy

code: export const footer = html`<footer class… label: Example copy: true copyLabel: Copy copiedLabel: Copied copyFailedLabel: Could not copy

long-lines-wrapped

code: export const footer = html`<footer class… label: Example wrap: true

long-lines-wrapped-numbered-copy

code: export const footer = html`<footer class… label: Example wrap: true lineNumbers: true highlightedLines: 1 highlightedLabel: Highlighted copy: true copyLabel: Copy copiedLabel: Copied copyFailedLabel: Could not copy

max-lines

code: 01:00 tide high, gauge 1.55 m
02:00 tide…

title: tide.log lineNumbers: true maxLines: 5 copy: true copyLabel: Copy copiedLabel: Copied copyFailedLabel: Could not copy

terminal

code: npm install @tanrei/web
npx tanrei studi…

languageLabel: Shell prompt: $ copy: true copyLabel: Copy copiedLabel: Copied copyFailedLabel: Could not copy

terminal-one-line

code: flutter pub add tanrei label: Install prompt: $ copy: true copyLabel: Copy copiedLabel: Copied copyFailedLabel: Could not copy

tabs

code: build:
	node scripts/build.js

test: bui…

title: Makefile

japanese-comment

label: 例 items: 8

rtl

code: const sizes = ['small', 'medium', 'large… title: مثال languageLabel: JavaScript lineNumbers: true highlightedLines: 3 highlightedLabel: مميز copy: true copyLabel: نسخ copiedLabel: تم النسخ copyFailedLabel: تعذر النسخ direction: rtl

rtl-copy-without-header

code: export const footer = html`<footer class… label: مثال copy: true copyLabel: نسخ copiedLabel: تم النسخ copyFailedLabel: تعذر النسخ direction: rtl

rtl-ltr-title

code: <tanrei-button variant="filled">Save</ta… title: packages/web/src/components/button/butto… copy: true copyLabel: Copy copiedLabel: Copied copyFailedLabel: Could not copy direction: rtl

auto-tsx

code: // A form's footer: one main action, one… title: Footer.tsx language: tsx languageLabel: TSX copy: true copyLabel: Copy copiedLabel: Copied copyFailedLabel: Could not copy

auto-html

code: <!-- One main action, one way out -->
<f…

language: html label: Example

auto-css

code: /* The footer of a form */
@media (min-w…

language: css label: Example

auto-javascript

code: const sizes = ['small', 'medium', 'large… language: js label: Example

auto-json

code: {
  "name": "acme",
  "extends": "tanrei…

language: json label: Example

auto-shell

code: # Install and build
pnpm add @tanrei/web…

language: sh label: Example prompt: $

auto-swift

code: import SwiftUI

/// A form's footer.
str…

language: swift label: Example

auto-kotlin

code: @Composable
fun Footer(busy: Boolean, on…

language: kotlin label: Example

auto-dart

code: class Footer extends StatelessWidget {… language: dart label: Example

auto-small

code: {
  "name": "acme",
  "extends": "tanrei…

size: small language: json label: Example

auto-highlighted-lines

code: const sizes = ['small', 'medium', 'large… language: js label: Example lineNumbers: true highlightedLines: 4-5 highlightedLabel: Highlighted

auto-marked

code: const sizes = ['small', 'medium', 'large… language: js label: Example lineNumbers: true addedLines: 3 removedLines: 2 addedLabel: Added removedLabel: Removed copy: true copyLabel: Copy copiedLabel: Copied copyFailedLabel: Could not copy

auto-japanese-comment

code: // 保存ボタンは 1 画面に 1 つだけ置く。
const label = '…

language: js label: 例

auto-off

code: // A form's footer: one main action, one… language: tsx highlight: false label: Example

auto-text

code: Tanrei 0.1.0
  5 platforms, 36 component…

language: text label: Example

auto-unknown-language

code: IDENTIFICATION DIVISION.
PROGRAM-ID. HEL…

language: cobol label: Example

`variant: outlined` (5)

outlined

code: <tanrei-button variant="filled">Save</ta… variant: outlined label: Example

small-outlined-titled

code: const sizes = ['small', 'medium', 'large… variant: outlined size: small title: sizes.js languageLabel: JavaScript copy: true copyLabel: Copy copiedLabel: Copied copyFailedLabel: Could not copy

syntax-outlined

variant: outlined label: A layer file items: 38

highlighted-outlined

code: const sizes = ['small', 'medium', 'large… variant: outlined label: Example highlightedLines: 3 highlightedLabel: Highlighted

auto-outlined

code: // A form's footer: one main action, one… variant: outlined language: tsx label: Example

生成自 specs/code-block.spec.json, tokens/comp/code-block.tokens.json, design/tokens/

语法高亮

颜色有三个来源，按以下顺序取用。

你提供的片段。 在生成页面时已经高亮的代码，或者由你选定的语法高亮器高亮的代码。它们按原样绘制；无论 language 和 highlight 是什么，代码块都不会再次高亮这段代码。
代码块自己的语法高亮器：highlight 为 true，language 指的是它认识的语言，并且代码长度不超过 comp.code-block.syntax.max-length（50,000 个字符）时使用。
普通文本：其他所有情况。

代码会立即以普通文本绘制。颜色稍后在同一帧里一次到位，不会移动任何东西。代码发生变化时会重新读取；在末尾不断增长的代码，保留已有的颜色。

`language`	结果
`html`、`xml`、`svg`、`css`、`javascript`（`js`、`mjs`、`cjs`、`jsx`）、`typescript`（`ts`、`tsx`）、`json`（`jsonc`）、`shell`（`sh`、`bash`、`zsh`）、`swift`、`kotlin`（`kt`）、`dart`	高亮。不区分大小写。
空、`text`、`plain`、`plaintext`	普通文本。不报告任何内容。
其他任何值	普通文本。调试构建会报告一次这个未知的语言。

代码块绝不猜测语言：不根据代码，不根据 headline，也不根据 language-label。简短的代码有歧义，猜错了就会给代码上错颜色。

关闭高亮。 highlight="false" 为单个代码块关闭它自己的语法高亮器。你提供的片段仍然会绘制。

长度上限。 长度超过 comp.code-block.syntax.max-length 的代码整段以普通文本绘制，绝不只高亮一半。设计系统可以更改这个值。

有新增和删除的行时，代码块把代码读作它包含的两段文本：更改之后的代码决定未删除各行的颜色，更改之前的代码决定已删除各行的颜色。一个开启了字符串的已删除行，不会让后面的内容上错颜色。

失败时不声张。 语法高亮器无法加载、抛出异常，或者它的片段拼接起来与代码不完全一致时，代码保持普通文本。页眉、复制按钮、行和标记照常工作。

这些文法是有意做小的。它们用于展示代码，而不是编辑代码。在语言本身难以解析的地方，它们可能把某个片段的颜色上错，但绝不会丢掉任何一个字符。

在生成页面时高亮

在构建阶段生成页面的网站，可以在构建时高亮。这样颜色在首次绘制时就已经在那里，浏览器也不用加载语法高亮器。highlightToHtml 就是元素使用的那个函数，它可以在 Node 中运行。

import { highlightToHtml } from '@tanrei/web/highlight';

const html = await highlightToHtml(source, 'tsx');
// <tanrei-code-block language="tsx"><pre><code data-syntax-of="tsx">${html}</code></pre></tanrei-code-block>

<code> 上的 data-syntax-of 说明这段代码已经高亮过。元素按原样绘制它，不导入任何东西。

使用你自己的语法高亮器

@tanrei/web/highlight 是一个独立的模块，没有任何依赖。元素在某个代码块第一次需要它时导入它，并在某种语言第一次被用到时导入该语言的文法。

导出	作用
`highlight(code, language)`	返回片段；语言不认识时返回 `null`。某种语言第一次使用时返回 Promise，之后返回值。
`highlightToHtml(code, language, { lines })`	返回 `<code>` 的内部 HTML。带 `lines` 时，每行一个 `<span data-line>`。
`registerLanguage(names, grammar)`	添加一种语言，或替换一种语言。文法是数据：若干具名的状态，每个状态是一组规则，每条规则有一个模式、一个角色，以及要进入或离开的状态。它也可以是一个导入文法的函数。
`loadLanguage(language)`	赶在该语言的第一段代码出现之前加载文法。
`setHighlighter(fn)`	整个替换语法高亮器。传入 `null` 会为整个页面关闭自动高亮。
`languages()`	返回各种语言可用的全部名称。
`foldScope(scopes, text)`	按下面的表格，返回带点号的作用域名称所对应的角色。
`tokenize(grammar, code)`、`checkGrammar(grammar)`	用于测试你编写的文法。

已经有一个信得过的语法高亮器的产品，也可以把 TanreiCodeBlock.highlighter 设为一个函数 (code, language, signal) => runs。这样代码块会去问这个函数，Tanrei 的模块则不会加载。

语法角色

角色（`data-syntax`）	它是什么	在默认系统中
`comment`	注释、文档注释	比代码更低调
`keyword`	语言自身的词：关键字、修饰符、at 规则、注解、写成单词的运算符	紫色，加重一档字重
`string`	写在代码里的文本：字符串、字符、正则表达式、标记语言中属性（attribute）的值	绿色
`constant`	不是文本的值：数字、布尔值、null、具名常量、单位、颜色值、转义序列	橙色
`function`	函数或方法的名称，无论是声明还是调用	蓝色
`type`	类型的名称：类、结构体、接口、内置类型、命名空间	蓝绿色
`tag`	标记语言和样式表所指向的对象：元素的名称、标记中组件的名称、选择器	红色
`property`	属于某样东西的名称：属性（property）、键、标记语言的属性（attribute）、样式属性、命令的选项	蓝色，色调更接近代码的颜色
`punctuation`	括号、分隔符、标记语言的定界符	比代码更低调
普通（没有 span）	其他任何内容：变量、参数、写成符号的运算符、标签之间的文本	代码的颜色

每个角色有两个令牌：一个颜色（comp.code-block.syntax.color.*）和一个字重档位（comp.code-block.syntax.emphasis.*）。这些角色是一条令牌轴，所以设计系统可以添加新的角色。默认系统的绿色和红色来自语法专用的调色板，色相与成功色和错误色相近。新增的行和删除的行靠竖条、符号和标签来分辨，绝不只靠颜色。角色只改变颜色和字重，所以高亮的代码和普通代码有相同的行和列。

片段是 <code> 里的一个 <span data-syntax="…">。span 之外的文本是普通文本。

你提供的片段按原样绘制

{
  "name": "acme",
  "dials": { "size.unit": 4 },
  "compact": false
}

把语法高亮器的作用域归并到角色

有些语法高亮器用带点号的作用域（scope）名称来命名找到的东西，这些名称出自同一套通用词汇。foldScope 把它们归并到这些角色，让你的语法高亮器和 Tanrei 的语法高亮器给出相同的颜色。一个词法单元的各个作用域，从最具体的开始向外依次尝试。在同一个作用域内，第一个匹配的行生效。不匹配任何一行的作用域会被跳过，什么都没匹配到的词法单元是普通文本。

#	作用域的开头	角色
1	`comment`、`punctuation.definition.comment`	`comment`
2	`constant.character.escape`、`constant.numeric`、`constant.language`、`constant.other`、`keyword.other.unit`、`support.constant`、`variable.other.constant`、`variable.other.enummember`	`constant`
3	`string`、`punctuation.definition.string`、`markup.inline.raw`、`markup.raw`	`string`
4	`entity.name.tag`、`support.class.component`、`meta.selector`，以及样式表中的 `entity.other.attribute-name`	`tag`
5	`entity.other.attribute-name`、`support.type.property-name`、`meta.property-name`、`meta.object-literal.key`、`variable.other.property`、`variable.other.object.property`、`support.type.vendored.property-name`、`variable.parameter.option`	`property`
6	`entity.name.function`、`support.function`、`variable.function`、`meta.function-call.generic`	`function`
7	`entity.name.type`、`entity.name.class`、`entity.name.namespace`、`entity.other.inherited-class`、`support.type`、`support.class`、`storage.type.primitive`、`storage.type.built-in`、`keyword.type`	`type`
8	文本由字母组成的 `keyword.operator`（`new`、`typeof`、`in`）	`keyword`
9	其余的 `keyword.operator`	普通
10	`keyword`、`storage`、`variable.language`、`meta.decorator`、`punctuation.decorator`、`entity.name.function.decorator`、`markup.heading`	`keyword`
11	`punctuation`、`meta.brace`、`meta.delimiter`	`punctuation`
12	`variable`、`meta`、`source`、`text`、`markup`、`invalid`	普通

字符串的引号是字符串的一部分。字符串里的转义序列是常量。
JSON 的键是属性，它们的值是字符串和常量。
装饰器的名称是关键字。
invalid 是普通文本。显示代码的组件不评判代码。
新增和删除是行的属性（added-lines、removed-lines），不是片段的属性。

Web 上绘制方式的不同之处

元素把每一行包进 <span data-line>，给它一个框。它会移动你的节点，在换行处拆开文本和片段，但不给代码添加任何字符。如果框架拥有 <code> 的子节点，就应该改为传入 code，或者自己渲染 [data-line]。
带标记的行的标签是该行代码之前的一个隐藏 <span>。它是 <code> 的 textContent 的一部分，但不在复制的内容之内。
outlined 外观画在它所处的任何背景上。如果那不是表面颜色，请在 --tanrei-code-block-ground 里指明，这样代码从行号和复制按钮下面滚过时，它们才有底色可依。
在元素定义之前，code.css 绘制填充、圆角、内边距和片段的颜色。页眉、复制按钮、行号和标记需要元素。
highlight 默认为 true，所以它的属性（attribute）是为了关闭它才写的：highlight="false"。属性（property）接受布尔值。
元素把它自己的片段作为 span 逐行写进你的 <code>，并把它们标记为自己写的。如果框架拥有 <code> 的子节点，就应该传入 code，让元素来写。
长度上限读取自自定义属性 --tanrei-comp-code-block-syntax-max-length，取层叠最终给到这个代码块的值。
使用单文件包的页面，语法高亮器已经包含在其中。以模块形式导入 @tanrei/web 的页面，则按需加载它。

指南

避免

不要用代码块表示句子里的一个名称。请使用行内代码。
不要指望靠语法颜色来说明什么。同样的代码以普通文本绘制时，必须表达同样的意思。
不要把命令和它们的输出混在同一个提示符下。每个非空行都会得到提示符。请用两个代码块。

无障碍

角色: group
标注: The block is a group named by title, or by label where it has no title; inside it the code is text with the role of code where the platform has one. The copy button is named by copyLabel. Line numbers, prompts, signs and bars are hidden; a marked line is preceded by its label in words (highlightedLabel, addedLabel, removedLabel).
最小目标: 即使外观尺寸更小，点击区域也满足最小目标尺寸。 minimum 32px · pointer 44px · spacing 8px · touch 48px

键盘操作

按键	动作
`Tab`	Moves focus to the copy button where there is one, then to the body while it can scroll. A block that neither scrolls nor copies is not a stop.
`Arrow keys, Page Up, Page Down, Home, End`	Scroll the focused body, as the platform scrolls any region.
`Enter` / `Space`	On the copy button: copies the code (CPY-2).

备注

The only target is the copy button, whose hit area meets the minimum target by its own spec (CPY-1, BTN-5) though it is drawn 32 high. The body is scrolled, not pressed.
A body that scrolls must be reachable by keyboard (WCAG 2.1.1) and so is a focus stop with a visible focus indicator (COD-7); one that does not scroll is not, so a page of short examples adds no stops. A group, not a landmark: a page may hold hundreds of blocks.
Reflow (WCAG 1.4.10): code is two-dimensional content, so sideways scrolling inside the block is allowed, and the page itself never scrolls sideways (COD-4, COD-24). wrap is for a product that prefers no sideways scrolling at all.
A marked line is never marked by color alone (WCAG 1.4.1): a highlighted line has a bar and a band and its label; an added or a removed line has a bar, a plus or a minus and its label (COD-15, COD-16). Syntax colors carry no meaning a reader needs: the same code drawn plain says the same thing, a role is never exposed (COD-22), and keywords are also told by weight. With a red-green color vision deficiency some of the default system's six hues draw together — the green of a string and the red of a tag's name first — beside the neutral tones and the keyword's weight; nothing is lost but a distinction between kinds of words.
Contrast: the code, the line numbers, the prompt and the signs are roles the token invariants hold at 4.5:1 on every surface (7:1 in the high-contrast schemes). Every syntax color is held by the build at the same ratios against the block's fill, against the band of a highlighted line and against every surface role, which is what an outlined block may stand on, in each system. The bars are primary, success and error, held at the same ratios, above the 3:1 a mark needs. The outlined look's edge is decorative.
An outlined block is read on whatever it is placed on. On a surface that is correct. On a colored container (a callout) the syntax colors are not paired with that container: use filled there, which brings its own surface.
The copy button is always drawn (COD-9): one that appears only under a pointer cannot be found by touch, and one that appears on focus moves under a keyboard user. Its confirmation is announced by the Copy button's own live region (CPY-5).
Highlighting adds nothing for assistive technology and takes nothing away: the code is the same text before and after the colors arrive, no live region speaks of them, and the body's scroll position, the selection and the focus are kept (COD-28). Colors arrive in one frame, without a motion, so nothing flashes more than once.
Screen readers read code as text, symbol by symbol as the person's settings say. The code block adds no line numbers or roles to that reading; the marks' labels are the only words it adds.
Code is not translated and not spell-checked (COD-2); comments in it are the author's language and are read with the page's voice unless the product marks their language.

生成自 specs/code-block.spec.json, tokens/sys/measure.tokens.json

组件负责的部分

代码是 code 元素，位于一个由 headline 或 label 命名的组里。
可以滚动的主体是焦点顺序中的一个停靠点，排在复制按钮之后，用方向键滚动。放得下的主体不是停靠点，所以满是简短示例的页面不会增加任何停靠点。
行号、符号、竖条和提示符对辅助技术隐藏。带标记的行之前有用文字写出的标签。
在 320 宽和两倍文本大小下，页面都绝不会因为代码块而横向滚动。
在强制颜色模式下，每种外观都会多出一道边线，所有代码都是文本颜色，竖条和符号保留。
高亮不会给辅助技术增加任何东西。不暴露任何角色，颜色到位时也不朗读。选区、焦点和滚动位置都保持不变。
对于红绿色觉异常的人，六种色相中有几种看起来会彼此接近，首先是字符串的绿色和标签（tag）名称的红色。关键字还可以靠字重来分辨。

需要你做的事

使用 copy 时，请提供 copy-label、copied-label 和 copy-failed-label，以及你用到的每种标记的标签，都用你的产品的语言来写。
在代码块周围的文字里说明高亮的行展示了什么。标签只说明它被高亮了。

GitHub 上的源码与 Issue

概览

用法

规格

构成

属性

事件

条目

run

状态

行为