xigua-ui-lib
v0.0.2
Published
基于 React 19 + TypeScript + Vite 构建的轻量级 UI 组件库。
Readme
xigua-ui-lib
基于 React 19 + TypeScript + Vite 构建的轻量级 UI 组件库。
安装
你可以使用 npm, yarn 或 pnpm 进行安装：
# 使用 npm
npm install xigua-ui-lib
# 使用 yarn
yarn add xigua-ui-lib
# 使用 pnpm
pnpm add xigua-ui-lib注意： 该组件库依赖
react和react-dom，请确保你的项目中已安装了这两个基础依赖。
组件列表
1. Tree (树形控件)
带父子级联选中功能的树形 checkbox 组件。支持以下特性：
- 选中父节点 → 所有子孙节点自动选中
- 取消父节点 → 所有子孙节点自动取消
- 子孙节点全部选中 → 父节点自动选中
- 子孙节点有任意未选中 → 父节点自动取消
基础引入与使用
import { useState } from 'react';
import { Tree } from 'xigua-ui-lib';
import type { TreeNode } from 'xigua-ui-lib';
// 引入组件库样式 (如果打包产物包含单独的 css 文件)
import 'xigua-ui-lib/dist/style.css'; // 请根据你的实际产物路径调整
const initialData: TreeNode[] = [
{
id: 1,
name: '节点 1',
selected: false,
children: [
{
id: 2,
name: '子节点 1-1',
selected: false,
children: [
{ id: 4, name: '孙节点 1-1-1', selected: false },
{ id: 5, name: '孙节点 1-1-2', selected: false },
],
},
{ id: 3, name: '子节点 1-2', selected: false },
],
},
];
function App() {
const [treeContext, setTreeContext] = useState<TreeNode[]>(initialData);
return (
<div style={{ padding: 20 }}>
<h3>基础级联树</h3>
<Tree
data={treeContext}
onChange={(newData) => {
// newData 是更新选中状态后的全新完整树
setTreeContext(newData);
console.log('当前最新树数据：', newData);
}}
/>
</div>
);
}
export default App;API 参考
Tree Props
| 属性 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| data | TreeNode[] | ✅ | - | 树的数据源 |
| onChange | (newData: TreeNode[]) => void | ❌ | - | 节点 checkbox 选中状态变化时的回调，参数为更新后的完整树数据 |
TreeNode 数据结构
传递给 data 的数组对象需要满足以下接口类型：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | number \| string | ✅ | 节点的唯一标识符 |
| name | string | ✅ | 节点显示的文本内容 |
| selected | boolean | ✅ | 节点当前是否处于选中状态 |
| children | TreeNode[] | ❌ | 子节点列表。如果不传或传空数组，则表示它是叶子节点 |
实用技巧：提取所有选中项
onChange 会返回包含所有层级的整棵树数据，如果你需要提交表单，通常需要拍平并提取出所有被选中的节点（selected: true）：
const getSelectedNodes = (nodes: TreeNode[]): TreeNode[] => {
return nodes.reduce((acc: TreeNode[], node: TreeNode) => {
if (node.selected) acc.push(node);
if (node.children) acc.push(...getSelectedNodes(node.children));
return acc;
}, []);
};
// 在 onChange 中使用:
onChange={(newData) => {
const selectedNodes = getSelectedNodes(newData);
const selectedIds = selectedNodes.map(n => n.id);
console.log('提交的 ID 列表:', selectedIds);
}}通过 <script> 标签直接引入
如果你没有使用工程化构建工具（如 Vite, Webpack），也可以直接在 HTML 文件中引入 UMD 产物。使用前请先引入 React 环境：
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Tree 示例</title>
<!-- 引入样式 -->
<!-- <link rel="stylesheet" href="./node_modules/xigua-ui-lib/dist/style.css"> -->
</head>
<body>
<div id="root"></div>
<!-- 先引入 React 和 ReactDOM -->
<script crossorigin src="https://unpkg.com/react@19/umd/react.development.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@19/umd/react-dom.development.js"></script>
<!-- 引入组件库的 UMD 构建产物 -->
<script src="./node_modules/xigua-ui-lib/dist/ui.umd.js"></script>
<script>
// 因为你在 Vite 库模式中配置了 name: "ui"
const { Tree } = ui;
// 接下来就可以使用 React.createElement 来渲染组件了...
</script>
</body>
</html>