QueryTabs 组件

一个支持多种模式（Tabs、Radio.Group、Segmented）且具备 URL 记忆功能的选项卡组件。

npm i @hzab/query-tab

何时使用

当需要在不同形式的选项卡间切换，并且希望保持选中状态与 URL 参数同步时使用。

代码演示

基本使用

import QueryTabs from '@hzab/query-tab';

const items = [
  { label: '标签一', key: '1' },
  { label: '标签二', key: '2', disabled: true },
  { label: '标签三', key: '3' },
];

function App() {
  return (
    <QueryTabs 
      items={items} 
      defaultActiveKey="1" 
      onChange={(key) => console.log(key)}
    />
  );
}

不同模式

// Tabs 模式（默认）
<QueryTabs items={items} mode="tabs" />

// Radio 按钮模式
<QueryTabs items={items} mode="radio" />

// Segmented 模式
<QueryTabs items={items} mode="segmented" />

主题定制

// 使用字符串简写（仅设置主色）
<QueryTabs items={items} theme="#ff0000" />

// 使用完整主题对象
<QueryTabs 
  items={items} 
  theme={{
    primary: '#ff0000',
    selectedText: '#fff',
    selectedBg: '#ff0000',
    defaultText: '#333',
    defaultBg: '#f5f5f5'
  }} 
/>

选中项记忆

// 开启 URL 记忆
<QueryTabs 
  items={items} 
  appendUrlQuery={true}
  queryKey="myTab"
/>

// 自定义 URL 参数结构
<QueryTabs 
  items={items} 
  appendUrlQuery={true}
  appendUrlQueryKey="filters"
  queryKey="activeTab"
/>

API

QueryTabs

| 参数 | 说明 | 类型 | 默认值 | 版本 | |-------------------|----------------------------------------------------------------------------|-------------------------------------------------|-------------|-------| | items | 选项卡配置项 | ItemsType[] | - | 1.0.0 | | mode | 组件模式 | 'tabs' | 'radio' | 'segmented' | 'tabs' | - | 1.0.0 | | className | 内部控件样式类名 | string | - | 1.0.0 | | style | 内部控件样式 | React.CSSProperties | - | 1.0.0 | | wrapperClassName | 外层容器样式类名 | string | - | 1.0.0 | | wrapperStyle | 外层容器样式 | React.CSSProperties | - | 1.0.0 | | activeKey | 当前选中项（受控） | string | - | 1.0.0 | | controlled | 是否开启完全受控状态，默认不开启(完全受控后，首次渲染组件将不会取url中的参数来设置tabs的默认选中项，而是由外部传入的activeKey决定) | boolean | false | 1.0.0 | | defaultActiveKey | 默认选中项 | string | - | 1.0.0 | | theme | 主题配置 | string | ThemeTokens | 1.0.0 | | defaultActiveKey | 默认选中项 | string | - | 1.0.0 | | onChange | 切换回调 | (activeKey: string) => void | - | 1.0.0 | | appendUrlQuery | 是否开启 URL 记忆 | boolean | true | 1.0.0 | | appendUrlQueryKey | URL 参数的父级键名 | string | 'tabsKeys' | 1.0.0 | | queryKey | URL 参数的子级键名 | string | 'tab' | 1.0.0 | | tabsProps | Tabs 模式专属属性 | Omit<TabsProps, ...> | - | 1.0.0 | | radioProps | Radio 模式专属属性 | Omit<RadioGroupProps, ...> | - | 1.0.0 | | segmentedProps | Segmented 模式专属属性 | Omit<SegmentedProps, ...> | - | 1.0.0 |

ItemsType

| 参数 | 说明 | 类型 | 默认值 | |----------|-------|-----------------|-----| | label | 选项卡标签 | React.ReactNode | - | | key | 唯一标识 | string | - | | disabled | 是否禁用 | boolean | - | | children | 选项卡内容 | React.ReactNode | - |

ThemeTokens

| 参数 | 说明 | 类型 | 默认值 | |--------------|--------------|--------|-----------------------------------| | primary | 主题主色（边框/强调色） | string | var(--ant-primary-color, #1677ff) | | selectedText | 选中文本色 | string | var(--qt-primary, primary) | | selectedBg | 选中背景色 | string | #ffffff | | defaultText | 默认文本色 | string | #4E5969 | | defaultBg | 默认背景色 | string | #ffffff |

注意事项

1. URL 记忆功能：需要同时提供 appendUrlQuery={true} 和 queryKey（参见第2条） 参数才能生效
2. 同一个页面使用多次QueryTabs组件时appendUrlQueryKey和queryKey必须有一个不相同，建议是appendUrlQueryKey不变queryKey独立设置，否则key相同会覆盖
3. 受控模式：当提供 activeKey 时，组件为受控模式，需要自行管理状态
4. 主题定制：支持 CSS 变量（如 --my-color 或 var(--my-color)）和常规颜色值
5. 模式切换：不同模式下的专属属性请使用对应的 *Props 参数传递