组件 · 数据展示

CodeBlock

Several lines of code or a log on a framed code surface, with an optional header for the file name and a copy action.

稳定

import { CodeBlock } from "@botiverse/raft-ui";

本页尚未翻译

译文完成之前，这里显示英文原文。阅读英文版

Several lines of code or a log, on a framed code surface that scrolls sideways instead of wrapping. An optional header names the file and holds actions such as Copy. You render the code inside, plain or highlighted.

code-block/compositions/shiki

When to use

Situation	Use
Several lines of code, or a log	CodeBlock
One command people copy and run	CopyableCode
A name from code inside a sentence	InlineCode
A diagram or a Markdown table	The same container (Built from existing parts)

Anatomy

CodeBlock: the frame. Required.
CodeBlockHeader: the optional top bar, with a hairline under it.
- CodeBlockTitle: the file name, in Space Mono.
- CodeBlockActions: the actions at its right end.
CodeBlockBody: the code panel. Render the code in a CodeBlockPre with its code inside it. Required.
CodeBlockPre: the code's pre, keyboard-reachable while it scrolls (Accessibility).
CodeBlockAction: a 32px icon button with radius-chip, like every control embedded in a frame. You provide its icon and what it does.

Variants

Variant	Use for
With a header	Code from a file: the header names it
Without a header	A snippet or a log without a file name; `CodeBlockActions` placed inside the body takes its own column at its top right
Highlighted	Code in a known language, highlighted with Shiki
Plain	Logs and text without a language

code-block/compositions/plain

code-block/compositions/without-header

code-block/compositions/animated-copy

Behavior

Long lines scroll sideways inside the body. The code doesn't wrap.
After a copy, the copy icon turns into a check, then back after a moment, as in CopyableCode.

Content

Put the file name in the title, with its extension: raft.config.ts.
Leave the header out when there is no file name.

Accessibility

Give every CodeBlockAction an aria-label, such as "Copy code": it is icon-only.
Announce a completed copy, for example with aria-live on the button, so the change of icon isn't the only signal.
Keep the code in pre and code, so it is read as code and keeps its whitespace.
Render the code in CodeBlockPre. A long line scrolls inside it, and while it does it is a region the keyboard can reach (tabindex="0", role="region"), named by its aria-label ("Code" by default; name it after the language, "ts code"): Safari doesn't let the keyboard reach a scroller that can't take focus, and a pre with no role can't carry a name. Code that fits adds no Tab stop. It shows the inset ink ring on keyboard focus.

Rules

Set code in Space Mono, text-mono-code.
Put the block on layer-code, with a line-hairline border and radius-container.
Put the actions 6px from the block's corner, 4px apart. Without a header they sit in a column of their own beside the code, as wide as the actions, so no line runs under them however many there are, and the block is at least tall enough to keep 6px under them. In a header they are centred in its 40px and 6px from its end (Shape).

API

CodeBlock, CodeBlockAction, CodeBlockActions, CodeBlockBody, CodeBlockHeader, CodeBlockPre, CodeBlockTitle

Framed code surface. Compose a header and a body inside it.

Prop	类型	默认值
renderAllows you to replace the component's HTML element with a different tag, or compose it with another component.	ReactElement \| ((props, state) => ReactElement)

Also takes the attributes of its element.

改动

0.2.0 · AddedAdded stable CodeBlock* and semantic Markdown* compound primitives.