Typography 排版
在 JSX 里写的文字(标题、正文、链接、引用、列表、键帽)都用排版组件,这样它们会遵循字号体系和主题。运行时拿到的 Markdown 请用 Markdown 渲染,它用的就是这些组件;要把长文字截成一行或几行,请用 Ellipsis。
ListItem 要放在 List 里:它渲染成 li。
排版组件按全局字号体系排出正文和标签:标题、行内文字、段落、链接、引用、列表、分割线、键帽和小节标签。它们的字号、颜色和间距都来自主题 token,所以用它们写出的文字放在哪里、在浅色和深色模式下看起来都一致。
import {
Blockquote,
Eyebrow,
Heading,
Kbd,
Link,
List,
ListItem,
Paragraph,
Separator,
Text,
} from "@pika-lab/react";块级组件(Heading、Paragraph、Blockquote、List、Separator)自带上下外边距,位于容器开头和结尾时去掉对应的那一侧。行内组件(Text、Link、Kbd、Eyebrow)没有外边距。
#Heading 标题
Heading 渲染一个章节标题,h1 到 h6。大小只由 level 决定,取自全局字号体系,并且自带上下间距。
#基础用法
level 决定元素和大小:h1 24px、h2 20px、h3 18px、h4 到 h6 16px。默认是 2。
Release notes
Version 2.4
New components
Heading
Props
Accessibility
#前缀色条
prefix="bar" 在文字前画一条色条。type 决定色条颜色:default、primary、info、success、warning 或 error。文字始终是主文字色。
default
primary
info
success
warning
error
#文字对齐
加上 alignText 后,色条移到左侧留白里,标题文字和下面的正文左对齐。
Without alignText
The bar pushes the heading text right of the body text.
With alignText
The bar sits in the gutter and the text lines up with this paragraph.
#间距
标题上下都有外边距,h1 到 h3 的下边距更大。容器里的第一个子元素去掉上边距,最后一个去掉下边距。
Install
Add the package and import its styles once at the root of the app.
Peer dependencies
React 19 or later. Nothing else is required.
Fonts
Pika names font families but never loads font files.
#锚点
id 等属性会传给标题元素,链接可以直接指向它。
Usage #
Copy the link next to the heading to share this section.
#属性
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
level | 1 | 2 | 3 | 4 | 5 | 6 | 2 | 渲染 h1 到 h6,同时决定大小。 | 未发布 |
prefix | bar | undefined | bar 在文字前画一条色条。 | 未发布 |
type | default | primary | info | success | warning | error | default | 色条的颜色。 | 未发布 |
alignText | boolean | false | 配合 prefix="bar",把色条移到左侧留白里,文字和正文对齐。 | 未发布 |
其余 h1 属性(id、className、aria-*、ref 等)都会传给标题元素。
用 level 选择标题级别。字号跟随 Pika 的字号体系,所以 h1 是 24px;首页大标题这类展示字号请自己设置。
#Text 文本
Text 用正文字号(--p-font-size-4 / --p-line-height-4)渲染一段文字。它总是自己设置颜色:没有 type 或 depth 时就是主文字色,放在哪里看起来都一样。没有 size 属性。
#类型
type 选择颜色角色:default、primary、info、success、warning 或 error。
#层级
depth 把默认颜色降为次要、第三级文字色。只在 type 为 default 时生效。
#加粗、斜体、下划线、删除线
delete 用 <del> 包住内容,读屏软件会读出这是被删除的内容。
#代码
code 把内容渲染成 <code> 行内代码。它保留 type 和 depth 的颜色,也可以和 delete 一起用。
pnpm check before you open a pull request.useLegacyTheme was removed; the call now fails with ERR_THEME.#元素
as 从一组固定的文本元素里选择要渲染的元素。元素的语义保留,字号和颜色由 Text 决定。
A paragraph rendered by Text.
Emphasis keeps its meaning for screen readers.Small print, still in the body size.#属性
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
as | TextElement | span | 要渲染的元素:span、div、p、label、strong、em、b、i、small、time、abbr、cite、q、mark、sub、sup、dfn、legend、figcaption、dt 或 dd。 | 未发布 |
code | boolean | false | 渲染成行内代码。 | 未发布 |
delete | boolean | false | 用 <del> 加删除线。 | 未发布 |
depth | 1 | 2 | 3 | undefined | 主要、次要或第三级文字色。仅在 type="default" 时生效。 | 未发布 |
italic | boolean | false | 斜体。 | 未发布 |
strong | boolean | false | 使用主题的加粗字重。 | 未发布 |
type | default | primary | info | success | warning | error | default | 颜色角色。 | 未发布 |
underline | boolean | false | 下划线。 | 未发布 |
其余属性(包括 ref)都传给根元素,根元素始终是 as 指定的元素。<code> 或 <del> 放在根元素里面,所以 as 和 ref 的类型总是一致。
#Paragraph 段落
Paragraph 渲染一个正文 <p>:字号用正文字号(字号体系第 4 档),行高用长文行高 --p-line-height-prose(1.6),而不是密集界面文字用的固定 20px 行高。
#基础用法
段落上下各留 16px。容器里的第一个段落去掉上间距,最后一个去掉下间距。
A paragraph is a block of prose. It uses the body font size with a roomy line height, so longer passages stay easy to read.
Paragraphs keep 16px of space above and below. The first one in its container drops the space above and the last one drops the space below, so a group of paragraphs sits flush with whatever wraps it.
#深度
depth 决定文字的强调程度:1 是主文字色,也是默认值;2、3 依次更淡。
Depth 1: the primary text color, used by default.
Depth 2: secondary text, for supporting detail.
Depth 3: tertiary text, for hints and fine print.
#属性
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
depth | 1 | 2 | 3 | 1 | 文字强调程度:主要、次要或第三级文字色。 | 未发布 |
其他属性(包括 ref)都传给 <p>。不传 depth 时用主文字色。
#Link 链接
Link 是文字里的行内链接。它沿用周围文字的字体和字号,颜色由 type 决定,下划线交给主题。
#基础用法
链接是句子的一部分:只有颜色和下划线不同。
Every component reads its colors from the color roles, and text sizes come from the typography scale, so a link takes the size of the sentence around it.
#类型
primary 是品牌链接色。neutral 是安静的灰色链接,用在元信息、页脚这类彩色链接太跳的地方。
#下划线
auto 只在悬停时显示下划线。hover、always、none 明确指定下划线。
#划线
variant 像读书 App 里的划线那样标出链接:marker 是马克笔,在文字下三分之一铺一道浅色、边缘柔和的色带(悬停时铺满);wave 和 line 在文字下画波浪线或直线。color 可选黄(默认)、蓝、绿、粉。划线后的文字用正文墨色(marker 会略带色带的色调),链接折行时每一行都有标记。
marker yellow · marker blue · marker green · marker pink
wave yellow · wave blue · wave green · wave pink
line yellow · line blue · line green · line pink
A marked link that wraps keeps its mark on every line: the color system explains how the jade seed turns into every role in the library.
#外部链接
target="_blank" 会自动加上 rel="noopener noreferrer",rel 里传入的值会保留。
#路由链接
as 用另一个组件代替 <a> 渲染,比如路由库的链接组件。Link 接受该组件的 props(这里是 to),并把类名、rel 和 ref 传下去,所以这个组件需要渲染一个接收它们的 <a>。若希望整棵应用里的站内 <Link href="/…">(包括 Markdown 渲染出的站内链接)默认走路由组件,可在 ConfigProvider 上配置 componentOptions={{ Link: { as: RouterLink } }};外部或协议链接(https:、mailto:、//…)、页内 #hash、download 以及 target="_blank" 会自动回退为原生 <a>。
Read the getting started guide first.
#属性
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
as | ElementType | 'a' | 渲染的元素或组件,例如路由库的 Link。 | 未发布 |
type | primary | neutral | primary | 颜色角色。 | 未发布 |
underline | auto | hover | always | none | auto | 下划线何时显示;auto 跟随主题。 | 未发布 |
variant | plain | marker | wave | line | plain | 链接的标记方式,见「划线」。 | 未发布 |
color | yellow | blue | green | pink | yellow | variant 不是 plain 时标记的颜色。 | 未发布 |
其余 props 传给渲染出的元素。type 是颜色角色,所以 <a> 自身的 type 属性不可用。可以用 ConfigProvider 的 componentOptions={{ Link: { … } }} 为一棵子树设置 as、type、underline、variant 和 color 的默认值。
访问过的链接保持原来的颜色。
#Blockquote 引用
Blockquote 渲染一个 <blockquote>,左侧带一条竖条,文字用次要文字色。和其他排版组件一样,它自带上下外边距,位于容器开头和结尾时去掉对应的那一侧。
#基础用法
cite 和其他原生属性会直接传给 <blockquote>。
Cool URIs don't change.
#段落
引用里的段落间距比正文更紧,第一段和最后一段去掉外侧边距,让竖条和文字等高。
Make each program do one thing well.
Expect the output of every program to become the input to another, as yet unknown, program.
#文字对齐
alignText 把竖条和它后面的间距挂到左侧留白里,让引用的文字和上下文对齐。
The release notes put it plainly:
Nothing in this release changes the public API.
So upgrading should be a no-op.
#嵌套
引用里再套一层引用,内层有自己的竖条。
Agreed, with one change:
Ship the token PR first, then the components on top of it.Components can go in parallel after that.
#属性
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
alignText | boolean | false | 把竖条挂到左侧留白里,让文字和上下文对齐。 | 未发布 |
其余 <blockquote> 属性(包括 cite 和 ref)都会透传。文字颜色固定为次要文字色。起始边是一条细的中性色竖条。
#List 列表
List 渲染长文里的列表:默认是 <ul>,ordered 时是 <ol>。每个 ListItem 是一个 <li>,在列表项里再放一个 List 就是嵌套列表。列表自带上下间距,在容器开头或结尾时去掉;第一项之后的每一项和上一项之间留一点距离。
这是排版用的列表。长消息流请用 VirtualList,它只渲染视口里的行。
#基础用法
默认是圆点,ordered 时是数字。标记用低调的三级文字色。
- Channels group conversations by topic
- Threads keep replies next to the message
- Agents can join any channel you invite them to
- Create a workspace
- Invite your team
- Add your first agent
#有序列表
start 设置起始编号,reversed 倒序编号,type 选择编号样式(1、a、A、i、I)。这三个属性都传给 <ol>,只在 ordered 时生效。
- Run the migrations
- Restart the workers
- Watch the error rate
- Bronze
- Silver
- Gold
- Draft
- Review
- Publish
#嵌套
ListItem 里的 List 就是子列表。嵌套的无序列表换成第二种圆点样式。
- Inbox
- Mentions
- Threads
- Following
- Muted
- Saved
- Set up the server
- Pick a region
- Add a domain
- Connect a machine
- Install the runtime
- Paste the token
#文字对齐
alignText 去掉缩进:标记挂在左侧留白里,列表项的文字和列表外的文字对齐。
Indented (default):
- Markers sit inside the text column
- Item text is indented by 2em
With alignText:
- Markers hang in the gutter
- Item text lines up with this paragraph
#任务列表
任务项去掉标记,由开头的复选框代替,就像 GFM 的任务列表(- [x] …)。第一个子元素是复选框(原生 <input type="checkbox"> 或 Checkbox)的列表项,在支持 :has() 的浏览器里会自动这样显示;task 则显式指定,复选框被包了一层时也有效。
#属性
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
ordered | boolean | false | 渲染 <ol> 而不是 <ul>。 | 未发布 |
start | number | undefined | 第一项的编号。只在 ordered 时生效。 | 未发布 |
reversed | boolean | undefined | 倒序编号。只在 ordered 时生效。 | 未发布 |
type | 1 | a | A | i | I | undefined | 编号样式。只在 ordered 时生效。 | 未发布 |
alignText | boolean | false | 标记挂到左侧留白里,列表项文字和周围文字对齐。 | 未发布 |
其他属性传给 <ul> / <ol>。
#ListItem 属性
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
task | boolean | false | 去掉标记,由开头的复选框代替。 | 未发布 |
其他属性(例如 value)传给 <li>。
#主题 token
| Token | 默认值 |
|---|---|
--p-list-font-size / --p-list-line-height | --p-font-size-4 / --p-line-height-4 |
--p-list-margin | 16px 0 |
--p-list-padding | 2em |
--p-list-item-margin | 0.25em 0 0 |
--p-list-bullet-type / --p-list-nested-bullet-type | disc / circle |
--p-list-marker-font-weight | regular |
--p-list-marker-color | initial(三级文字色) |
#Separator 分割线
Separator 在内容之间画一条线:块与块之间的横线、中间带文字的横线,或行内元素之间的短竖线。
#基础用法
没有 children 时渲染为 <hr>,上下留出间距。作为容器的第一个或最后一个子元素时,外侧的间距会去掉。
Release notes are written as each change lands.
Breaking changes are listed first, then fixes.
#文字
children 会作为文字放在线的中间。labelPlacement 可以把它放到 left、center 或 right。这段文字同时也是分割线给辅助技术的名称。
#虚线
#垂直
orientation="vertical" 渲染一条 1em 高的行内竖线,用来分隔行内元素。
#装饰性
decorative 表示这条线只是视觉上的:它会带上 role="none",并对辅助技术隐藏。带文字时,文字仍然可以作为普通文本被读到。
The card header already separates this section.
So the line below it is only visual.
#属性
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
children | ReactNode | undefined | 线中间的文字。vertical 时忽略。 | 未发布 |
dashed | boolean | false | 画成虚线。 | 未发布 |
decorative | boolean | false | 只是视觉上的线:不带 separator 角色。 | 未发布 |
labelPlacement | left | center | right | center | 文字在线上的位置。 | 未发布 |
orientation | horizontal | vertical | horizontal | 块级横线或行内竖线。 | 未发布 |
其余 props 传给根元素:<hr>、带文字时的 <div role="separator">,或垂直时的 <span role="separator">。
#Kbd 键盘按键
Kbd 用原生的 <kbd> 元素把键盘输入画成一个键帽。尺寸以 em 为单位,跟随所在的文字大小。
#基础用法
把按键名称放在里面。
Press Esc to close the dialog, or Enter to confirm.
#组合键
keys 为每个按键渲染一个键帽,中间用 separator(默认 +)连接。按照 HTML 规范对组合键的建议,这些键帽包在一个外层 <kbd> 里。
Open search with ⌘+K
Save as with Ctrl+Shift+S
Go to inbox with GthenI
#尺寸
medium 是周围文字的 0.875em,small 是 0.75em,所以在标题和说明文字里都能按比例缩放。
Medium ⌘+C and small ⌘+C
In larger text the keycaps grow with it ⌘+C
#修饰键符号
Kbd 不检测平台,也不做按键名称映射。直接写你想要的符号,并给符号加上 title,悬停时能看到按键名称。
#属性
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
children | ReactNode | undefined | 按键名称。设置了 keys 时忽略。 | 未发布 |
keys | readonly ReactNode[] | undefined | 渲染组合键:每一项一个键帽,外面包一层 <kbd>。 | 未发布 |
separator | ReactNode | "+" | 组合键中按键之间的内容。 | 未发布 |
size | small | medium | medium | 相对周围文字的大小:0.75em 或 0.875em。 | 未发布 |
Kbd 同样支持原生 kbd 属性和 ref;组合键时它们作用在外层元素上。
#Eyebrow 小节标签
Eyebrow 是放在一个区块上方或旁边的小标签:列表分组、面板里的一块、表单字段。它加粗、大写、字距最宽,颜色固定为次级文字色,所以不论放在哪里,小节标签看起来都一样。中文照常显示。
#基础用法
12px、strong 字重、最宽字距。颜色是组件自己设定的,不继承父元素。
#等宽
mono 切换成等宽的元信息样式,小一档到 11px,用于运行环境、版本号和计数。
#作为小节标题
当它是一个区块唯一的标题时,用 as="h2" 到 "h6" 渲染成标题元素,这样它会出现在文档大纲里。外观不变,浏览器给标题的默认外边距会被清掉。
Members
- Kate
- Kirby
- Wug
#表单标签
配合 as="label" 和 htmlFor,它就是表单控件的标签。
#前后内容
before 和 after 在标签旁放一个图标或计数。数字使用等宽数字。
#属性
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
as | span | div | label | h2 | h3 | h4 | h5 | h6 | span | 渲染的元素。div 和标题是块级,span 和 label 是行内。 | 未发布 |
htmlFor | string | undefined | 所属控件的 id,只在 as="label" 时生效。 | 未发布 |
mono | boolean | false | 用 11px 等宽字体代替 12px 无衬线字体。 | 未发布 |
before | ReactNode | undefined | 标签前的内容,比如图标。 | 未发布 |
after | ReactNode | undefined | 标签后的内容,比如计数。 | 未发布 |
children | ReactNode | undefined | 标签文字。 | 未发布 |
Eyebrow 也接受原生属性和 ref。它没有外边距,由周围的布局决定间距。before 里的装饰性图标应加上 aria-hidden。