Tabs 標籤頁

選項卡切換元件，支援受控 / 非受控、卡片 / 線條兩種外觀、頁籤關閉與新增、完整鍵盤導覽。

基礎用法

基礎用法

水墨暈染，氣韻生動。

丹青設色，金碧輝映。

留白處皆是意境（禁用態）。

工筆細描，毫髮畢現。

寫意揮灑，不拘形似。

import { useState } from 'react'
import { LhTabs, LhTabPane } from '@lh-ui/react'

export default function Demo() {
  const [value, setValue] = useState('ink')

  return (
    <LhTabs value={value} onChange={(name) => setValue(name)}>
      <LhTabPane name="ink" label="水墨">
        水墨晕染，气韵生动。
      </LhTabPane>
      <LhTabPane name="danqing" label="丹青">
        丹青设色，金碧辉映。
      </LhTabPane>
    </LhTabs>
  )
}

Tabs Props

屬性	說明	型別	可選值	預設值
value	當前啟用頁籤的 name（受控）	string	—	—
defaultValue	當前啟用頁籤的 name（非受控預設值）	string	—	—
type	外觀	'line' | 'card'	—	'line'
closable	頁籤是否可關閉	boolean	—	false
addable	是否顯示新增按鈕	boolean	—	false
tabPosition	頁籤位置	'top' | 'bottom'	—	'top'
sx	快速版面配置屬性	SxProps	—	—

TabPane Props

屬性	說明	型別	預設值
name	頁籤唯一標識（作為穩定鍵，不建議動態修改）	string	—
label	頁籤標題	ReactNode	—
disabled	是否停用	boolean	false
children	頁籤內容	ReactNode	—

Tabs 事件

事件	說明	回呼簽名	Vue 對照
onChange	啟用頁籤變化時觸發	(name: string) => void	@change
onRemove	關閉頁籤時觸發（頁籤的顯隱由業務側控制）	(name: string) => void	@remove
onAdd	新增按鈕點選時觸發	() => void	@add

受控 / 非受控

傳 value 即受控，傳 defaultValue 走非受控內部態。兩種模式下 onChange 都會觸發。刪除啟用頁籤時，非受控模式自動切到相鄰可用頁籤（對齊 plus 的 getNameAfterRemove）；受控模式交由業務側在 onRemove 裡處理。

子節點限制

children 必須直接是 LhTabPane（可用 .map 渲染，可用 Fragment 平鋪包裹，但不可被自訂元件包裹）—— 父元件靠 Children.forEach 下鑽收集頁籤記錄，自訂包裹層會導致收集失敗。

鍵盤互動

遵循 APG tabs pattern：焦點在頁籤按鈕上時，ArrowRight / ArrowLeft（縱向為 ArrowDown / ArrowUp）在可用頁籤間移動並啟用，跳過停用項；Home / End 跳到首 / 末項；Delete / Backspace 關閉當前頁籤（需 closable）。僅啟用頁籤 tabindex=0，其餘為 -1（roving tabindex）。

無障礙

頁籤欄為 role="tablist"，頁籤為 role="tab" 並帶 aria-selected / aria-controls，面板為 role="tabpanel" 並帶 aria-labelledby，id 由 useId() 生成、SSR 穩定。非啟用面板以 hidden 屬性移出無障礙樹。

ref

forwardRef<HTMLDivElement> —— 根元素。LhTabPane 轉發 HTMLDivElement。

樣式

import '@lh-ui/react/theme.css'
import '@lh-ui/react/style/tabs'