@xiaokai/qb-ui

QB小工具 React 组件库 — 提供按钮、选择器、输入框、布局、色彩系统、日夜模式等组件和工具。

安装

npm install @xiaokai/qb-ui
# or
yarn add @xiaokai/qb-ui
# or
pnpm add @xiaokai/qb-ui

Peer Dependencies: react >= 17.0.0, react-dom >= 17.0.0

快速开始

// 引入样式（在入口文件中引入一次即可）
import '@xiaokai/qb-ui/styles';

// 引入组件
import { QBButton, QBCard, QBInput, useDarkMode } from '@xiaokai/qb-ui';

function App() {
  const { scheme, toggle } = useDarkMode();

  return (
    <QBCard>
      <h2>当前模式: {scheme}</h2>
      <QBInput placeholder="请输入内容" />
      <QBButton variant="primary" size="l" onClick={toggle}>
        切换日夜模式
      </QBButton>
    </QBCard>
  );
}

组件

QBButton

按钮组件，支持 5 种类型和 4 种尺寸。

import { QBButton } from '@xiaokai/qb-ui';

// 类型: primary | secondary | tertiary | white | progress
// 尺寸: xl | l | m | s
<QBButton variant="primary" size="l">主要按钮</QBButton>
<QBButton variant="secondary" size="m">次要按钮</QBButton>
<QBButton variant="tertiary" size="s">三级按钮</QBButton>
<QBButton variant="progress" size="l" progress={60}>下载中</QBButton>
<QBButton variant="primary" size="l" block>全宽按钮</QBButton>

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | variant | 'primary' \| 'secondary' \| 'tertiary' \| 'white' \| 'progress' | 'primary' | 按钮类型 | | size | 'xl' \| 'l' \| 'm' \| 's' | 'l' | 按钮尺寸 | | block | boolean | false | 是否全宽 | | progress | number | - | 进度值 (0-100) |

QBInput

输入框组件，支持验证状态和内联标签。

import { QBInput } from '@xiaokai/qb-ui';

<QBInput placeholder="请输入内容" />
<QBInput label="姓名" placeholder="请输入姓名" />
<QBInput status="error" placeholder="错误状态" />
<QBInput status="success" placeholder="成功状态" />
<QBInput type="number" placeholder="数字输入" />

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | status | 'default' \| 'error' \| 'success' | 'default' | 验证状态 | | label | string | - | 内联标签文本 |

QBSelector

选择器组件，支持线框和面性两种风格。

import { QBSelector, QBSelectorGroup } from '@xiaokai/qb-ui';

const options = [
  { label: '男', value: 'male' },
  { label: '女', value: 'female' },
];

// 线框选择器
<QBSelector variant="outline" label="性别" value={val} options={options} onChange={setVal} />

// 面性选择器组
<QBSelectorGroup cols={3}>
  <QBSelector variant="solid" label="选项1" />
  <QBSelector variant="solid" label="选项2" />
  <QBSelector variant="solid" label="选项3" />
</QBSelectorGroup>

QBCard

卡片容器组件。

import { QBCard } from '@xiaokai/qb-ui';

<QBCard>卡片内容</QBCard>

QBModule

模块组件，包含标题区域和内容区域。

import { QBModule } from '@xiaokai/qb-ui';

<QBModule title="模块标题" subtitle="副标题描述">
  <p>模块内容</p>
</QBModule>

布局组件

import { QBContainer, QBRow, QBCol } from '@xiaokai/qb-ui';

<QBContainer>
  <QBRow>
    <QBCol span={6}>左半部分</QBCol>
    <QBCol span={6}>右半部分</QBCol>
  </QBRow>
</QBContainer>

QBDivider

分割线组件。

import { QBDivider } from '@xiaokai/qb-ui';

<QBDivider />
<QBDivider direction="vertical" />

Hooks

useDarkMode

日夜模式管理 Hook。自动检测系统偏好，支持手动切换和持久化。

import { useDarkMode } from '@xiaokai/qb-ui';

const { scheme, isDark, toggle, set, reset } = useDarkMode();

// scheme: 'light' | 'dark'
// isDark: boolean
// toggle(): 切换模式
// set('dark'): 设置指定模式
// reset(): 重置为系统偏好

useIframeHeight

iframe 高度自适应 Hook。自动监听内容变化并通知父窗口调整高度。

import { useIframeHeight } from '@xiaokai/qb-ui';

function App() {
  const { updateHeight } = useIframeHeight();
  // 自动监听 DOM 变化、窗口大小变化、图片加载等
  return <div>内容</div>;
}

useQueryParser

URL Query 解析 Hook。从父页面或当前页面 URL 提取搜索关键词。

import { useQueryParser, extractFromQuery, containsKeyword } from '@xiaokai/qb-ui';

const { query } = useQueryParser();
// query: 从 URL 的 keyword 或 query 参数获取

const date = extractFromQuery(query, /(\d{4}-\d{2}-\d{2})/);
const hasKeyword = containsKeyword(query, ['计算器', '换算']);

工具函数

CryptoUtils

XOR 加解密工具。

import { encryptApiToken, decryptApiToken } from '@xiaokai/qb-ui';

const encrypted = encryptApiToken('my-secret-token');
const decrypted = decryptApiToken(encrypted);

TCMData

中药百科数据库，支持 5 种中药数据查询。

import { TCMData, recognizeHerb, getAllHerbs } from '@xiaokai/qb-ui';

const herb = recognizeHerb('黄芪的功效');
// { id: 'huangqi', name: '黄芪', functions: [...], ... }

const allHerbs = getAllHerbs();

CSS 样式类

引入样式后可直接使用 CSS 类名：

色彩系统

支持日间/夜间模式自动切换（通过 data-color-scheme 属性）。

<!-- CSS 变量 -->
<div style="color: var(--qb-primary)">品牌色文本</div>
<div style="background: var(--qb-bg-grey)">灰色背景</div>

<!-- 工具类 -->
<span class="qb-text-primary">主文本</span>
<span class="qb-text-secondary">次要文本</span>
<span class="qb-text-danger">警示文本</span>

排版

<h1 class="qb-h1-bold">标题 24px medium</h1>
<p class="qb-body2">正文 14px regular</p>
<span class="qb-caption1">辅助文字 12px</span>
<span class="qb-truncate">单行省略...</span>
<span class="qb-line-clamp-2">多行省略...</span>

布局

<!-- 栅格 -->
<div class="qb-row">
  <div class="qb-col-6">50%</div>
  <div class="qb-col-6">50%</div>
</div>

<!-- 间距 -->
<div class="qb-mt-12 qb-px-16">margin-top: 12px; padding: 0 16px</div>

<!-- Flex -->
<div class="qb-flex qb-justify-between qb-align-center qb-gap-8">
  <span>左</span><span>右</span>
</div>

按钮

<button class="qb-btn qb-btn-l qb-btn-primary">主要按钮</button>
<button class="qb-btn qb-btn-m qb-btn-secondary">次要按钮</button>
<button class="qb-btn qb-btn-s qb-btn-tertiary">三级按钮</button>

CSS 变量一览

| 变量 | 日间值 | 说明 | |------|--------|------| | --qb-primary | #205AEF | 品牌主色 | | --qb-danger | #F44837 | 危险色 | | --qb-success | #0BB861 | 成功色 | | --qb-warning | #FF8A14 | 警告色 | | --qb-text-a1 | #242424 | 主文本 | | --qb-text-a2 | #666666 | 次要文本 | | --qb-text-a3 | #8F8F8F | 辅助文本 | | --qb-text-a4 | #B3B3B3 | 占位文本 | | --qb-bg-grey | #F6F7FA | 页面背景 | | --qb-bg-white | #FFFFFF | 卡片背景 | | --qb-bg-frame | #F5F5F5 | 框架背景 | | --qb-line | rgba(0,0,0,0.08) | 分割线 |

发布

# 构建
npm run build

# 发布到 npm
npm publish --access public

License

MIT