npm package: @libeilong/react-admin-next
Description: 轻量的 React 后台管理组件集合，集成了 Ant Design Pro 组件、表单抽屉、表格查询、位置选择等常用功能，便于在内部管理系统中快速搭建页面。
Author: lblblong
Latest version: 0.0.2

# @libeilong/react-admin

轻量的 React 后台管理组件集合，集成了 Ant Design Pro 组件、表单抽屉、表格查询、位置选择等常用功能，便于在内部管理系统中快速搭建页面。

**核心特性**
- 提供 `BaseLayout`、`FormDrawer`、`TableQuery`、`TableSwitch` 等常用组件
- 与 `@libeilong/react-store-provider`、`@libeilong/map-js-sdk` 等库协同工作
- 使用 `tsdown` 构建并发布，支持 TypeScript 类型输出

**包信息**
- **名称**: `@libeilong/react-admin`
- **版本**: `0.24.1`
- **作者**: `lblblong`
- **License**: MIT

**安装**
在 monorepo 内使用 workspace 依赖时，通常在根目录使用 `pnpm` 安装所有包；单独安装时：

```
pnpm add @libeilong/react-admin
```

注意：本包将 `react`、`antd`、`mobx` 等声明为 `peerDependencies`，请在项目中安装匹配的版本。

**快速开始（示例）**
仓库内包含一个 `example` 演示：

```
cd packages/react-admin/example
pnpm install
pnpm start
```

打开浏览器访问 `http://localhost:1234`（若 Parcel 默认端口为 1234）。

**常用导出**
- `BaseLayout` — 后台页面布局组件（位于 `src/components/base-layout`）
- `FormDrawer` — 表单抽屉组件（位于 `src/components/form-drawer`）
- `TableQuery` / `TableQuery2` — 带查询逻辑的表格组件（位于 `src/components/table-query*`）
- `TableSwitch` — 表格内开关组件
- `location-select` / `poi-select` — 地图位置选择弹层（位于 `src/popups`）

示例用法：

```
import React from 'react'
import { BaseLayout, TableQuery } from '@libeilong/react-admin'

export default function App(){
	return (
		<BaseLayout>
			<TableQuery />
		</BaseLayout>
	)
}
```

**构建与发布**
- 本包使用 `tsdown` 构建，仓库根或包内可运行：

```
pnpm --filter @libeilong/react-admin run build
```

发布前会自动运行 `tsdown`（见 `prepublishOnly` 脚本）。

**开发**
- 本地开发可启用 watch 模式：

```
pnpm --filter @libeilong/react-admin run dev
```

**测试与示例调试**
- 示例使用 `parcel` 打包并在 `example` 目录下运行 `pnpm start` 来查看效果。

**贡献**
- 欢迎提交 issue 与 PR。请遵循仓库的贡献规范与代码风格。

**相关项目**
- `@libeilong/map-js-sdk` — 地图 SDK，location 相关弹层依赖
- `@libeilong/react-store-provider` — store provider 解决方案

**许可证**
MIT
)

**TableQuery2 详解**
TableQuery2 是一个基于 `@ant-design/pro-components` 的表格 + 查询方案，配合 `TableQueryStore2` 使用可以实现：URL 参数同步、分页、排序、过滤、加载态以及工具栏动作的统一管理。

主要组成：
- 组件：`TableQuery2`（位于 `src/components/table-query2/index.tsx`）
- Store：`TableQueryStore2`（位于 `src/components/table-query2/base-store.ts`）

核心 API（`TableQueryStore2` 字段与方法概览）
- `list: I[]`：当前表格数据列表
- `paging: { current, pageSize }`：分页信息，初始 `current=1`, `pageSize=15`
- `total: number`：总条数
- `sort: Record<string, 'ascend'|'descend'>`：排序信息
- `filter: object`：表格筛选条件
- `table: TableConfig`：表格配置，包含 `rowKey`, `maxHeight`, `headerTitle`, `noPagination`, `loading`, `rowSelection` 等
- `querySync: boolean`：是否同步查询参数到 URL（默认 true）
- `onGetQuery?: () => Record<string, any>`：当同步到 URL 时，用于附加自定义查询参数
- `onSetQuery?: (query, firstSetQuery) => void`：当从 URL 同步到 Store 时触发（例如将查询表单值同步回 store）
- `onFirstFetch?: () => Promise<void>`：第一次 fetch 前会调用一次
- `onCreate?: () => any`：如果定义该方法，组件工具栏会显示一个“新建”按钮并绑定该函数
- `fetchList`：抽象方法，需要实现实际的数据获取逻辑，返回 `{ list, total }`
- `fetch(options?)`：触发数据拉取（可选 `{ reset:true }` 清除分页与 loading）

使用注意与行为
- `TableQuery2` 会监听路由的 `location.search` 并在变化时调用 `store.setQuery`，用于把 URL 参数同步到 Store（例如页码、每页大小、额外的 query 字段）。
- 组件会在 `request` 回调里设置 `store.paging.current` / `pageSize` / `sort` / `filter`，并调用 `store.fetch()` 发起请求。
- `flushQuery()` 会把 `store.getQuery()` 序列化并通过 `navigate()` 更新到 URL（首次更新可使用 replace）。

一个最小可用示例

```
import React from 'react'
import { TableQuery2, TableQueryStore2 } from '@libeilong/react-admin'

class UsersStore extends TableQueryStore2<{ id: number; name: string }>{
	columns = [
		{ title: 'ID', dataIndex: 'id' },
		{ title: 'Name', dataIndex: 'name' },
	]

	fetchList = async () => {
		// 这里是你调用后端 API 的位置，示例返回固定数据
		const list = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
		const total = 2
		return { list, total }
	}
}

export default function Page(){
	const store = React.useMemo(() => new UsersStore(), [])
	return (
		<TableQuery2 store={store} />
	)
}
```

示例：在表格工具栏添加“新建”按钮

```
class UsersStore extends TableQueryStore2<{ id: number; name: string }>{
	// ...columns, fetchList
	onCreate = () => {
		// 打开创建表单或跳转到新建页面
	}
}
```

同步查询表单到 URL 的模式
- 实现 `onGetQuery` 来返回额外的查询参数（例如表单字段）；实现 `onSetQuery` 把 URL 参数设置回表单值。

示例：启用/禁用 URL 同步

```
const store = new UsersStore()
store.querySync = false // 禁用自动同步 URL 查询参数
```

常见问题
- 如何在第一次加载时自动触发查询？
	- 可在页面创建 store 后调用 `store.fetch()`，或者在 `onFirstFetch` 中完成初始化逻辑，`fetch` 内部会在第一次调用时执行 `onFirstFetch`。
- 如何自定义列的 `rowKey`？
	- 修改 `store.table.rowKey = 'yourKey'` 或在构造函数中覆盖默认值。

如果你希望，我可以：
- 为 `TableQuery2` 添加更完整的示例页面到 `example` 并集成一个真实的 mock API。
- 在 README 中为 `TableQuery` 与 `TableQuery2` 做表格对比与迁移指南（如果两个版本共存）。