VXUI 2

官网：ui.vx.link  |  GitHub：tmplink/vxui_react  |  English Version

一套适用于后台、运营台、仪表盘和内部工具的通用 React UI 组件库。基于 CSS 自定义属性（设计令牌）做主题化，无障碍支持（焦点陷阱、键盘导航、ARIA 语义）由库内自行实现。

安装

npm install vxui-re

react 和 react-dom（均要求 ^19.0.0）需要由宿主应用提供。

快速开始

import ReactDOM from 'react-dom/client';
import {
  ThemeProvider,
  ToastProvider,
  themePresets,
  AppShell,
  Button,
  Card,
  CardContent,
  CardHeader,
  CardTitle,
  Input,
} from 'vxui-re';
import 'vxui-re/styles.css';
// 可选 —— 仅当整个页面都由 VXUI 构成时引入（设置 body 背景 / 字体 / #root 高度）：
// import 'vxui-re/global.css';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <ThemeProvider themes={themePresets} defaultTheme="light">
    <ToastProvider>
      <AppShell
        brand="Acme Ops"
        title="概览"
        navSections={[
          {
            title: '工作空间',
            items: [{ key: 'overview', label: '概览', active: true }],
          },
        ]}
        headerActions={<Button size="sm">新建项目</Button>}
      >
        <Card>
          <CardHeader>
            <CardTitle>队列健康</CardTitle>
          </CardHeader>
          <CardContent>
            <Input label="搜索订单" placeholder="PO-1024" />
          </CardContent>
        </Card>
      </AppShell>
    </ToastProvider>
  </ThemeProvider>,
);

主题定制

VXUI 2 使用 CSS 自定义属性。只需覆盖少量变量即可几分钟内完成品牌化改造：

:root {
  --vx-primary: #7c3aed;
  --vx-primary-strong: #6d28d9;
  --vx-primary-soft: rgba(124, 58, 237, 0.1);
  --vx-bg: #f8fafc;
  --vx-surface: #ffffff;
  --vx-border: #e2e8f0;
  --vx-text: #0f172a;
  --vx-radius: 10px;
  --vx-sidebar-width: 240px;
}

<html> 带 data-theme="dark"（ThemeProvider 写的就是它）或 Tailwind 习惯的 class="dark" 时进入深色。显式 data-theme 始终优先，所以 class="dark" 是给无 JS / 挂载前的页面用的。

运行时创建自定义主题：

import { ThemeProvider, createTheme, themePresets } from 'vxui-re';

const themes = {
  ...themePresets,
  ocean: createTheme('dark', {
    label: 'Ocean',
    tokens: {
      '--vx-primary': '#38bdf8',
      '--vx-primary-strong': '#0ea5e9',
      '--vx-primary-soft': 'rgba(56, 189, 248, 0.16)',
      '--vx-bg': '#06131f',
      '--vx-surface': '#0d2236',
    },
  }),
};

<ThemeProvider themes={themes} defaultTheme="ocean">
  <App />
</ThemeProvider>

通过 useTheme() 读取当前主题并调用 setTheme('ocean') 在线切换。

避免首帧闪色

ThemeProvider 在 effect 里应用 token，也就是浏览器首次绘制之后，因此偏好深色的页面会先闪一下亮色 base。内置 preset 同时以静态 :root[data-theme-name='…'] 规则发布，所以只要 React 挂载前给 <html> 打上属性即可：

import { themeBootstrapScript } from 'vxui-re';

themeBootstrapScript({ storageKey: 'vxui-re-theme', defaultTheme: 'black-gold' });
// → '(function(w,m){…})(window,{"dark":"dark",…});'

<ThemeProvider scoped themes={…} defaultTheme="dark"> 只给这棵子树换主题（例如亮色页面里的一块暗色预览区）：它渲染一个 data-vx-theme-scope 容器，不碰 <html>；portal 到 <body> 的浮层（对话框、下拉、Popover、Tooltip、Toast）仍沿用页面级主题。

<ThemeProvider defaultTheme="system">（themeBootstrapScript 传同样的值）表示跟随系统配色（prefers-color-scheme）；此时 useTheme() 的 theme 为 'system'，实际生效的是 resolvedTheme / mode。

把这一行贴进 <head>（SSR 模板里直接生成）。storageKey / defaultTheme 必须与 <ThemeProvider> 的 props 一致，否则首帧显示回退主题再纠正。自己用 createTheme 定义的主题没有静态规则，只能在挂载后生效。

组件列表

布局与导航

AppShell（应用框架）、Shell / ShellSidebar / ShellContent（底层布局）、NavigationMenu（导航菜单）、Breadcrumb（面包屑）、Pagination（分页）、Tabs（标签页）、Menubar（菜单栏）、Stepper（步骤）、Resizable（可调整面板）、ScrollArea（滚动区域）、Separator（分隔线）

按钮与操作

Button（按钮）、Toggle（切换）、SegmentedControl（分段控制器）、DropdownMenu（下拉菜单）、ContextMenu（右键菜单）

表单与输入

Input（输入框）、Textarea（多行文本）、Checkbox（复选框）、CheckboxGroup（复选框组）、RadioGroup（单选组）、Radio（单选按钮）、Switch（开关）、Slider（滑块）、NumberInput（数字输入）、TagInput（标签输入）、Rating（星级评分）、DatePicker（日期选择）、ColorPicker（颜色选择）、Select（单选下拉）、MultiSelect（多选下拉）、PinInput（PIN 输入）、TimePicker（时间选择）、Form（表单）、FileUpload（文件上传）

浮层与弹出

Dialog（模态框）、Sheet（侧边面板）、Popover（弹出内容）、Tooltip（提示）、HoverCard（悬浮卡片）、CommandPalette（命令面板）

反馈与状态

Toast（轻通知）、Notification（全局通知）、Alert（内联警告）、Progress（进度条）、Spinner（加载指示器）、Skeleton（骨架屏）、EmptyState（空状态）、Result（结果页）

数据展示

Table（表格）、Card（卡片）、Badge（徽章）、Avatar（头像）、Accordion（折叠面板）、Calendar（日历）、Image（图片）、Carousel（轮播）、TreeView（树形列表）、Timeline（时间线）、Descriptions（描述列表）

排版

Heading（标题）、Text（文本）、Label（标签）、CodeBlock（代码块）、Article（文章布局）

移动端

MobileShell（移动端框架）、BottomNav（底部导航）、MobileList（移动端列表），另有已废弃的 MobileDrawer（左右侧滑抽屉，请改用 Sheet side="left"）与 ActionSheet（请改用 Sheet side="bottom"）。移动端组件与其他组件一样从根入口导出，不存在 vxui-re/mobile 子路径。

工具

ThemeProvider（主题提供者）、useTheme（主题钩子）、Responsive（响应式条件渲染）、I18nProvider（语言提供者）、useI18n（语言钩子）、LanguageSwitcher（语言切换）、VXUIProvider（顶层组合提供者）

设计原则

• 令牌优先主题化 — 所有视觉决策都使用 CSS 变量。不依赖 Tailwind，不使用 CSS-in-JS。
• 默认无障碍 — 浮层与交互组件内置键盘导航、焦点陷阱与 ARIA 语义；Switch、Tabs、Toast 额外构建在 Radix UI 基元之上。
• 无全局副作用 — 元素级 reset（button、input、a、img…）只作用于 VXUI 组件内部（vx-* / vxm-* 元素及其后代）；不碰 <html> / <body>，需要时显式引入 vxui-re/global.css。
• 移动优先响应式 — 窄视口下侧边栏自动折叠为浮层。移动端组件与其他组件同样从根入口导出。
• 粘性受控 — value 一旦出现过定义（首帧，或之后任意一次渲染）就永远按受控处理：之后传 undefined 表示清空，不会回落到 defaultValue（defaultValue 只服务非受控用法）。因此 useState<string>() 风格的宿主也能用 —— 组件跟随它第一次给出的值。
• 静态优先的 CSS — base token 与全部内置 preset 都在同一个静态样式表里，不靠 JS 也能正确显示；ThemeProvider 只在挂载后补内联 token，用于支持自定义 createTheme() 配色（见「避免首帧闪色」）。

本地开发

npm install
npm run dev          # 启动开发服务器
npm run typecheck    # TypeScript 类型检查
npm run build        # 构建组件库（用于 npm publish）
npm run test         # 运行测试
npm run security:audit  # 安全审计

许可证

Apache-2.0

框架预置能力

表单控件内置清除、密码切换、字符计数、自动高度与校验关联；选择器支持分组、远程搜索及数量限制。CheckboxGroup / RadioGroup 支持原生表单字段名。Table 提供分页、合计、展开、固定列与空值占位；变化数据请使用 rowKey + selectedKeys，避免按下标保存选择。Dialog / Sheet 支持异步确认和重复提交防护，浮层内置键盘导航、焦点归还与视口避让。完整 API 见 llms.txt 和中英文交互文档。