villianjs-pro

React + TypeScript 业务组件库，基于 Ant Design / Pro Components，提供高频后台场景组件（表格、选择器、导入导出、列表、表单增强等）。

React + TypeScript component library built on Ant Design / Pro Components for admin dashboards and enterprise apps.

Features | 核心能力

• ProTable：增强表格（搜索、分页、列表/网格视图、操作栏）
• TabSelector：多 Tab 弹窗选择器（单选/多选）
• Imports：文件导入流程（上传、进度、结果、历史）
• Exports：文件导出流程（同步/异步、轮询状态）
• List.Container：分页卡片列表容器
• TreeSelect：树形选择器
• Image：支持缓存与过期控制的图片组件
• Button / ConfirmButton / ButtonGroup：按钮增强组件
• Card / Modal / CheckCard / Typography / Beyond：常用业务 UI 组件
• 内置工具：library、locale、hooks

Install | 安装

npm i villianjs-pro

Quick Start | 快速开始

推荐按子路径导入（villianjs-pro/{组件名}），只加载用到的组件，获得最优的体积与启动性能：

import React from "react";
import { ProTable } from "villianjs-pro/ProTable";
import { Button } from "villianjs-pro/Button";
import { Modal } from "villianjs-pro/Modal";
import { Imports } from "villianjs-pro/imports";
import { Exports } from "villianjs-pro/Exports";

export default function DemoPage() {
  return (
    <div>
      <Button type="primary">Action</Button>
      {/* more business components */}
    </div>
  );
}

也兼容根入口导入（会引入全部组件的模块图，打包后由 tree-shaking 裁剪，冷启动体积大于子路径方式）：

import { ProTable, Button, Imports, Exports, TabSelector } from "villianjs-pro";

可用子路径：./Beyond、./Button、./ButtonGroup、./Card、./CheckCard、./ConfirmButton、./Exports、./Form、./hooks、./images、./imports、./library、./List、./locale、./Modal、./ProTable、./Switch、./TabSelector、./Text、./tree-select（注意大小写，exports 精确匹配）。

Styles | 样式：零导入，自动生效

你不需要手动导入任何样式文件。 组件源码自己引用样式，打包器会随组件一起把 CSS 抽取并注入 <link rel="stylesheet"> —— 只要 import 了组件，样式就在：

import { Button } from "villianjs-pro/Button";
// ✅ 不需要、也不应该写 import "villianjs-pro/Button/style.css"

前置要求（vite / webpack / rspack / Next.js 默认均满足）：

1. 打包器需对 node_modules 下的 .module.css 启用 CSS Modules（各主流打包器的默认行为）；
2. 若你自定义过 css.modules / css-loader 配置，请确认它没有被 exclude: /node_modules/ 排除掉。

样式基于 antd v6 的 CSS 变量（var(--ant-*)）实现：主题切换（含暗色模式）由 ConfigProvider 统一驱动，组件无需重新构建。每个组件根节点都会挂上 antd 的 CSS 变量作用域类（css-var-*）， 所以变量一定能解析；且所有变量都带 fallback，万一作用域缺失也不会「全白」。

覆盖样式：请用语义类

组件内部的视觉类名带哈希（CSS Modules 生成），不保证稳定，不要拿它写业务样式。 组件同时保留了一套不哈希的语义类作为覆盖钩子：

| 组件 | 语义类 | | --- | --- | | Button / ButtonGroup | ant-vlian-button / ant-vlian-button-group | | Card | vlian-card、vlian-card_header、vlian-card_content、vlian-card_head-title | | ProTable | ant-vlian-table、ant-vlian-table-list、ant-vlian-table-view-switch、ant-vlian-table-pagination-* | | tree-select | ant-vlian-tree-select、ant-vlian-tree-select-trigger、ant-vlian-tree-select-content | | TabSelector | vlian-tab-modal |

/* 示例：把 ProTable 的视图切换按钮换成主题色 */
.ant-vlian-table-view-switch { color: var(--ant-color-primary); }

⚠️ 与 antd 自身类同名特异性（都是 (0,1,0)）时，谁生效取决于样式表顺序。需要压过 antd 时，请提高选择器特异性（例如 .my-page .ant-vlian-button），不要用 !important。

Components | 组件总览

Data Display & Interaction | 数据展示与交互

• ProTable
• List, ListContainer
• Card
• CheckCard
• TreeSelect
• TabSelector
• Beyond
• Typography

Workflow Components | 业务流程组件

• Imports, ImportContextProvider
• Exports
• ProForm

Basic UI | 基础 UI

• Button
• ConfirmButton
• ButtonGroup
• VaSwitch
• Modal
• Image

Utilities | 工具能力

• library（db / file / string / form / is / table 等）
• locale（zh-cn / en-us）
• hooks

Minimal Runnable Examples | 按组件最小可运行示例目录

建议在项目中维护一套最小示例目录，便于用户按组件快速检索、复制、运行。

Recommended minimal example structure for faster component discovery and copy-run usage.

examples/
  protable-basic/                # ProTable 基础分页与搜索 | Basic table with search & pagination
  tab-selector-basic/            # TabSelector 单选/多选 | Modal tab selector (radio/checkbox)
  imports-basic/                 # Imports 上传+进度+结果 | Import workflow demo
  exports-basic/                 # Exports 同步/异步导出 | Sync/async export demo
  list-container-basic/          # List.Container 分页卡片列表 | Paginated card list
  tree-select-basic/             # TreeSelect 树形选择 | Tree selection
  image-cache-basic/             # Image 缓存与过期 | Cached image with expire time
  button-confirm-basic/          # Button + ConfirmButton 异步确认 | Async action + confirm
  button-group-basic/            # ButtonGroup 操作组 | Action button group
  form-proform-basic/            # ProForm 表单增强 | Form enhancement demo
  card-modal-basic/              # Card + Modal 组合示例 | Card and modal composition
  checkcard-basic/               # CheckCard 选择卡片 | Selectable card
  typography-basic/              # Typography 文本排版 | Text/Title/Link/Paragraph
  beyond-overflow-basic/         # Beyond 超出折叠展示 | Overflow collapse list

每个示例目录建议包含：

• App.tsx：单组件最小可运行代码
• mock.ts：最小 mock 数据与请求
• README.md：中英双语说明（场景、依赖、运行方式）

npm Search Title Suggestions | npm 搜索标题建议（可同步到 GitHub Description）

下面标题可用于 npm 包描述、GitHub 仓库描述、文档首页副标题，提高中英文检索命中。

The following lines are optimized for npm and GitHub search visibility.

1. React + TypeScript Ant Design Pro Components Library for Admin Dashboard (ProTable, Imports, Exports, TreeSelect)
2. Enterprise React UI Components: ProTable, Modal Selector, Import/Export Workflow, List & Form Enhancements
3. 中后台 React 组件库（Ant Design）：ProTable、导入导出、树选择、列表与表单增强
4. React 中后台业务组件库 | ProTable / TabSelector / Imports / Exports / TreeSelect
5. Ant Design 业务组件库（TypeScript）- 表格、选择器、导入导出、表单流程

推荐同步策略：

• npm description：中英混合 1 行，覆盖核心组件名
• GitHub Description：优先使用第 1 或第 3 条
• 文档首页副标题：保留中英两行，覆盖 admin dashboard、中后台、ProTable、import/export

Usage Notes | 使用说明

• 依赖 react、react-dom、antd@6 与 @ant-design/pro-components@3 生态。
• 建议在中后台项目中与 Ant Design 主题体系一起使用。
• 样式无需手动导入，见上方 Styles | 样式。
• 组件 API 与示例可查看 components/*/README.md 和 src/stories/*。

Peer Dependencies | 对等依赖

请确保项目中已安装以下核心依赖（版本以 package.json 为准）：

• react >= 18, react-dom >= 18
• antd >= 6
• @ant-design/pro-components >= 3.1.14-7
• @ant-design/icons >= 6, classnames
• @vlian/utils

@ant-design/cssinjs 不再是本包的对等依赖。样式层已从 cssinjs 迁移到 CSS Modules， 不再需要消费者提供它；若你的项目里仍装着，也不会冲突。

License

MIT