SwLink

SwLink 是框架提供的统一链接组件，自动区分资源文件链接与路由链接，无需手动判断该用 <a> 还是 <NuxtLink>：

资源文件后缀（pdf / zip / mp4 / apk 等）→ 渲染原生 <a href>，由浏览器处理下载/预览
其他路径 → 渲染 <NuxtLink>，走 Nuxt 路由系统

同时自动处理安全属性：target="_blank" 时补充 rel="noopener noreferrer"；外链（https://）额外加 nofollow。

何时用 SwLink

页面 / 资源跳转默认一律 SwLink（渲染真实 <a href>，SEO / 爬虫 / a11y 友好）。仅命中下列具名例外才用别的：

命中	用
可信外链要传 SEO 权重（dofollow）	原生 `<a href rel="noopener">`（SwLink 对 https 外链强制 `nofollow`）
要 NuxtLink `custom` 插槽做完全自定义渲染	`<NuxtLink custom v-slot>`
同页锚点 `#id`	原生 `<a href="#id">`
不产生 URL 跳转的纯交互（切换 / 弹窗 / 提交）	`SwButton`（那不是链接）

反模式：① @click + router.push / navigateTo 做本可 <a href> 的页面跳转 → 丢 SEO；② <a @click>（无 href）做纯交互 → 丢 a11y。完整选型见框架开发规范「链接 / 导航选型」。

基础用法

加载中...

外链与 rel 自动处理

加载中...

禁用态

加载中...

资源文件链接

传入带资源后缀的路径，组件自动渲染为原生 <a>：

<!-- 自动渲染为 <a href="/files/guide.pdf" target="_blank"> -->
<SwLink to="/files/guide.pdf" target="_blank">下载 PDF</SwLink>

<!-- 视频文件，浏览器直接播放/下载 -->
<SwLink to="/video/intro.mp4" target="_blank">查看视频</SwLink>

带查询参数的路由链接

加载中...

通过 params 传入查询参数：

<!-- 对象形式 → /search?kw=nuxt&page=1 -->
<SwLink to="/search" :params="{ kw: 'nuxt', page: 1 }">搜索</SwLink>

<!-- 字符串形式 → /player?url=https://... -->
<SwLink to="/player" params="https://cdn.example.com/video.m3u8">播放</SwLink>

默认视觉与覆盖

加载中...

SwLink 自带文字链接默认视觉：主色（var(--primary)）+ 无下划线 + hover 亮度反馈（filter: brightness(0.92)，house style）。

改链接颜色 → 设 CSS 变量 --sw-link-color（在链接或任意祖先上），按变量级联生效、与规则特异性 / 加载顺序无关：

<style scoped>
/* ✅ 换色走变量：页脚弱化灰链接、深色 banner 上的白字链接等 */
.sw-app-footer {
  --sw-link-color: var(--muted-foreground);
}
/* 或直接设在链接元素上 */
.my-link {
  --sw-link-color: var(--primary-foreground);
}
</style>

⚠️ 别用 .sw-link { color: … } 直接覆盖颜色——它与框架默认 .sw-link 规则等特异性 (0,2,0)，胜负由 CSS 源顺序决定，而 nuxt dev(HMR) 与 nuxt build(Vite 打包) 顺序不一致 → 同一份代码 dev / prod 链接色会翻转（framework#170，缘起 yc001 页脚链接）。换色一律走 --sw-link-color。

其余视觉（如常显下划线，长段正文内嵌链接 WCAG 1.4.1 色弱可辨）的 scoped 覆盖需更高特异性，避免同样的等特异性赌顺序：

<style scoped>
.my-article .sw-link {
  text-decoration: underline;
}
</style>

按钮样导航不进组件：业务自套按钮 class（与 SwButton 零视觉哲学一致）。

Props

名称	类型	默认值	说明
`to`	`string`	`''`	跳转目标 URL 或路由路径
`target`	`'_self' \| '_blank'`	`'_self'`	打开方式
`title`	`string`	`''`	原生 title 属性（鼠标悬浮提示）
`params`	`Record<string, string \| number \| boolean> \| string`	`''`	查询参数；string 会包装为 query.url，object 作为 query
`track`	`LinkTrackProp`	`undefined`	内置埋点（opt-in，不传零行为），见下「内置埋点」

内置埋点（`:track`）

内容卡片 / 导航项的曝光与点击埋点可由组件自动上报，业务只填业务字段：

<SwLink to="/movie/123" :track="{
  exposure: { event: 'appPageitemExposure', payload: { item_id: '123', item_type: 'video', item_name: '片名', parent_item_id: '', page_key: 'home', page_name: '首页' } },
  click:    { event: 'appPageitemClick',    payload: { item_id: '123', item_type: 'video', item_name: '片名', parent_item_id: '', position: 1, page_key: 'home', page_name: '首页' } },
}">
  <MovieCard :movie="movie" />
</SwLink>

字段	时机	常用 event
`track.exposure`	进视口一次（IntersectionObserver ≥50% 可见，内部走 `useExposure`）	`appPageitemExposure` / `recommendListView`
`track.click`	点击时（fire-and-forget，不阻塞导航）	`appPageitemClick` / `recommendListClick` / `navigation`

event 限 WebSdkEvent 联合类型（typo 由 TS 拦截），由业务显式指定——同一张卡片在推荐流用 recommendList*、普通列表用 appPageitem*，组件不猜语义。
payload 业务字段原样透传；上报走 useTracker（tracker gate 关闭时静默 no-op）。
逃生舱：业务自有打点 SDK 不用 :track——原生 click 事件照常透传，曝光时机用 useExposure 自接。

Slots

插槽名	说明
`default`	链接文字或自定义内容

注意事项

资源后缀检测范围： pdf / zip / rar / docx / xlsx / pptx / jpg / png / gif / svg / xml / m3u8 / ts / key / mp4 / mp3 / webm / apk / json / gz / tar / mobileprovision / txt / exe。命中后缀时自动用 <a href>，否则用 <NuxtLink>。
rel 自动处理： target="_blank" 时自动补 rel="noopener noreferrer"；外链（https:// 开头）额外加 nofollow，无需手动设置。
外链路由： 对于 https:// 开头的外部 URL，<NuxtLink> 本身支持外链跳转，SwLink 会正确处理。资源后缀检测优先于外链判断。