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，物件作為 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 會正確處理。資源後綴偵測優先於外部連結判斷。