链接
通向某个地方的文本：句子里的一个短语、单独的一行，或者只有一个字形。文本样式随所在位置而定，下划线按你的设计系统的选择绘制，离开本站的链接会带上标记。
- 类别
- 导航
- 令牌
comp.link- 层级
- 基础
- Web
tanrei-linkschedule - SwiftUI
TanreiLinkradio_button_unchecked - Jetpack Compose
TanreiLinkradio_button_unchecked - Flutter
TanreiLinkradio_button_unchecked - React Native
Linkradio_button_unchecked
生成自 docs/status/status.json, specs/link.spec.json
在句子里、单独一行、只有一个字形
有一条规则，产品不用查表就能照着做：有地址的是链接，没有地址的是按钮。 在页面上执行某件事、不通向任何地方的控件是按钮；如果它应该像文本一样低调，就用 text 变体。应该看起来像按钮的目的地，是带 href 的按钮。
在 Web 上，链接不是一个元素，而是加在你自己的锚元素（<a>）上的一个类。锚元素就在文档里，所以在任何脚本运行之前它就已经是链接，爬虫、搜索索引和处理页面上锚元素的路由都能找到它。路由自带的链接组件也可以加上这个类。.tanrei-prose 里的每个锚元素不加类也会以同样的方式绘制，所以渲染出来的 Markdown 什么都不用加。
SwiftUI、Compose、Flutter 和 React Native 尚在计划中：本页开头各平台旁边的名称是规格为它们定下的，这些平台目前还没有提供任何实现。React 也还没有 Link 组件，请使用加了这个类的锚元素。
<link rel="stylesheet" href="@tanrei/web/tokens.css" />
<link rel="stylesheet" href="@tanrei/web/icons.css" />
<link rel="stylesheet" href="@tanrei/web/link.css" />
<!-- 在句子里。 -->
<p>请先阅读<a class="tanrei-link" href="/guides/accessibility/">无障碍指南</a>。</p>
<!-- 单独一行：点击区域会扩展到最小目标。 -->
<a class="tanrei-link" data-standalone href="/getting-started/">开始使用</a>
<!-- 新标签页：标记会自动绘制。同时也要用文字说明。 -->
<a class="tanrei-link" href="https://example.com/" target="_blank" aria-description="在新标签页中打开">源代码</a>
<!-- 另一个网站，在用户当前所在的地方打开：标签之后有一个箭头，同时用文字说明。 -->
<a class="tanrei-link" href="https://example.com/" data-external="true" aria-description="外部链接">标准文档</a>
<!-- 带上那个网站的图标：由你自己的网站提供的图片，写成锚元素的第一个子元素。 -->
<a class="tanrei-link" href="https://example.com/" data-external="true" aria-description="外部链接"><img
class="tanrei-link-site-icon" src="/icons/example-com.png" alt="" width="32" height="32"
loading="lazy" decoding="async" referrerpolicy="no-referrer">标准文档</a>
<!-- 让一个链接不跟随设计系统的下划线选择：always、hover 或 never。 -->
<a class="tanrei-link" data-standalone data-underline="hover" href="/about/">关于</a>
<!-- 有自己选择的区域：里面的每个链接都跟随它。 -->
<footer style="--tanrei-comp-link-underline-visibility: never">…</footer>
<!-- 字形：紧贴文字书写，两者之间不留空格。 -->
<a class="tanrei-link" data-standalone href="/tokens.zip"><span class="tanrei-icon" aria-hidden="true">download</span>下载令牌</a>
<a class="tanrei-link" data-standalone data-icon-position="trailing" href="/tokens/">下一篇：令牌<span class="tanrei-icon" aria-hidden="true">arrow_forward</span></a>
<!-- 只有一个字形：用 aria-label 命名。 -->
<a class="tanrei-link" href="#installation" aria-label="指向“安装”的链接"><span class="tanrei-icon" aria-hidden="true">link</span></a>
<!-- 当前页面、此刻无法前往的链接，以及反色表面上的链接。 -->
<a class="tanrei-link" data-standalone href="/components/" aria-current="page">组件</a>
<a class="tanrei-link" data-standalone role="link" aria-disabled="true">上一页</a>
<a class="tanrei-link" data-variant="inverse" href="/changes/">更改内容</a>
<script type="module">
// 可选：涟漪和 dim 按下反馈、noopener、拒绝和调试报告。`@tanrei/web` 也会加载它。
// 页面生成时没有标记的地方，它还会标出离开本站的链接。
import { setSiteOrigins, setExternalLabel } from '@tanrei/web/link';
setSiteOrigins(['https://docs.example.com']); // 属于你自己网站的源
setExternalLabel('外部链接'); // 这段文字，整个页面设置一次，用你的语言
</script>import '@tanrei/web/link.css';
import '@tanrei/web/link';
import { Link as RouterLink } from 'react-router-dom';
<a className="tanrei-link" href="/guides/accessibility/">无障碍指南</a>
{/* 路由的链接组件会渲染它自己的锚元素：把这个类交给它。 */}
<RouterLink className="tanrei-link" data-standalone to="/getting-started/">开始使用</RouterLink>| 属性 | 在 Web 上 |
|---|---|
href |
href |
target: new |
target="_blank" |
targetLabel |
aria-description |
variant: inverse |
data-variant="inverse" |
standalone |
data-standalone |
iconPosition: trailing |
data-icon-position="trailing" |
current |
aria-current="page"（或它的其他取值） |
disabled |
role="link" aria-disabled="true"，并且不带 href |
label |
aria-label |
underline |
data-underline="always"、"hover" 或 "never"；不写时由设计系统的选择决定 |
external: on、off |
data-external="true"、data-external="false"；不写时由地址决定 |
externalLabel |
aria-description |
siteIcon |
你自己写的 <img class="tanrei-link-site-icon" alt="">，作为锚元素的第一个子元素 |
换行：下划线、状态层和焦点环跟随每一行
规格说明在反色表面上
页面已保存。查看更改内容。
链接不带自己的文本样式：无论在段落、标题、说明文字还是表格单元格里，它都沿用所在文本的字体族、字号、字重和行高。悬停、聚焦和按下画在它所经过的每一行的文字背后，不占空间，所以链接周围的任何东西都不会移动。字形、网站的图标和标记与文字一样大，并与旁边的词留在同一行。
下划线何时绘制是一种选择，有三个取值。always 在静止时和每一种状态下都绘制。hover 在链接被悬停、从键盘获得焦点或被按下时绘制。never 不绘制，这时悬停、聚焦和按下仍由状态层、标签颜色和焦点环来表示。这个选择在三个层级上设置：sys.behavior.link-underline 针对一个设计系统的所有文本链接，comp.link.underline.visibility 只针对链接这一个组件，underline 属性针对单个链接。默认系统选择 always。在 Web 上，这个组件令牌是一个自定义属性，所以页脚这样的区域可以带有自己的取值。当前链接和只有一个字形的链接在任何选择下都没有下划线；强制颜色模式下，无论哪种选择都会绘制下划线。
离开本站的链接会说明这一点。 外部链接在标签之后显示字形 arrow_outward；如果你给出了图标，还会在标签之前显示那个网站的图标。external 的取值是 auto、on 或 off。在 auto 下，与页面不同源（origin）的 http 或 https 地址是外部链接；路径、片段、邮件地址、电话号码和下载从来不是。把属于你自己网站的其他源声明一次，它们也就不算外部链接。comp.link.external.marks 为整个产品关掉图标（arrow），或者把两种标记都关掉（none）。
离开本站和在新标签页中打开是两件事。标签之后的位置只放一个字形：带 target="_blank" 的链接放 open_in_new，无论它是不是外部链接；除此之外，外部链接放 arrow_outward。后置一侧放着你自己的字形时，它会取代这两者；只有一个字形的链接则两者都没有。
链接从不自己去取图标。 siteIcon 是你给出的图片：它由你自己的网站提供，在构建网站时生成。如果组件向目的地或某个图标服务去要这个图标，就等于告诉对方每位读者正在看哪个页面。没有给出图标时，链接只显示箭头。加载不出来的图标会保留它的位置，什么都不画。
构成
| 部件 | 说明 |
|---|---|
1 container | The shape behind the link's text, on each line the link runs over. It has no fill at rest and takes no room in the layout: it is where hover, focus and press are drawn. |
2 label · 可选 | The link's text, in the text style of the text it sits in. It wraps with that text and is never cut. |
3 underline | The line under the label, in the label's color. When it is drawn is a choice (LNK-27): at rest and in every state, only while the link is pointed at, focused from the keyboard or pressed, or never. In the default system it is drawn at rest, where it is what tells a link from the text beside it. The current link and a link that is a glyph alone have none. |
4 icon · 可选 | A glyph of the system's icon set that the product names, before or after the label, or alone (a heading's anchor). Decorative beside a label; alone, the link is named by label. |
5 site-icon · 可选 | A small picture of the site an external link leads to, before the label. The product gives it; the link never fetches one by itself (LNK-32, LNK-35). Decoration: the label names the link. |
6 mark · 可选 | The one glyph after the label that says where following the link takes the person: open_in_new for a link that opens a new context, arrow_outward for a link that leaves the site and opens where the person is (LNK-31). Never both. Drawn by the link where the product has put no glyph of its own there. |
7 focus-ring | The indicator shown for keyboard focus, around the link's part of each line it runs over. |
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
href | string | "" | The destination: an address as the platform's links take one (a URL; on the web a path or a fragment as well). A link without a destination is not a link: it is drawn as the text around it and reported (LNK-21). |
target | same | new | "same" | Where the destination opens. same: where the person is — the same tab on the web, the app's own handling of the address elsewhere. new: a new context — a new tab or window on the web, outside the current screen elsewhere — which a link with a label marks with the glyph open_in_new after it and says through targetLabel (LNK-13). Whether the destination is another site is a second fact, external's (LNK-30): a link may leave the site without opening a new context, and open one without leaving. |
targetLabel | string | "" | What assistive technology reads after the link's name while target is new ("opens in a new tab"). Tanrei ships no words of its own, so the product gives them in its language. Required while target is new; ignored otherwise. |
external | auto | on | off | "auto" | Whether the destination is on another site than the one the person is on. auto: the link decides, where the platform can tell (LNK-30) — on the web an address of another origin than the page's and the product's declared own; elsewhere an address outside the hosts the product has declared. on: it is external, whatever the address. off: it is not, and the link shows and says nothing of it. An external link with a label shows an arrow after it and, where siteIcon is given, that site's picture before it (LNK-31, LNK-32); a design system or a product turns either off for every link with comp.link.external.marks. It changes nothing about where or how the destination opens. |
externalLabel | string | "" | What assistive technology reads after the link's name while the link is external and target is same ("external link"), in the product's language. Empty, the words the product has set once for every external link are read (LNK-34). Ignored while target is new: targetLabel is then the link's one description. |
siteIcon | string | "" | The picture of the site an external link leads to: the address of an image as the platform's images take one (on the web a URL the page may load — of the product's own origin, or a data URL), or the platform's own image value. Drawn before the label while the link is external (LNK-32); ignored otherwise. The link never derives it from href and never asks the destination or anyone else for it (LNK-35): the product gives a picture it has, made where the product is built. Empty, the link shows the arrow alone. |
variant | standard | inverse | "standard" | Which surface the link is drawn for. standard: the product's ordinary surfaces and its quiet containers. inverse: a surface of the opposite theme (a snackbar's, a tooltip's, a dark band on a light page), where the standard link color is not readable. It changes colors only. A design system may add values. |
underline | auto | always | hover | never | "auto" | When the label is underlined. always: at rest and in every state. hover: while the link is hovered, focused from the keyboard or pressed, and not at rest. never: in no state. Auto takes comp.link.underline.visibility, the design system's answer (always in the default system). hover and never are for a link that stands by itself among other links — a list of navigation, a footer — where its place says what it is; inside running text use them only where the link color stands 3:1 apart from the text's (LNK-29). |
standalone | boolean | false | False: the link is part of a sentence or a line of text, and its target is its own text (LNK-17). True: the link stands by itself — under a paragraph, in a table cell, in a row of links — and its hit area is extended to the minimum target without changing how it is drawn or laid out. It changes nothing a person sees. |
iconPosition | leading | trailing | "leading" | Which side of the label the glyph sits on, in the reading direction. Ignored when the link has no label or no glyph. |
current | boolean | false | The link names the place the person is already at, in a set of navigation: the current page in a row of site links or a trail of pages, the current section in a table of contents. It is exposed as the current item, drawn without an underline, whatever underline says, at the emphasized weight, and stays a link (LNK-18). At most one link of a set is current; the set, not the link, decides which. |
disabled | boolean | false | The link cannot be followed now (the previous page of the first page): it keeps the link role with the disabled state and no destination, leaves the focus order and opens nothing (LNK-19). |
label | string | "" | The accessible name of a link that is a glyph alone ("Link to Installation"), in the product's language. Ignored while the link has a label of text, which names it. |
插槽
| 插槽 | 说明 |
|---|---|
default | The label: the text that says where the link goes. Leave it empty for a link that is a glyph alone. |
icon | The glyph: a glyph of the system's icon set, drawn through the platform's icon helper at the size of the link's text. With a label it sits at the side iconPosition names; without one it is the link's only content. At the leading side it stands where an external link would show the site's picture, and at the trailing side where it would show its arrow or the mark of a new context: the product's glyph stands and the link draws nothing of its own there. |
事件
| 事件 | 说明 |
|---|---|
click | The link was activated by pointer, touch, Enter or assistive technology. It is emitted before the destination opens; a product that takes the navigation itself (a client-side router) cancels it (LNK-12). |
状态
行为
以 EARS 形式写成的需求。每个平台的实现都按这些 ID 逐条测试。需求原文取自规格文件，原样以英文呈现。
| ID | 需求 |
|---|---|
LNK-1 | WHILE href is a destination THE link SHALL be the platform's own link to it (the web's anchor element in the document itself, not in a shadow root; SwiftUI's Link; on Compose, Flutter and React Native an element or a run of text with the platform's link semantics whose address is opened by the platform's opener), so that whatever the platform gives a link — on the web its context menu, opening in a new tab or window, copying and dragging its address, the address shown before it is followed, a crawler and a search index that read it, and a link that works before any script has run — is the platform's, and not the link's to draw or to take over; and SHALL expose the link role. |
LNK-2 | THE link SHALL draw its label in the text style of the text it sits in — that text's family, size, weight, line height and letter spacing — bringing no text style of its own, in the label color of its variant (comp.link.standard.label.color for standard, comp.link.inverse.label.color for inverse), on the baseline of the text beside it, and SHALL NOT make its line taller than that text makes it. |
LNK-3 | WHILE its underline is shown (LNK-27, LNK-28) THE link SHALL draw it comp.link.underline.width thick, comp.link.underline.offset below the text's baseline, in the label's color of that state, under the text only and not under a glyph, the site icon or the mark. WHILE its underline is always — the default system's choice — THE link SHALL draw it at rest and in every state, so that a link is told from the text around it without relying on color. A current link (LNK-18) and a link that is a glyph alone (LNK-16) draw none, whatever the choice. |
LNK-4 | THE link SHALL wrap its label with the text it sits in, breaking where that text's language allows a break and, for a run with no such place that is longer than the line (an address), inside the run rather than overflowing; it SHALL NOT cut its label, draw an ellipsis or scroll; and on every line it runs over it SHALL draw its underline, its container and its focus ring for its own part of that line. |
LNK-5 | THE link SHALL draw its container as the box of its content on each line it runs over — as wide as its part of the line and as high as the text's own box, never the line's whole height where that would touch a neighbouring line's text — filled with the container color of its variant and state, with corners comp.link.container.shape, and SHALL NOT let the container take room, move the text beside it or change a line's height. |
LNK-6 | WHILE hovered, keyboard-focused or pressed THE link SHALL render its container, label, icon and opacity from the component tokens of the highest-precedence active state, with precedence pressed over focused over hovered; focus gained by pointer or touch SHALL NOT select the focused state. |
LNK-7 | WHEN the link receives keyboard focus THE link SHALL show the focus ring without animation — the system's focus indicator, sys.focus.offset from the container, sys.focus.outer-width wide in the focus-ring color, with the inner stroke of sys.focus.inner-width where the system has one — around its part of each line it runs over, never as one box around the lines between its first word and its last; focus gained by pointer or touch SHALL NOT show it. |
LNK-8 | WHEN the link is pressed by pointer, touch or Enter THE link SHALL show the pressed state without delay and SHALL keep it visible for at least sys.motion.duration.press-hold, even when the press ends sooner. |
LNK-9 | WHILE pressed THE link SHALL answer as sys.behavior.pressed-feedback names: overlay applies the pressed tokens to the whole container at once; ripple grows the pressed state layer from the point of contact (from the center for keyboard activation); dim applies the pressed opacity to the whole control and draws no state layer; none draws no answer to the press. Under ripple and dim only the container color stays with the state under the press; label, icon, opacity and shape still come from the pressed tokens. Under none every part stays with the state under the press. The ripple grows over comp.link.motion.feedback-duration with motion.state-easing, fades over motion.state-duration with motion.state-easing once the press has ended and press-hold has passed, and appears whole where motion is reduced. |
LNK-10 | THE link SHALL ease its container corners by sys.shape.corner-smoothing (0 is a quarter circle, 0.6 the iOS continuous corner; a platform with only the OS curve draws it for any amount above 0) and show its keyboard focus as sys.behavior.focus-style names (ring or glow); a platform that cannot draw a choice SHALL fall back to the first value and state that in its README. |
LNK-11 | THE link SHALL change between its states over comp.link.motion.state-duration with comp.link.motion.state-easing, and at once where motion is reduced. |
LNK-12 | WHEN the user activates the link by pointer, touch or Enter THE link SHALL emit click exactly once and then open href where target names, unless the product cancelled that click, in which case it SHALL open nothing: the product's own router has taken the navigation. It SHALL NOT hold the navigation back for sys.motion.duration.press-hold. THE link SHALL NOT be activated by Space, which on the web scrolls the page as it does on any link, and SHALL NOT show the pressed state for it; WHERE the platform gives its links other keys or gestures (on the web a modified or a middle click that opens a new tab, on Apple platforms a long press that previews) THE link SHALL leave them to the platform. |
LNK-13 | WHILE target is new THE link SHALL open href in a new context — on the web a new tab or window that is given no handle to the page that opened it; on the other platforms outside the screen the person is on, as the platform's opener decides — and, WHILE it has a label and no glyph of the product's after it, SHALL draw the glyph open_in_new of the system's icon set after the label as LNK-14 draws a trailing glyph — at the end of the label in the link's own direction, right after its last word — in the label color of its variant and state, through the icon helper, which mirrors it where the link's own direction is right-to-left because the icon set marks its name, and hidden from assistive technology. It SHALL draw that glyph whether or not the link is external, and then no arrow (LNK-31): the place after the label holds one glyph. WHILE the link holds the product's own glyph at its trailing side, or has no label, THE link SHALL draw no mark of its own: the product has chosen what that place shows. Whether a mark is drawn or not THE link SHALL expose targetLabel as its description, read after its name and role — its one description, so externalLabel is not read with it (LNK-34) — and WHILE targetLabel is empty SHALL still render and in debug builds report that a link that opens a new context does not say so. WHILE target is same THE link SHALL draw no open_in_new and SHALL ignore targetLabel. |
LNK-14 | WHILE the link has both a label and a glyph THE link SHALL draw the glyph at the side iconPosition names in the link's own direction — the direction LNK-26 lays its label out in: a standalone link's label's own, and a phrase's the sentence's unless the product marks the phrase with a direction of its own — leading before the label's first word, trailing after its last word, both mirrored where that direction is right-to-left in a box as large as the font size of the link's text, comp.link.container.gap from the label, centred on the line of the word beside it, in the label color of its variant and state, with sys.icon.family.unselected and sys.icon.fill.unselected, sys.icon.weight and an optical size clamped between sys.icon.optical-size.min and sys.icon.optical-size.max, hidden from assistive technology; and SHALL keep the glyph on the line of the word next to it, so that a leading glyph never ends a line and a trailing glyph or the mark never begins one. |
LNK-15 | WHILE the link has a label THE link SHALL expose the label's text as its accessible name and ignore the label prop; WHILE it has a glyph and no label THE link SHALL expose the label prop as its accessible name and keep the glyph from assistive technology; WHILE it has a glyph, no label and an empty label prop THE link SHALL still render, and in debug builds report that it has no accessible name. THE link SHALL add nothing to its name: neither its address, nor that it opens a new context (LNK-13), nor that it leaves the site (LNK-34), nor that it is current (LNK-18); the site icon and the arrow are kept from assistive technology and name nothing. |
LNK-16 | WHILE the link has a glyph and no label THE link SHALL draw the glyph alone, in a box as large as the font size of the text it sits in, in the icon color of its variant and state (comp.link.standard.icon.color for standard, comp.link.inverse.icon.color for inverse), with its container a square one line of that text high around it, and SHALL draw no underline and no mark; it SHALL answer hover, focus and press and extend its hit area as LNK-6 to LNK-10 and LNK-17 say. Where it stands and when it is seen are the layout's that places it: a heading's anchor is placed and revealed by prose and is this link showing the glyph link. |
LNK-17 | WHILE standalone is false and the link has a label THE link SHALL take input on its own text and container and nowhere else: its hit area is its part of each line and SHALL NOT reach over the text of a neighbouring line or of the same line. WHILE standalone is true, or the link is a glyph alone, and its visual size is below the minimum target THE link SHALL extend its hit area on both axes to sys.target.touch for touch input and sys.target.pointer for fine pointers, without changing its visual size or the room it takes in the layout; a platform that cannot tell the input type SHALL use sys.target.touch. |
LNK-18 | WHILE current is true THE link SHALL expose itself as the current item of its set (on the web the current page; a platform without that state, the selected state) and stay a link that can be focused and followed; it SHALL draw its container, label and glyph from the parts of its variant prefixed with current (comp.link.standard.current.label.color, comp.link.standard.current.icon.color, and inverse's tokens of the same names), SHALL draw no underline, and SHALL draw its label at the emphasized weight of the text style it sits in — that style's weight plus sys.typescale.emphasis.body in running text and a label, plus sys.typescale.emphasis.heading in a heading — so that it is told from the links beside it by more than its color. |
LNK-19 | WHILE disabled is true THE link SHALL NOT be a link that can be followed: it SHALL render its container, label, icon and opacity from the disabled component tokens of its variant, its underline, where its choice draws one at rest (a disabled link is neither hovered nor focused, so under hover it has none), the mark of LNK-13 and the arrow of LNK-31 in the disabled label color, the site icon at comp.link.site-icon.disabled-opacity, SHALL expose the link role with the disabled state and no destination, SHALL NOT be focusable, SHALL NOT emit click, and SHALL open nothing by any means the platform gives a link (on the web the anchor carries no href, so there is no context menu entry, no drag and no new tab for it). |
LNK-20 | THE link SHALL draw no state for a destination already visited: its colors say what it is and what state it is in, and are the same before and after it has been followed. |
LNK-21 | IF href is empty or only white space, or names a script to run rather than a place to go (the web's javascript: scheme), or cannot be read as an address by the platform, THE link SHALL NOT be a link: it SHALL draw its content as the text around it, with no underline, no state, no mark, no arrow and no site icon, SHALL expose no role, SHALL NOT be focusable and SHALL emit nothing, and in debug builds report it — a link without a destination has nothing else to be, and a press that does something on the page is a button's. WHEN target or variant names a value the link or the active design system does not have THE link SHALL behave as same and render with the default variant's tokens, WHEN underline or external names a value the link does not define THE link SHALL treat it as auto, and in each case in debug builds report the unknown value. |
LNK-22 | WHERE the platform draws with a person's own forced colors (the web's forced-colors mode, and a platform's equivalent where it has one) THE link SHALL draw its label, its glyph, its mark or arrow and its underline in the platform's link color and, WHILE disabled, in its disabled text color; SHALL draw the underline at rest whatever underline and the tokens it follows say, except on a current link and a glyph alone — the colors are then the person's and not the design system's, so nothing any longer holds the link's color apart from the text's (LNK-29), and the line is what the platform itself gives a link; SHALL draw the site icon as the picture it is, unchanged; and SHALL draw its focus ring in the platform's highlight color. |
LNK-23 | WHILE the text size is enlarged THE link SHALL grow with the text it sits in — its label, its glyph box, the box of its site icon, its container and its hit area — and SHALL keep comp.link.underline.width, comp.link.underline.offset, comp.link.container.gap and comp.link.site-icon.shape. |
LNK-24 | THE link 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 link is shown THE link SHALL draw itself for the new direction at once, without a motion of its own, keeping its focus. |
LNK-25 | WHERE the layout direction is right-to-left THE link SHALL draw the glyph of its icon slot mirrored left to right exactly when the system's icon set marks that glyph's name as mirrored or the product forces mirroring for that use, and unmirrored when the product forbids it: the icon helper mirrors the glyph inside its own box, about the box's vertical centre line, changing neither its place, size, color and fill nor the order LNK-14 gives. THE link SHALL NOT mirror a glyph itself, and SHALL NOT mirror content the product gives as an image or a view of its own rather than by a glyph's name — the site icon among it (LNK-32). |
LNK-26 | WHILE standalone is true THE link SHALL lay out its label as text of its own direction, isolated from the text around it: it takes the base direction of its first strong character, or the layout direction where it has none, so that a left-to-right word, a number with its sign or unit, a telephone number and an address keep their own order in a right-to-left layout and reorder nothing beside them; THE link SHALL still place the label and align its lines by the layout direction, not by the text's own. WHILE standalone is false THE link SHALL lay out its label as part of the sentence it is in, in that sentence's direction, isolated only so that it reorders nothing beside it: a phrase of a sentence is that sentence's text, and what direction a block of text has is that block's to say. |
LNK-27 | THE link SHALL show its underline as its underline prop names: WHILE underline is auto, as comp.link.underline.visibility names, which follows sys.behavior.link-underline unless a design system sets the link apart; WHILE underline is always, hover or never, as that value names, whatever the tokens say. WHEN underline, or the token it follows, changes THE link SHALL draw the other form at once, moving no text and keeping its focus. A platform that cannot draw a choice SHALL fall back to the first value, always, and state that in its README. |
LNK-28 | WHILE its underline is hover THE link SHALL draw no underline at rest and SHALL draw it, as LNK-3 says, WHILE the link is hovered, keyboard-focused or pressed, the line arriving and leaving with that state as LNK-11 times it and moving no text; the focus ring of LNK-7 is drawn as under every choice, so keyboard focus shows the ring and the line together. WHERE the input has no hover (touch) the line is therefore seen for the length of a press and no longer, and THE link SHALL put nothing in its place at rest: a link under hover has to be told from the text beside it as a link that is never underlined has to be (LNK-29). WHILE its underline is never THE link SHALL draw no underline in any state, and SHALL still show hover, focus and press by its container, its label color and its focus ring (LNK-6, LNK-7). |
LNK-29 | WHILE its underline is not always, standalone is false, current is false and it has a label THE link SHALL, in debug builds on a platform that can read both colors, report a label color whose contrast against the color of the text the link sits in is under 3:1, and SHALL still render: a phrase in running text that is not underlined at rest is told from the words beside it by color alone, which people who do not see that difference cannot do (WCAG 1.4.1). THE link SHALL report nothing for a standalone link, a current link or a glyph alone, which are not phrases among other words. The same ratio is held for the design system's own choice by the build, not by the link: where sys.behavior.link-underline or comp.link.underline.visibility is not always, the link color is held 3:1 apart from the text color in every scheme. |
LNK-30 | THE link SHALL treat its destination as external as its external prop names: WHILE external is on, as external, whatever href is; WHILE it is off, as not external; WHILE it is auto, as external exactly when the platform can tell that the destination is on another site than the one the person is on. On the web that is: href, read against the document's address, has the scheme http or https, its origin is neither the document's nor one the product has declared as part of its own site, and the anchor does not ask for a download. A path, a fragment, an address of any other scheme (a mail address, a telephone number) and a download are never external under auto. On the other platforms, where a screen has no address of its own, that is: the product has declared the hosts that are its own, and href is an http or https address outside them; WHILE it has declared none, nothing is external under auto. THE link SHALL change nothing but what it shows and says for being external (LNK-31 to LNK-34): where the destination opens is target's alone, and nothing is added to how the address is requested. |
LNK-31 | WHILE the link is external, has a label, holds no glyph of the product's after it, target is same and comp.link.external.marks is not none THE link SHALL draw the glyph arrow_outward of the system's icon set after the label as LNK-14 draws a trailing glyph — at the end of the label in the link's own direction (LNK-14), right after its last word, in a box as large as the font size of its text, comp.link.container.gap from the label, on the line of the last word and never beginning a line, not underlined — in the label color of its variant and state, through the icon helper, which mirrors it where the link's own direction is right-to-left because the icon set marks its name, and hidden from assistive technology. WHILE target is new THE link SHALL draw the mark of LNK-13 in that place and no arrow: the place holds one glyph, and that the page the person is on stays open is what they need to know first. WHILE the link holds the product's own glyph at its trailing side, or has no label, THE link SHALL draw no arrow. |
LNK-32 | WHILE the link is external, has a label, siteIcon names a picture, the link holds no glyph of the product's before its label and comp.link.external.marks is all THE link SHALL draw that picture before the label as LNK-14 places a leading glyph: in a square box as large as the font size of the link's text, comp.link.container.gap from the label, centred on the line of the first word and never ending a line, the whole picture scaled to fit the box with its proportions kept, its corners comp.link.site-icon.shape eased as LNK-10 eases the container's, not underlined, never mirrored, in every state as it is at rest, and hidden from assistive technology with no text alternative: it is decoration, and the label names the link. THE link SHALL keep the box's room from the first frame, so that nothing moves when the picture arrives, and IF the picture cannot be loaded or decoded SHALL draw nothing in the box — no broken-picture mark, no alternative text, no glyph in its place — and in debug builds report it. WHILE siteIcon is empty THE link SHALL draw no picture and keep no room for one: an external link without a picture shows the arrow alone. WHILE the link holds the product's own glyph before its label THE link SHALL draw that glyph and no picture. THE link SHALL draw the picture as a picture only: whatever the file holds, nothing in it is run, laid out as markup or opened as a document. |
LNK-33 | THE link SHALL draw the marks of an external link as comp.link.external.marks names: all, the site icon where one is given (LNK-32) and the arrow (LNK-31); arrow, the arrow alone, with no picture drawn and no room kept for one; none, neither, and the link then exposes nothing of being external (LNK-34). The choice is the design system's or the product's layer's and holds for every link; one link is set apart by external (off shows and says nothing) and by leaving siteIcon empty. It SHALL change nothing about the mark of a new context (LNK-13). WHEN the choice changes THE link SHALL draw the other form at once. A platform that cannot read the choice SHALL fall back to the first value, all, and state that in its README. |
LNK-34 | WHILE the link is external, has a label, target is same and comp.link.external.marks is not none THE link SHALL expose as its description, read after its name and role, externalLabel or, WHILE externalLabel is empty, the words the product has set once for every external link (on the web where the page is made or through the package's script; a setting of the package elsewhere), whether the arrow is drawn or the product's own trailing glyph stands in its place; WHILE both are empty THE link SHALL still render and in debug builds report, once for the page or the screen and not once for each link, that external links do not say so. WHILE target is new THE link SHALL expose targetLabel alone (LNK-13): a link has one description, and the product words it for both facts where both should be said ("opens example.com in a new tab"). WHILE the link has no label it SHALL expose nothing of being external. Tanrei ships no words of its own. |
LNK-35 | THE link SHALL request nothing by itself for what it draws: it SHALL NOT derive a picture's address from href, SHALL NOT ask the destination or any other party for an icon, a title or a preview, and SHALL NOT reach the destination in any way before the person follows the link. The one address it loads is siteIcon, exactly as the product gave it; on the web it loads that picture without sending the page's address with the request, and in debug builds reports a siteIcon whose origin is not the document's — every reader's browser would then tell that other party which page is being read. |
各平台名称对照
对等并不意味着 API 完全相同。同一份契约，由各平台以自己的惯用方式表达。
| 规格 | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
|---|---|---|---|---|---|
| 组件 | tanrei-link | TanreiLink | TanreiLink | TanreiLink | Link |
href · 属性 | href | destination | href | href | href |
target · 属性 | target | target | target | target | target |
targetLabel · 属性 | aria-description | targetLabel | targetLabel | targetSemanticLabel | targetLabel |
external · 属性 | data-external | external | external | external | external |
externalLabel · 属性 | aria-description | externalLabel | externalLabel | externalSemanticLabel | externalLabel |
siteIcon · 属性 | img.tanrei-link-site-icon | siteIcon | siteIcon | siteIcon | siteIcon |
variant · 属性 | data-variant | variant | variant | variant | variant |
underline · 属性 | data-underline | underline | underline | underline | underline |
standalone · 属性 | data-standalone | TanreiLink | TanreiLink | TanreiLink | standalone |
iconPosition · 属性 | data-icon-position | iconPosition | iconPosition | iconAlignment | iconPosition |
current · 属性 | aria-current | isCurrent | current | isCurrent | current |
disabled · 属性 | aria-disabled | disabled | enabled | enabled | disabled |
label · 属性 | aria-label | label | contentDescription | semanticLabel | accessibilityLabel |
click · 事件 | click | action | onClick | onPressed | onPress |
| 备注 | A class on the product's own anchor, not an element with an anchor in its shadow root: <a class="tanrei-link" href="…">…</a>, styled by a stylesheet of the package (LNK-1). The anchor is in the document, so it is a link before any script runs and for whatever reads the page as built: a crawler, a search index, a framework that prefetches or routes the anchors it finds, and a router's own link component, which takes the class. The props are the anchor's own attributes: href; target in HTML's spelling (_blank is new; target="new" would name a window, so it is not used here); aria-description for targetLabel; aria-current="page" (or another of its values) for current; aria-label for label; and a disabled link is written <a class="tanrei-link" role="link" aria-disabled="true"> with no href. data-variant="inverse", data-standalone and data-icon-position="trailing" are the three that HTML has no attribute for. The glyph is a .tanrei-icon element inside the anchor, before or after the text; the mark is the anchor's ::after (the icon font's open_in_new, mirrored under the anchor's own :dir(rtl)). A standalone link is given the dir of its label's first strong character (a glyph's name aside) by the package's script where the page wrote none, so its direction, and so the side of its glyphs and its mark, is its label's first strong character's (LNK-26, LNK-14); a phrase in a sentence takes the dir the page writes on it, not drawn while data-icon-position is trailing or the anchor has no text (aria-label present). The container and the ring follow wrapped lines through box-decoration-break: clone and outline; the extended hit area of LNK-17 is a pseudo-element that takes no room. The stylesheet alone gives the default system's whole look and every state, including the press-hold (a delayed transition back from :active). The package's script, where it is loaded, adds through one listener on the document what a stylesheet cannot: the shared press primitive (ripple and dim, LNK-9), noopener on a new context, the refusals of LNK-21 and every debug report. The same rules apply to every anchor of a .tanrei-prose that is prose's own (PRS-16), so rendered Markdown needs no class, and a heading's anchor (.tanrei-prose-anchor) is the icon-only form. rel and download are the anchor's own. React: Link renders the same anchor and takes a render prop for a router's link. data-underline="always | hover | never" sets one link apart; without it the anchor follows --tanrei-comp-link-underline-visibility, which the stylesheet reads by a container style query and, where the browser has none, from data-underline-system written on the document's root by the package's script; with neither it is always, the first value. The custom property can be set on any element, so a region (a footer, a navigation list) takes its own choice without an attribute on each link. hover is :hover under (hover: hover), :focus-visible and the pressed state; the line is the text decoration's color, so nothing moves. External: the stylesheet computes nothing about addresses. It draws the marks for data-external that is not false, and that attribute is written by whoever knows the page's address — where the page is made, by markExternalLinks() of @tanrei/web/links (Node; it takes the tree the product's own renderer already has, and parses nothing) or by React's Link, both from the product's site origins; and, for an anchor that carries no data-external, by the package's script, which compares new URL(a.href).origin with location.origin and with setSiteOrigins([…]) and writes data-external="detected" (re-read when href changes; only a value it wrote is ever changed by it). A page with neither shows no external mark: a missing mark, never a wrong one. Marks written by the script arrive after the first paint and take room; marks written where the page is made are in the first paint. The arrow is the same ::after as the mark of a new context, whose content is open_in_new while target="_blank" and arrow_outward otherwise, so the two cannot both be drawn. The site icon is the product's <img class="tanrei-link-site-icon" src="…" alt="" width="…" height="…" loading="lazy" decoding="async" referrerpolicy="no-referrer">, the anchor's first child, placed as a leading glyph is; alt="" and no role keep it from assistive technology; it is an img, never an inline svg, an object or an iframe, so a vector file is drawn and not run (LNK-32). A broken picture keeps its room and draws nothing. externalLabel is aria-description on the anchor, written by the same step that writes data-external where the product set words for every external link (externalLabel of markExternalLinks(), setExternalLabel() of the script). comp.link.external.marks is read as the underline choice is. resolveSiteIcons() of @tanrei/web/links is the build-time helper that turns the external origins of a site into pictures the site serves itself; the component never calls it and nothing of it runs in a browser. Words: the words set once for every external link are the key externalLabel of the product's words, and targetLabel is read the same way; the script's setExternalLabel(text) is setWords({ externalLabel: text }) before it is released. | Two spellings for the two places a link stands. Standalone: the view TanreiLink(_ title: String, destination: URL, target:, targetLabel:, variant:, icon:, iconPosition:, isCurrent:, action:), built on SwiftUI's Link, taking its font from the environment and disabled by .disabled(_:); TanreiLink(label:icon:destination:) is the glyph alone. In text: Text(tanreiLink:) helpers that build an AttributedString run with the link attribute, the underline and the variant's color, for use inside a Text. action runs before the address opens and returns whether the link should still open it (the environment's OpenURLAction does the opening, so an app that routes addresses itself handles it there). The isLink trait; isSelected for current. SwiftUI draws no hover, focus or press on a run inside a Text: an in-text link there has its resting look and the system's own focus and press, and the README says so. Not built on this platform yet: underline: TanreiLinkUnderline? = nil (nil is auto; .always, .hover, .never), read from the generated choice otherwise; hover is the pointer's on iPadOS, macOS and visionOS, and focus from a keyboard. external: Bool? = nil (nil is auto): auto reads the hosts the app declares once in the environment (.tanreiSiteHosts([…])), and with none declared nothing is external. siteIcon: Image? = nil is an image the app already has (an asset, or one it loaded itself); the view loads nothing. externalLabel is the accessibility hint; the words for every external link are an environment value. In a Text run the arrow and the picture are attachments of the attributed string. | Standalone: TanreiLink(text, href, onClick = null, target, targetLabel, variant, icon, iconPosition, current, enabled, contentDescription), drawn with LocalTextStyle. In text: tanreiLinkAnnotation(href, variant, onClick) returns a LinkAnnotation.Url whose TextLinkStyles carry the resting, hovered, focused and pressed tokens, for AnnotatedString.Builder.withLink; a link annotation has the link semantics Compose lacks for a clickable element (the standalone form, a clickable element, still has no link role). enabled is the inverse flag. The address is opened through LocalUriHandler.current after onClick, which returns false to keep it closed. Current is selected semantics. A run of text draws no ripple: LNK-9's fallback. Not built on this platform yet: underline: TanreiLinkUnderline? = null (null is auto). external: Boolean? = null (null is auto), decided against LocalTanreiSiteHosts; with none provided nothing is external. siteIcon: Painter? = null is the app's own painter; the composable loads nothing. externalLabel joins the state description; the words for every external link are a composition local. In an annotated string the arrow and the picture are inline content. | Standalone: TanreiLink(label: …, href: …, onPressed:, target:, targetSemanticLabel:, variant:, icon:, iconAlignment:, isCurrent:, enabled:), in DefaultTextStyle. In text: TanreiLinkSpan(text: …, href: …), an InlineSpan for Text.rich that carries its recognizer and its states. Semantics(link: true), linkUrl where the engine has it; selected for current. The address is opened by the opener the app provides, after onPressed, which returns false to keep it closed. enabled is the inverse flag. Not built on this platform yet: underline: TanreiLinkUnderline? (null is auto). external: bool? (null is auto), decided against the hosts of TanreiLinkScope; with none nothing is external. siteIcon: ImageProvider? is the app's own provider — an asset or a memory image; the widget never builds a network provider from href. externalSemanticLabel is the semantics hint; the words for every external link come from TanreiLinkScope. In a TanreiLinkSpan the arrow and the picture are widget spans. | <Link href="…">text</Link> is a Text with accessibilityRole="link": nested in a Text it is in that text and inherits its style; by itself it takes a style (a text style of the typescale) and standalone extends its hitSlop. onPress receives an event whose preventDefault() keeps the address closed; otherwise Linking.openURL(href). accessibilityHint carries targetLabel; accessibilityState carries disabled and, for current, selected. A nested Text draws no ripple and no hover: LNK-9's fallback. Follows the app's direction where an ancestor's is not known. Not built on this platform yet: underline?: 'always' | 'hover' | 'never' (undefined is auto); hover exists only where the platform reports a pointer. external?: boolean (undefined is auto), decided against the hosts given to the provider; with none nothing is external. siteIcon?: ImageSourcePropType is a source the app already has (a required asset); the component never builds a { uri } from href. externalLabel is accessibilityHint. Nested in a Text, the picture is an inline Image and the arrow a glyph of the icon font. |
令牌
| 令牌 | 引用 | 解析值（浅色） |
|---|---|---|
--tanrei-comp-link-container-gap | sys.space.space50 | 4px |
--tanrei-comp-link-container-shape | sys.shape.corner.extra-small | 3px |
--tanrei-comp-link-disabled-container-shape | — | 3px |
--tanrei-comp-link-disabled-opacity | — | 1 |
--tanrei-comp-link-external-marks | — | 0 |
--tanrei-comp-link-focused-container-shape | — | 3px |
--tanrei-comp-link-focused-opacity | — | 1 |
--tanrei-comp-link-hovered-container-shape | — | 3px |
--tanrei-comp-link-hovered-opacity | — | 1 |
--tanrei-comp-link-inverse-container-color | — | |
--tanrei-comp-link-inverse-current-container-color | — | |
--tanrei-comp-link-inverse-current-icon-color | comp.link.inverse.current.label.color | |
--tanrei-comp-link-inverse-current-label-color | sys.color.inverse-on-surface | |
--tanrei-comp-link-inverse-current-state-layer-color | comp.link.inverse.current.label.color | |
--tanrei-comp-link-inverse-disabled-container-color | — | |
--tanrei-comp-link-inverse-disabled-current-container-color | — | |
--tanrei-comp-link-inverse-disabled-current-icon-color | — | |
--tanrei-comp-link-inverse-disabled-current-label-color | — | |
--tanrei-comp-link-inverse-disabled-current-state-layer-color | — | |
--tanrei-comp-link-inverse-disabled-icon-color | — | |
--tanrei-comp-link-inverse-disabled-label-color | — | |
--tanrei-comp-link-inverse-disabled-state-layer-color | — | |
--tanrei-comp-link-inverse-focused-container-color | — | |
--tanrei-comp-link-inverse-focused-current-container-color | — | |
--tanrei-comp-link-inverse-focused-current-icon-color | — | |
--tanrei-comp-link-inverse-focused-current-label-color | — | |
--tanrei-comp-link-inverse-focused-current-state-layer-color | — | |
--tanrei-comp-link-inverse-focused-icon-color | — | |
--tanrei-comp-link-inverse-focused-label-color | — | |
--tanrei-comp-link-inverse-focused-state-layer-color | — | |
--tanrei-comp-link-inverse-hovered-container-color | — | |
--tanrei-comp-link-inverse-hovered-current-container-color | — | |
--tanrei-comp-link-inverse-hovered-current-icon-color | — | |
--tanrei-comp-link-inverse-hovered-current-label-color | — | |
--tanrei-comp-link-inverse-hovered-current-state-layer-color | — | |
--tanrei-comp-link-inverse-hovered-icon-color | — | |
--tanrei-comp-link-inverse-hovered-label-color | — | |
--tanrei-comp-link-inverse-hovered-state-layer-color | — | |
--tanrei-comp-link-inverse-icon-color | sys.color.inverse-on-surface | |
--tanrei-comp-link-inverse-label-color | sys.color.inverse-link | |
--tanrei-comp-link-inverse-pressed-container-color | — | |
--tanrei-comp-link-inverse-pressed-current-container-color | — | |
--tanrei-comp-link-inverse-pressed-current-icon-color | — | |
--tanrei-comp-link-inverse-pressed-current-label-color | — | |
--tanrei-comp-link-inverse-pressed-current-state-layer-color | — | |
--tanrei-comp-link-inverse-pressed-icon-color | — | |
--tanrei-comp-link-inverse-pressed-label-color | — | |
--tanrei-comp-link-inverse-pressed-state-layer-color | — | |
--tanrei-comp-link-inverse-state-layer-color | comp.link.inverse.label.color | |
--tanrei-comp-link-motion-feedback-duration | sys.motion.role.feedback | 450ms |
--tanrei-comp-link-motion-state-duration | sys.motion.role.state.compact | 200ms |
--tanrei-comp-link-motion-state-easing | sys.motion.easing.state | cubic-bezier(0.2, 0, 0, 1) |
--tanrei-comp-link-pressed-container-shape | — | 3px |
--tanrei-comp-link-pressed-opacity | — | 1 |
--tanrei-comp-link-site-icon-disabled-opacity | sys.state.disabled-content-opacity | 0.38 |
--tanrei-comp-link-site-icon-shape | sys.shape.corner.extra-small | 3px |
--tanrei-comp-link-standard-container-color | — | |
--tanrei-comp-link-standard-current-container-color | — | |
--tanrei-comp-link-standard-current-icon-color | comp.link.standard.current.label.color | |
--tanrei-comp-link-standard-current-label-color | sys.color.on-surface | |
--tanrei-comp-link-standard-current-state-layer-color | comp.link.standard.current.label.color | |
--tanrei-comp-link-standard-disabled-container-color | — | |
--tanrei-comp-link-standard-disabled-current-container-color | — | |
--tanrei-comp-link-standard-disabled-current-icon-color | — | |
--tanrei-comp-link-standard-disabled-current-label-color | — | |
--tanrei-comp-link-standard-disabled-current-state-layer-color | — | |
--tanrei-comp-link-standard-disabled-icon-color | — | |
--tanrei-comp-link-standard-disabled-label-color | — | |
--tanrei-comp-link-standard-disabled-state-layer-color | — | |
--tanrei-comp-link-standard-focused-container-color | — | |
--tanrei-comp-link-standard-focused-current-container-color | — | |
--tanrei-comp-link-standard-focused-current-icon-color | — | |
--tanrei-comp-link-standard-focused-current-label-color | — | |
--tanrei-comp-link-standard-focused-current-state-layer-color | — | |
--tanrei-comp-link-standard-focused-icon-color | — | |
--tanrei-comp-link-standard-focused-label-color | — | |
--tanrei-comp-link-standard-focused-state-layer-color | — | |
--tanrei-comp-link-standard-hovered-container-color | — | |
--tanrei-comp-link-standard-hovered-current-container-color | — | |
--tanrei-comp-link-standard-hovered-current-icon-color | — | |
--tanrei-comp-link-standard-hovered-current-label-color | — | |
--tanrei-comp-link-standard-hovered-current-state-layer-color | — | |
--tanrei-comp-link-standard-hovered-icon-color | — | |
--tanrei-comp-link-standard-hovered-label-color | — | |
--tanrei-comp-link-standard-hovered-state-layer-color | — | |
--tanrei-comp-link-standard-icon-color | sys.color.on-surface-variant | |
--tanrei-comp-link-standard-label-color | sys.color.link | |
--tanrei-comp-link-standard-pressed-container-color | — | |
--tanrei-comp-link-standard-pressed-current-container-color | — | |
--tanrei-comp-link-standard-pressed-current-icon-color | — | |
--tanrei-comp-link-standard-pressed-current-label-color | — | |
--tanrei-comp-link-standard-pressed-current-state-layer-color | — | |
--tanrei-comp-link-standard-pressed-icon-color | — | |
--tanrei-comp-link-standard-pressed-label-color | — | |
--tanrei-comp-link-standard-pressed-state-layer-color | — | |
--tanrei-comp-link-standard-state-layer-color | comp.link.standard.label.color | |
--tanrei-comp-link-underline-offset | sys.space.space25 | 2px |
--tanrei-comp-link-underline-visibility | sys.behavior.link-underline | 0 |
--tanrei-comp-link-underline-width | sys.border.hairline | 1px |
测试样例
作为基准的渲染结果。所有平台都以相同的 ID 为每个样例截取快照，以便相互比较。
variant: standard (43)
in-text
href: /components/button/ in-text-wrapping
href: /guides/accessibility/ in-text-wrapping-rtl
href: /guides/accessibility/ direction: rtl in-text-new
href: https://example.com/tanrei target: new targetLabel: opens in a new tab in-text-new-rtl
href: https://example.com/tanrei target: new targetLabel: يفتح في علامة تبويب جديدة direction: rtl long-address
href: https://example.com/tanrei/design-system… external: off standalone
href: /getting-started/ standalone: true standalone-leading-icon
href: /tokens.zip standalone: true slots: icon standalone-trailing-icon
href: /foundations/tokens/ standalone: true iconPosition: trailing slots: icon standalone-trailing-icon-rtl
href: /foundations/tokens/ standalone: true iconPosition: trailing direction: rtl slots: icon standalone-wrapping
href: /foundations/tokens/ standalone: true iconPosition: trailing slots: icon standalone-new
href: https://example.com/tanrei target: new targetLabel: opens in a new tab standalone: true standalone-new-leading-icon
href: https://example.com/tanrei target: new targetLabel: opens in a new tab standalone: true slots: icon standalone-new-trailing-icon
href: https://example.com/tanrei target: new targetLabel: opens in a new tab standalone: true iconPosition: trailing slots: icon icon-only
href: #installation label: Link to Installation slots: icon icon-only-new
href: https://example.com/tanrei target: new targetLabel: opens in a new tab label: Source code slots: icon icon-only-rtl
href: #installation label: رابط إلى التثبيت direction: rtl slots: icon current
href: /components/ standalone: true current: true current-leading-icon
href: /components/ standalone: true current: true slots: icon disabled
href: /page/0/ standalone: true disabled: true disabled-new
href: https://example.com/tanrei target: new targetLabel: opens in a new tab disabled: true disabled-icon-only
href: #installation disabled: true label: Link to Installation slots: icon ltr-label-rtl
href: https://example.com/tanrei external: off standalone: true direction: rtl underline-always
href: /components/button/ underline: always underline-hover
href: /components/button/ underline: hover underline-never
href: /components/button/ underline: never standalone-underline-hover
href: /getting-started/ underline: hover standalone: true standalone-underline-never
href: /getting-started/ underline: never standalone: true external
href: https://example.com/tanrei external: on externalLabel: external link external-site-icon
href: https://example.com/tanrei external: on externalLabel: external link siteIcon: fixtures/site-icon.png external-standalone
href: https://example.com/tanrei external: on externalLabel: external link standalone: true external-standalone-site-icon
href: https://example.com/tanrei external: on externalLabel: external link siteIcon: fixtures/site-icon.png standalone: true external-standalone-underline-never
href: https://example.com/tanrei external: on externalLabel: external link siteIcon: fixtures/site-icon.png underline: never standalone: true external-wrapping
href: https://example.com/tanrei external: on externalLabel: external link siteIcon: fixtures/site-icon.png external-new
href: https://example.com/tanrei target: new targetLabel: opens in a new tab external: on siteIcon: fixtures/site-icon.png external-forced
href: /partners/ external: on externalLabel: external link external-suppressed
href: https://example.com/tanrei external: off siteIcon: fixtures/site-icon.png external-mail
href: mailto:[email protected] external-leading-icon
href: https://example.com/tanrei external: on externalLabel: external link siteIcon: fixtures/site-icon.png standalone: true slots: icon external-trailing-icon
href: https://example.com/tanrei external: on externalLabel: external link siteIcon: fixtures/site-icon.png standalone: true iconPosition: trailing slots: icon external-site-icon-failed
href: https://example.com/tanrei external: on externalLabel: external link siteIcon: fixtures/missing.png external-disabled
href: https://example.com/tanrei external: on siteIcon: fixtures/site-icon.png standalone: true disabled: true external-rtl
href: https://example.com/tanrei external: on externalLabel: رابط خارجي siteIcon: fixtures/site-icon.png direction: rtl variant: inverse (7)
inverse
href: /changes/ variant: inverse inverse-new
href: https://example.com/tanrei target: new targetLabel: opens in a new tab variant: inverse inverse-current
href: /components/ variant: inverse standalone: true current: true inverse-disabled
href: /page/0/ variant: inverse standalone: true disabled: true inverse-icon-only
href: #installation variant: inverse label: Link to Installation slots: icon inverse-underline-never
href: /changes/ variant: inverse underline: never external-inverse
href: https://example.com/tanrei external: on externalLabel: external link siteIcon: fixtures/site-icon.png variant: inverse 生成自 specs/link.spec.json, tokens/comp/link.tokens.json, design/tokens/
- 链接文字背后的容器是文字本身的框（字体自身的高度），而不是整个行高。
- 带字形或标记的链接换行时，绘制成在行末切开的一个框。不带它们的链接在每一行上都有完整的四个角。
- 带有字形、标记或外部链接标记的独立链接按布局的方向排列标签，而不是按标签自己第一个字母的方向。
- 样式表不对地址做任何计算：它只为
data-external绘制标记。在生成页面的地方写上这个属性（对渲染出来的 Markdown，@tanrei/web/links的构建步骤markExternalLinks()会替你写），标记就在首次绘制里。 - 有包里的脚本时，没有
data-external、而地址离开本站的锚元素会在浏览器里被标出。这些标记在首次绘制之后才出现，每一个都会把同一行上它后面的内容推开文字大小加间距那么远。既没有这个属性也没有脚本的页面不显示任何外部链接的标记。 - 在不支持样式容器查询的浏览器里，脚本为整个页面读取这两个选择。区域自己的取值在那里不会被看到；没有脚本时，每个选择都取它的第一个值：
always，以及两种标记都显示。 - 在按下反馈为涟漪的设计系统下，跨越多行的链接改用叠加层来回应。
- 没有包里的脚本时，样式表会绘制每一种状态，按下反馈为叠加层。
| 组件 | 它是什么 | 何时使用 |
|---|---|---|
| 链接 | 通向某个地方的文本，采用周围的文本样式，下划线按设计系统的选择绘制 | 句子里的一个短语、本身就是目的地的一行文字、标题旁边的一个字形 |
| 有目的地的按钮 | 绘制成按钮的链接 | 目的地是屏幕上的操作之一：“开始使用”“查看源代码” |
| Text 按钮 | 一个按钮 | 它执行某件事，不通向任何地方，无论它多么应该看起来像文本 |
data-standalone 不改变用户看到的任何东西。它说明这个链接不属于某一行文字，于是它的点击区域可以扩展到最小目标，而不会抢走本该落在上下两行的按下操作。段落下方的链接、表格单元格里的链接和一排链接都用它。在句子里则不要加。
hover 和 never 是为独立放置的链接准备的：导航列表、页脚、一排相关页面。它们在列表里的位置就说明了它们是什么。在这些链接上设置 data-underline，或者给这个区域一个它自己的组件令牌取值，并让句子里的链接保留下划线。
- 标签要写得脱离周围的句子也能说明链接通向哪里：写“安装指南”，不写“这里”。
- 只在
sys.color.inverse-surface上使用data-variant="inverse"。在柔和的容器（语义状态的容器、secondary-container）上，用标准链接就对了。 - 一组导航里最多只把一个链接标为当前，由这组导航决定是哪一个。
- 两个独立链接之间留出
sys.target.spacing，或者让它们所在的行有一个目标那么高。 - 网站的图标要以你自己的网站提供的文件给出。
@tanrei/web/links的resolveSiteIcons()会在构建网站时生成它们，所以没有哪位读者的浏览器会向其他任何一方发出请求。 - 外部链接的文字只设置一次（
setExternalLabel()，或构建步骤的externalLabel），用你的产品的语言。它就是产品的文字里的键externalLabel：setWords({ externalLabel: '…' })给出的是同一段文字，加上{ lang }就可以按语言分别给出。
- 在链接颜色就是文本颜色的层里，不要去掉静止时的下划线。在默认系统里，链接颜色就是文本颜色本身，在全部六种配色方案里两者的对比度都是 1.00:1，所以表明“这是链接”的只有下划线。如果选择是
hover或never，而链接颜色与文本颜色的对比度不到 3:1，构建对默认系统会失败，对产品的层则给出警告。 - 不要指望
hover在触摸屏上让链接显现出来。那里没有悬停，所以hover与never适用同一条规则。 - 不要在浏览器里从那个网站或某个图标服务加载它的图标。那样每位读者的浏览器都会告诉对方正在阅读的是哪个页面。
- 不要用点击处理函数代替目的地。没有地址的锚元素会绘制成普通文本，并在调试构建中报告。
- 不要把链接放进整体可按下的控件（链接卡片、有目的地的列表项），也不要把控件放进链接。
- 不要给访问过的链接加样式。需要表示“已打开过”的产品，应根据自己的数据用 Tag 或字形来标出。
- 角色
link- 标注
- A link with a label is named by the label's text, which should say where it goes without the sentence around it ("the installation guide", not "here"). A link that is a glyph alone is named by label, which is required; its glyph is decorative to assistive technology. A link has at most one description: while target is new it is targetLabel ("opens in a new tab"); otherwise, while the link is external and marked, it is externalLabel or the product's words for every external link ("external link"). The mark, the arrow and the site icon are decorative. A current link carries the current state; nothing is added to its name.
- 最小目标
- 即使外观尺寸更小，点击区域也满足最小目标尺寸。 minimum 32px · pointer 44px · spacing 8px · touch 48px
键盘操作
| 按键 | 动作 |
|---|---|
| Tab | Moves focus to the link. A disabled link is passed. |
| Enter | Follows the link. Space does what it does on any link (on the web it scrolls the page). |
备注
- A link in running text is told from the words beside it by more than color (WCAG 1.4.1). In the default system the link color is the primary's, which is the color of the text itself — 1.00:1 against sys.color.on-surface in all six schemes — so the underline is the only thing that says "link": the default system's choice is always, and the build fails if it is changed while the colors stand as they are.
- When the underline may be left out at rest. A design system or a product may choose hover or never where its link color stands 3:1 or more apart from its text color in every scheme and still keeps its own contrast on the surfaces; a cue then remains for the pointer and the keyboard — the line itself under hover, the state layer and the focus ring under never. The build checks the ratio for the system-wide choice and for the component's own (an error in the default system, a warning in a product's layer). It cannot check one link set apart by the underline prop: that is the product's to judge, and a debug build reports an in-text link that fails it (LNK-29). hover is not a weaker never on a touch screen: there is no pointer to bring the line back, so the two are held to the same ratio.
- Links that stand by themselves — a list of navigation, a footer, a row of related pages — are what hover and never are for: their place in a list says what they are, and no word beside them competes. Set underline on those links, or give the region its own value of the component token, and leave the links of sentences underlined.
- Forced colors draw the underline whatever was chosen (LNK-22): the link color is then the platform's, and nothing the design system measured still holds.
- An external link says so twice, once for the eye and once in words: the arrow after the label, and a description read after the name (LNK-34). The arrow is not the mark of a new context: a link that leaves the site and opens where the person is shows arrow_outward; one that opens a new tab or window shows open_in_new, external or not, and its description is targetLabel. A link never shows both, and is never described twice.
- The site's picture is decoration: it has no text alternative and no role, it is never the only thing that marks a link as external (the arrow is always there with it), and a link without one loses nothing a person needs. It is a picture someone else drew, so its contrast against the surface is not the design system's to hold; a picture that cannot be seen on a dark or a light surface is given a ground where it is made, not by the link.
- A link calls no one. It draws only what the product gave it and reaches no other site before the person follows it (LNK-35): reading a page that links to a site tells that site nothing.
- The target. A link inside a sentence or a line of text takes WCAG 2.5.8's exception for inline targets: its hit area is its text, and extending it would take presses meant for the lines above and below. A link that stands by itself (standalone) and a link that is a glyph alone are not in a sentence, so their hit area is extended to sys.target without changing what is drawn (LNK-17); the product leaves sys.target.spacing between two of them, or lets their rows be a target high.
- A link is not a button. What leads nowhere and does something on the page is a Button — the text variant where it should read as quietly as text — and it is activated by Space as well as Enter. A link is never given a press handler in place of a destination (LNK-21).
- No visited state (LNK-20). A product whose content is a list of places people work through (search results, a reading list) marks what was opened from its own data, with a Tag or a glyph, which every platform can draw and assistive technology can read.
- The current link stays a link: it can be focused and followed, and leads to the top of the page the person is on. It is told from its neighbours by having no underline and a heavier weight, and by its state for assistive technology. A set that should not let its current item be followed (the last item of a trail) draws it as text, not as a link.
- A disabled link is not in the focus order, as a disabled Button is not. Where people must learn why a place cannot be reached, say so in text beside it.
- A link does not hold another link, a button or any other control, and is not placed inside one. Inside an element that is pressed as a whole (a link card, a list item with a destination) the text is that element's, not a second link.
- Text must remain readable at 200% text size: the link is text and grows and wraps with it; nothing about it has a fixed size (LNK-23).
- Contrast in the default system: sys.color.link on every surface role is held to 4.5:1 (7:1 in the high-contrast schemes) by the token invariants, and sys.color.inverse-link on sys.color.inverse-surface likewise. On the quiet containers (secondary-container and the four status containers) the link color measures 4.6:1 or more in every scheme today; that pair is not yet an invariant. The focus ring is held to 3:1 against every surface.
- How a state looks is a value decision of the active design system (a state-layer mix in Tanrei, a dim or no hover at all elsewhere). The link reads the state's tokens and never computes the effect itself.
生成自 specs/link.spec.json, tokens/sys/measure.tokens.json
- 它就是浏览器自己的链接：链接角色、用 Enter 前往、上下文菜单、在新标签页中打开，以及没有脚本也能用的链接。
- 在默认系统里，下划线把它与旁边的文本区分开，不依赖颜色，在每种配色方案下都是如此。在强制颜色模式下，无论选择了什么都会绘制下划线。
- 外部链接只有一条描述，在名称之后朗读：新标签页用
aria-description，否则用外部链接的那段文字。箭头和网站的图标对辅助技术隐藏。 - 键盘焦点环画在链接在每一行上的那一段周围。
- 独立链接和只有一个字形的链接会把点击区域扩展到最小目标。句子里的链接只占自己的文字。
- 标记以及标签旁边的字形对辅助技术隐藏。
- 有包里的脚本时，在新标签页中打开的链接会得到
noopener，调试构建会报告缺少名称、缺少描述，以及不是目的地的地址。它还会报告句子里静止时没有下划线、且与所在文本的对比度不到 3:1 的链接，没有文字的外部链接（每个页面报告一次），以及从另一个源加载的网站图标。
- 用
aria-label给只有一个字形的链接命名，并给每个字形加上aria-hidden="true"。 - 用
aria-description以你的产品的语言说明链接会在新标签页中打开。Tanrei 不自带任何文字。 - 禁用的链接写成不带
href的锚元素，并加上role="link"和aria-disabled="true"。它会离开焦点顺序，所以请在旁边用文字说明为什么这个地方无法到达。 - 在指明用户当前所在页面或章节的链接上设置
aria-current。 - 在连续文本里，只有当链接颜色与文本颜色的对比度达到 3:1 或更高、并且与表面的对比度仍有 4.5:1 时，才使用
hover和never。文本接近黑色、表面接近白色时，这只是中间色调里很窄的一段。 - 用文字说明链接会离开本站：在链接上写
aria-description，或者使用你为所有外部链接设置一次的那段文字。Tanrei 不自带任何文字。对于既是外部链接又在新标签页中打开的链接，要让这一条描述把两件事都说到。 - 网站的图标写成
alt=""。它是装饰：给链接命名的是标签，标出它的是箭头。