Link 使用手册

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

在正文、说明和导航中提供清晰的文字链接，支持箭头等视觉形式，表达可继续访问的内容。

使用选择

用于导航到地址或资源。即时动作使用 Button；提供真实 href，不能用占位地址伪装按钮。

• 提供真实 href，target / rel 控制打开方式；disabled 表达不可用状态。

• lines、tooltip 和 onTruncate 控制截断提示；parts 只配置内置 Tooltip。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { Link } from '@snowui-design-system/components';</script> <Link href="/components/quick-start" target="_top">Get started with SnowUI</Link>

API

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

内置组件双模式

• parts.Tooltip：配置单行截断时的内置 Tooltip。

• 自定义提示结构时使用外置 Tooltip 组合；显式 Props 高于 part。

Link 是独立的 文字链接组件。按钮外观但点击后跳转的场景继续使用 <Button href>；正文文字链接、带文字箭头链接与外链图标链接使用 <Link>。

功能概览

• 所有变体默认 color="Black40"，hover 变为 Black100；color="Black100" / "Black" 反向变为 Black40；Indigo 等其他颜色 hover 变为 Black100。

• arrow：Figma 样式 2。默认颜色文字 + 内置 ArrowUpRight trailing Icon；文字 hover 遵守统一颜色规则，装饰箭头使用 currentColor × opacity: 0.4 -> 1。

• external：Figma 样式 3。默认颜色文字 + 内置 ArrowSquareOut trailing Icon；文字 hover 遵守统一颜色规则，Icon 使用 currentColor × opacity: 0.4 -> 1。

• hoverColor：可传入任意 CSS 颜色；传 false 时 hover 不变色。

• underline：支持常态下划线、仅 hover 下划线、常态显示但 hover 隐藏，以及不显示下划线。默认不显示。

• lines={1}：启用单行截断；仅在真实溢出时自动显示 Tooltip，完整链接文字来自共享 TruncationController。

• external 内置 trailing Icon 可由外置直系 as="trailing" 替换。

文字截断

Link 复用 通用 TruncationController 与 fitTextToElement()，不自行创建尺寸观察器。lines={1} 时控制器测量文字层并判断真实截断状态；可见前缀按实际字体宽度拟合，英文等字母文字只保留完整单词，单个单词放不下时只显示省略符；中日韩文字可退回 Unicode 字素边界，因此不会出现半个字或组合字符。显式 … 作为可见文字的行内尾部渲染，与最后一个完整单词 / 字之间没有额外间距。

<Link href="/docs" lines={1} class="max-w-80">    一段超过可用宽度的完整文档链接</Link> <Link href="/docs" variant="external" lines={1} tooltip={false} class="max-w-80">    不显示截断 Tooltip 的外链</Link>

布局模型

主布局模型：槽位宿主布局（三槽位：leading / content / trailing）。

通过 <Frame row> 输出 data-auto-layout，复用 auto-layout.css（源码参考：components/src/styles/auto-layout.css） 的三槽位布局。默认文字作为 Content；external 变体的内置 ArrowSquareOut 作为 trailing。Snippet 中的外置直系 as="leading" / as="trailing" 会投影回 Link 根层，保持 Frame 对直系槽位的 Grid 落列、水平居中与统一 gap 规则。Link 根通过 [data-auto-layout] 组件级确权，将公共槽位 gap 保持为至少4 CSS px，默认首选 var(--gap-1)；含附件或单行截断时复用Frame singleLine，纯文字且未启用截断时保留原文字流。长标签显式使用 lines={1}，复用Link已有截断／全文提示。外置 Icon 保留自身尺寸，未传 size 时使用 Icon 默认的 16px。

内置图标与替换

<Link href="/docs" variant="external">打开文档</Link> <Link href="/docs" variant="external">    打开文档    <Icon as="trailing"><ArrowUpRight /></Icon></Link>

下划线

<Link href="/docs" underline="always">常态下划线</Link><Link href="/docs" underline="hover">悬停时出现</Link><Link href="/docs" underline="until-hover">悬停时隐藏</Link><Link href="/docs">默认无下划线</Link>

下划线只应用于链接文字。arrow 与 external 的 Icon 均不绘制下划线。

Hover 颜色

<Link href="/docs" hoverColor="#ff4747">自定义 hover 色</Link><Link href="/docs" hoverColor={false}>hover 不变色</Link>

未传 hoverColor 时，颜色由 color 决定，与 variant 无关。主题切换时 Black40 / Black100 跟随主题。原有 CSS 颜色 override 仍作为直接样式逃生口；需要自动 hover 规则时使用 color，显式 hoverColor 高于自动结果：

arrow 的默认 Icon、external 的默认 Icon 与外置 trailing Icon 均继承文字颜色，不单独切换颜色源。它们按照无底色轻量 Icon 规范使用 opacity: 0.4 -> 1 表达 hover 活跃度。

布局变量链

Link 根节点默认使用 width: fit-content; max-width: 100%，因此在 column / stretch 父容器内仍保持 Hug，trailing 会随文字宽度移动。外部显式 width、w-full 或 inline style 可以覆盖。