@gulibs/react-vtable 0.0.17 → 0.0.19

package/README.md

@@ -2,13 +2,46 @@
 
 ![NPM version](https://img.shields.io/npm/v/@gulibs/react-vtable.svg?style=flat-square)
 
+A powerful and flexible React table component library built with shadcn/ui and TanStack Table.
+
 [English](#english) | [中文](#chinese)
 
 ---
 
 ## English
 
-A powerful React table component library built with shadcn/ui components and TanStack Table.
+### Table of Contents
+
+- [Features](#features)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+- [Complete API Reference](#complete-api-reference)
+- [Advanced Examples](#advanced-examples)
+- [Best Practices](#best-practices)
+- [Development](#development)
+- [License](#license)
+
+### Features
+
+- ✨ **Powerful Table**: Built on TanStack Table v8 for maximum flexibility and performance
+- 🎨 **shadcn/ui Components**: Beautiful, accessible, and customizable UI components
+- 🔍 **Search & Filter**: Advanced search with auto-filtering for local/remote data
+- 📄 **Pagination**: Client-side and server-side pagination support
+- ✅ **Row Selection**: Single/multiple selection with cross-page selection support
+- 🎯 **Batch Actions**: Flexible batch operations with smart button grouping
+- ✏️ **Inline Editing**: Edit rows inline with validation support
+- 📌 **Fixed Columns**: Pin columns to left/right with automatic shadow effects
+- 🌳 **Tree Table**: Hierarchical data with expand/collapse support
+- 🔄 **Drag & Drop**: Row and column reordering with @dnd-kit
+- 📱 **Responsive**: Mobile-friendly design
+- 🌐 **i18n**: Built-in English and Chinese locales
+- 🎭 **Rich Value Types**: 20+ built-in value types (date, money, status, etc.)
+- 📋 **Copy to Clipboard**: One-click copy for cells
+- 💬 **Tooltip**: Customizable tooltips for cells and headers
+- 📏 **Text Ellipsis**: Single-line and multi-line text truncation
+- 🔧 **TypeScript**: Full TypeScript support with comprehensive types
 
 ### Prerequisites
 
@@ -17,16 +50,24 @@ This library requires **Tailwind CSS** to be installed and configured in your pr
 ### Installation
 
 ```bash
-# Install the library
+# Using pnpm (recommended)
 pnpm add @gulibs/react-vtable
 
-# Install peer dependencies
-pnpm add react react-dom tailwindcss
+# Using npm
+npm install @gulibs/react-vtable
+
+# Using yarn
+yarn add @gulibs/react-vtable
+
+# Peer dependencies (if not already installed)
+pnpm add react react-dom @tanstack/react-table tailwindcss
 ```
 
 ### Configuration
 
-#### Configure Tailwind CSS
+#### Tailwind CSS Setup
+
+Add the library path to your `tailwind.config.js`:
 
 ```javascript
 // tailwind.config.js
@@ -39,636 +80,545 @@ export default {
 }
 ```
 
-> 💡 **Note**: The library automatically injects its CSS styles, so no manual CSS imports are required.
+> 💡 **Note**: The library automatically injects its CSS styles. No manual CSS imports are required.
 
-### Usage
+### Quick Start
 
 ```tsx
 import { ProTable } from '@gulibs/react-vtable'
-// No need to manually import CSS, styles are automatically inlined
 
 function App() {
   const columns = [
-    {
-      title: 'Name',
-      dataIndex: 'name',
-      key: 'name',
-    },
-    {
-      title: 'Age',
-      dataIndex: 'age',
-      key: 'age',
-    },
+    { title: 'Name', dataIndex: 'name', key: 'name' },
+    { title: 'Age', dataIndex: 'age', key: 'age' },
+    { title: 'Email', dataIndex: 'email', key: 'email' },
   ]
 
   const dataSource = [
-    { name: 'John', age: 30 },
-    { name: 'Jane', age: 25 },
+    { id: 1, name: 'John Doe', age: 30, email: 'john@example.com' },
+    { id: 2, name: 'Jane Smith', age: 25, email: 'jane@example.com' },
   ]
 
   return (
     <ProTable
       columns={columns}
       dataSource={dataSource}
-      rowKey="name"
+      rowKey="id"
     />
   )
 }
 ```
 
-### Features
+### Core Concepts
 
-- **Powerful Table**: Built on TanStack Table for maximum flexibility
-- **shadcn/ui Components**: Beautiful, accessible UI components
-- **Drag & Drop**: Row and column reordering with @dnd-kit
-- **Search & Filter**: Advanced search and filtering capabilities with default behavior for local and remote data modes
-- **Pagination**: Built-in pagination with customizable options
-- **Column Settings**: Show/hide columns, drag to reorder
-- **Row Selection**: Single and multiple row selection with batch actions, **cross-page selection support** (selection state persists across pages when using `request` or `pagination.onChange`)
-- **Editable Rows**: Inline editing capabilities with various value types
-- **Fixed Columns**: Left and right fixed columns with automatic position calculation and subtle shadow effects (powered by TanStack Table column pinning)
-- **Tree Table**: Hierarchical data display with expandable/collapsible rows, custom expand icons, and accordion mode
-- **Internationalization**: Built-in i18n support with English and Chinese locales
-- **Horizontal Scrolling**: Configurable table width with scroll support
-- **Copy to Clipboard**: One-click copy functionality for cells
-- **Text Ellipsis**: Single-line and multi-line text truncation with ellipsis
-- **Tooltip**: Hover tooltips for cells and headers with customizable content
-- **Responsive**: Mobile-friendly design
-- **TypeScript**: Full TypeScript support
-
-### Examples
-
-#### Basic Table
+#### 1. Data Modes
 
+**Local Data Mode** (using `dataSource`):
 ```tsx
 <ProTable
+  dataSource={localData}
   columns={columns}
-  dataSource={dataSource}
   rowKey="id"
 />
 ```
 
-#### With Search
-
-The table provides **default search behavior** that works automatically:
-
-- **Local Data Mode** (no `request` prop): Search values are automatically converted to TanStack Table's `columnFilters`, and the table filters data in real-time using `getFilteredRowModel()`.
-- **Remote Data Mode** (with `request` prop): Search triggers a new data fetch with search parameters passed to the backend.
-
-The default filter function supports:
-- Case-insensitive string matching (contains) for **text-like** fields
-- **Exact match** for **enum/filter** fields (e.g. `valueEnum`, `filters`, `valueType: 'select' | 'status'`)
-- Array-based multi-select filtering (exact match for enum/filter fields, contains match for text fields)
-- Automatic handling of empty/null values
-
+**Remote Data Mode** (using `request`):
 ```tsx
 <ProTable
+  request={async (params) => {
+    // params includes: current, pageSize, filters, sorter
+    const res = await fetchData(params)
+    return {
+      data: res.items,
+      total: res.total,
+      success: true
+    }
+  }}
   columns={columns}
-  dataSource={dataSource}
   rowKey="id"
-  search={{
-    filterType: 'query',
-    searchText: 'Search',
-    resetText: 'Reset'
-  }}
 />
 ```
 
-**Custom Search Behavior:**
+#### 2. Search Behavior
+
+The table provides **automatic search behavior**:
+
+- **Local Mode**: Converts search values to TanStack Table's `columnFilters` and filters in real-time
+- **Remote Mode**: Triggers data fetch with search parameters sent to backend
+
+Default filter supports:
+- Case-insensitive substring matching for text fields
+- Exact match for enum/select fields (`valueEnum`, `filters`, `valueType: 'select'`)
+- Array-based multi-select filtering
+- Automatic empty/null value handling
 
-You can provide custom `onSearch` and `onReset` callbacks to override the default behavior:
+#### 3. Pagination Modes
 
+**Client-side Pagination** (default with `dataSource`):
 ```tsx
 <ProTable
-  columns={columns}
-  dataSource={dataSource}
-  rowKey="id"
-  search={{
-    filterType: 'query',
-    onSearch: (values) => {
-      // Custom search logic
-      console.log('Search values:', values)
-    },
-    onReset: () => {
-      // Custom reset logic
-      console.log('Reset search')
-    }
-  }}
+  dataSource={data}
+  pagination={{ pageSize: 10 }}
 />
 ```
 
-#### With Pagination
-
+**Server-side Pagination** (with `request`):
 ```tsx
 <ProTable
-  columns={columns}
-  dataSource={dataSource}
-  rowKey="id"
-  pagination={{
-    pageSize: 10,
-    showSizeChanger: true
-  }}
+  request={fetchData}
+  pagination={{ pageSize: 10 }}
 />
 ```
 
-#### Remote Pagination (with `request`)
-
-In **Remote Data Mode** (when you pass `request`), pagination works like this:
-
-- **`total` controls the page count**: return `total` from `request` (recommended) and/or pass `pagination.total`.
-- **Do not pass `pagination.current/pageSize` as constants** (e.g. `current: 1`), unless you intend to lock the table to that page. If you want controlled pagination, store them in state and update in `pagination.onChange`.
-
-**Uncontrolled (recommended if you don't need to control page state):**
-
+**Manual Server Pagination** (without `request`):
 ```tsx
 <ProTable
-  columns={columns}
-  rowKey="id"
-  request={async (params) => {
-    // params includes: current, pageSize, ...filters, ...sorter
-    const res = await fetchUsers(params)
-    return { data: res.items, total: res.total, success: true }
-  }}
+  dataSource={currentPageData}
   pagination={{
-    pageSize: 10,
-    showSizeChanger: true,
-    showQuickJumper: true,
+    mode: 'server',  // Important!
+    current: page,
+    pageSize: pageSize,
+    total: total,
+    onChange: (page, pageSize) => fetchPage(page, pageSize)
   }}
 />
 ```
 
-**Controlled (when you need to sync pagination with external state / URL):**
-
-```tsx
-function Page() {
-  const [pagination, setPagination] = useState({
-    current: 1,
-    pageSize: 10,
-    total: 0,
-  })
-
-  return (
-    <ProTable
-      columns={columns}
-      rowKey="id"
-      request={async (params) => {
-        const res = await fetchUsers(params)
-        setPagination((prev) => ({ ...prev, total: res.total }))
-        return { data: res.items, total: res.total, success: true }
-      }}
-      pagination={{
-        current: pagination.current,
-        pageSize: pagination.pageSize,
-        total: pagination.total,
-        showSizeChanger: true,
-        showQuickJumper: true,
-        onChange: (current, pageSize) => {
-          setPagination((prev) => ({ ...prev, current, pageSize }))
-        },
-      }}
-    />
-  )
-}
-```
+---
 
-#### Server Pagination (NO `request`, you fetch data yourself)
+## Complete API Reference
 
-If you **do not** use `request`, but you still want **server-side pagination** (i.e. `dataSource` only contains **current page items**),
-set `pagination.mode: 'server'` to prevent TanStack Table from slicing again.
+### ProTable Props
 
-```tsx
-function Page() {
-  const [pagination, setPagination] = useState({ current: 1, pageSize: 10, total: 0 })
-  const [data, setData] = useState<any[]>([])
+#### Core Props
 
-  const fetchPage = async (current: number, pageSize: number) => {
-    const res = await fetchUsers({ current, pageSize })
-    setData(res.items)
-    setPagination((prev) => ({ ...prev, current, pageSize, total: res.total }))
-  }
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `columns` | `ProColumn<T>[]` | `[]` | Column definitions |
+| `dataSource` | `T[]` | `[]` | Local data array |
+| `request` | `(params) => Promise<Response>` | - | Remote data fetcher |
+| `rowKey` | `string \| (record) => string` | `'id'` | Unique row identifier |
+| `loading` | `boolean` | `false` | Loading state |
+| `defaultData` | `T[]` | `[]` | Default data for initial render |
+| `postData` | `(data: T[]) => T[]` | - | Transform data after fetch |
+| `params` | `Record<string, any>` | - | Extra params for `request` |
 
-  useEffect(() => {
-    void fetchPage(pagination.current, pagination.pageSize)
-  }, [])
+#### Layout Props
 
-  return (
-    <ProTable
-      columns={columns}
-      rowKey="id"
-      dataSource={data}
-      pagination={{
-        mode: "server",
-        current: pagination.current,
-        pageSize: pagination.pageSize,
-        total: pagination.total,
-        onChange: (current, pageSize) => void fetchPage(current, pageSize),
-      }}
-    />
-  )
-}
-```
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `size` | `'small' \| 'middle' \| 'large'` | `'middle'` | Table size |
+| `bordered` | `boolean` | `false` | Show table borders |
+| `tableLayout` | `'auto' \| 'fixed'` | `'auto'` | Table layout algorithm |
+| `scroll` | `{ x?: number \| string \| true; y?: number \| string }` | - | Scrollable area config |
+| `sticky` | `boolean \| { offsetHeader?: number }` | `false` | Sticky header config |
+| `showHeader` | `boolean` | `true` | Show table header |
+| `className` | `string` | - | Custom class name |
+| `style` | `CSSProperties` | - | Custom styles |
+| `tableStyle` | `CSSProperties` | - | Table element styles |
+
+#### Feature Props
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `search` | `ProTableSearch \| false` | `false` | Search form config |
+| `toolbar` | `ProTableToolBar \| false` | `false` | Toolbar config |
+| `pagination` | `ProTablePagination \| false` | `false` | Pagination config |
+| `rowSelection` | `ProTableRowSelection<T>` | - | Row selection config |
+| `batchActions` | `ProTableBatchActions<T>` | - | Batch actions config |
+| `editable` | `ProTableEditable<T>` | - | Inline editing config |
+| `expandable` | `ProTableExpandable<T> \| false` | - | Tree table config |
+| `draggable` | `ProTableDraggable \| false` | - | Drag & drop config |
+| `columnsState` | `ProColumnState` | - | Column state management |
+
+#### Callback Props
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `onChange` | `(pagination, filters, sorter, extra) => void` | Table change callback |
+| `onLoad` | `(dataSource: T[]) => void` | Called after data loaded |
+| `onLoadingChange` | `(loading: boolean) => void` | Loading state change |
+| `onRequestError` | `(error: Error) => void` | Request error callback |
+| `onSubmit` | `(params: any) => void` | Search submit callback |
+| `onReset` | `() => void` | Search reset callback |
+| `onRow` | `(record, index) => HTMLAttributes` | Row props callback |
+
+#### Advanced Props
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `headerTitle` | `ReactNode` | Table header title |
+| `headerSubTitle` | `ReactNode` | Table header subtitle |
+| `footer` | `(data) => ReactNode` | Table footer render |
+| `emptyRender` | `ReactNode` | Empty state render |
+| `tableRender` | `(props, dom, domList) => ReactNode` | Custom table render |
+| `tableExtraRender` | `(props, data) => ReactNode` | Extra content after table |
+| `paginationRender` | `(opts) => ReactNode` | Custom pagination render |
+| `searchFormRender` | `(props, dom) => ReactNode` | Custom search form render |
+| `actionRef` | `Ref<ProTableAction<T>>` | Table action reference |
+| `formRef` | `Ref<FormInstance>` | Search form reference |
+| `locale` | `ProTableLocale` | i18n locale config |
 
-#### Custom Pagination Rendering (`paginationRender`)
+---
 
-Use `paginationRender` when you want to **render your own pagination UI** (in any layout), while still reusing ProTable’s built-in
-pagination state and default Pagination component.
+### ProColumn Configuration
 
-Notes:
-- `paginationRender` receives `pagination`, `onChange`, and `defaultDom`.
-- If you are in **server pagination mode** (`pagination.mode: 'server'`) you must also provide `pagination.onChange` to fetch data.
+#### Basic Props
 
-```tsx
-<ProTable
-  columns={columns}
-  rowKey="id"
-  dataSource={data}
-  pagination={{
-    mode: "server",
-    current,
-    pageSize,
-    total,
-    onChange: (page, pageSize) => void fetchPage(page, pageSize),
-  }}
-  paginationRender={({ pagination, onChange, defaultDom }) => (
-    <div className="space-y-2">
-      <div className="flex items-center justify-between rounded border p-2">
-        <div className="text-sm text-muted-foreground">
-          Page {pagination.current} / Size {pagination.pageSize} / Total {pagination.total}
-        </div>
-        <div className="flex gap-2">
-          <button onClick={() => onChange(Math.max(1, pagination.current - 1), pagination.pageSize)}>
-            Prev
-          </button>
-          <button onClick={() => onChange(pagination.current + 1, pagination.pageSize)}>
-            Next
-          </button>
-        </div>
-      </div>
-      {/* reuse built-in Pagination UI */}
-      {defaultDom}
-    </div>
-  )}
-/>
-```
+| Property | Type | Description |
+|----------|------|-------------|
+| `title` | `string` | Column header text |
+| `dataIndex` | `keyof T \| string \| string[]` | Data field path (supports nested: `'user.name'` or `['user', 'name']`) |
+| `dataPath` | `string` | Alternative to dataIndex (string path only: `'user.name'`) |
+| `key` | `string` | Unique column key |
+| `width` | `number \| string` | Column width (required for fixed columns) |
+| `align` | `'left' \| 'center' \| 'right'` | Text alignment |
+| `fixed` | `'left' \| 'right'` | Pin column to left/right |
+
+#### Display Props
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `valueType` | `ProFieldValueType` | Value display type (20+ types) |
+| `valueEnum` | `Record<string, { text: string; status?: string; color?: string }>` | Enum value mapping |
+| `render` | `(value, record, index) => ReactNode` | Custom cell render (takes priority over `valueType`) |
+| `ellipsis` | `boolean \| ProColumnEllipsis` | Text ellipsis config |
+| `tooltip` | `boolean \| ProColumnTooltip` | Tooltip config |
+| `headerEllipsis` | `boolean \| ProColumnEllipsis` | Header ellipsis config |
+| `headerTooltip` | `boolean \| ProColumnTooltip` | Header tooltip config |
+| `copyable` | `boolean \| ProColumnCopyable` | Enable copy to clipboard |
+
+#### Search Props
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `search` | `boolean \| ProColumnSearch` | Include in search form |
+| `hideInSearch` | `boolean` | Hide in search form |
+| `searchFormItemProps` | `FormItemProps` | Search form item props |
+| `renderFormItem` | `(value, onChange, field, column) => ReactNode` | Custom search input render |
+
+#### Table Display Props
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `hideInTable` | `boolean` | Hide in table |
+| `sorter` | `boolean \| ((a, b) => number)` | Enable sorting |
+| `filters` | `Array<{ text: string; value: any }>` | Filter options |
+| `onFilter` | `(value, record) => boolean` | Filter function |
 
-#### With Internationalization
+#### Edit Props
 
-```tsx
-import { ProTable, zh_CN } from '@gulibs/react-vtable'
+| Property | Type | Description |
+|----------|------|-------------|
+| `editable` | `boolean \| ((record) => boolean)` | Enable inline editing |
+| `hideInForm` | `boolean` | Hide in edit form |
+| `formItemProps` | `FormItemProps` | Form item props |
+| `fieldProps` | `Record<string, any>` | Field component props |
 
-<ProTable
-  columns={columns}
-  dataSource={dataSource}
-  rowKey="id"
-  locale={zh_CN}
-/>
-```
+---
 
-#### With Fixed Columns
+### Value Types Reference
+
+Supported `valueType` values:
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `text` | Plain text | "Hello World" |
+| `textarea` | Multi-line text | Long content |
+| `number` | Number | 123 |
+| `money` | Currency | $1,234.56 |
+| `percent` | Percentage | 75% |
+| `date` | Date | 2024-01-01 |
+| `dateTime` | Date with time | 2024-01-01 10:30:00 |
+| `dateRange` | Date range | 2024-01-01 ~ 2024-01-31 |
+| `select` | Select dropdown | Uses `valueEnum` |
+| `status` | Status badge | Uses `valueEnum` |
+| `tags` | Multiple tags | Array display |
+| `switch` | Boolean switch | true/false |
+| `avatar` | Avatar image | URL display |
+| `image` | Image | URL display |
+| `progress` | Progress bar | 0-100 |
+| `code` | Code block | Monospace text |
+| `fromNow` | Relative time | "2 hours ago" |
+| `email` | Email address | With mailto link |
+| `phone` | Phone number | Formatted |
+| `url` | URL link | Clickable link |
+| `color` | Color picker | Color swatch |
+| `rate` | Rating stars | 1-5 stars |
+| `custom` | Custom render | Use `render` function |
 
-Fixed columns are implemented using TanStack Table's column pinning feature. The library automatically calculates positions and applies subtle shadow effects to indicate fixed column boundaries.
+---
 
-```tsx
-<ProTable
-  columns={[
-    {
-      title: 'ID',
-      dataIndex: 'id',
-      key: 'id',
-      width: 80,
-      fixed: 'left'  // Fixed to the left
-    },
-    {
-      title: 'Name',
-      dataIndex: 'name',
-      key: 'name',
-      width: 120
-    },
-    {
-      title: 'Actions',
-      dataIndex: 'actions',
-      key: 'actions',
-      width: 100,
-      fixed: 'right'  // Fixed to the right
-    }
-  ]}
-  dataSource={dataSource}
-  rowKey="id"
-  scroll={{ x: 1000 }}  // Enable horizontal scrolling
-  tableLayout="fixed"    // Recommended for fixed columns
-/>
+### Search Configuration
+
+```typescript
+interface ProTableSearch {
+  filterType?: 'query' | 'light'  // Query: form above table, Light: inline filters
+  searchText?: string              // Search button text
+  resetText?: string               // Reset button text
+  submitText?: string              // Submit button text
+  labelWidth?: number | 'auto'     // Label width
+  span?: number                    // Grid column span
+  defaultCollapsed?: boolean       // Initially collapsed
+  collapsed?: boolean              // Controlled collapse state
+  onCollapse?: (collapsed: boolean) => void
+  optionRender?: (config, props, dom) => ReactNode[]  // Custom action buttons
+}
 ```
 
-**Important Notes:**
-- Fixed columns require a `width` property to calculate positions correctly
-- The library automatically handles position calculations using TanStack Table's `getStart()` and `getAfter()` methods
-- Subtle shadow effects are automatically applied to the last left-pinned column and first right-pinned column
-- No additional CSS is required - all styles are applied inline
-
-#### With Tree Table (Expandable Rows)
-
-Tree tables support hierarchical data structures with expandable/collapsible rows. The data structure should include a `children` property (or custom field name) containing nested rows.
+**Example:**
 
 ```tsx
 <ProTable
-  columns={columns}
-  dataSource={[
-    {
-      id: 1,
-      name: 'Parent Node',
-      children: [
-        { id: 11, name: 'Child Node 1' },
-        { id: 12, name: 'Child Node 2' }
-      ]
-    }
-  ]}
-  rowKey="id"
-  expandable={{
-    childrenColumnName: 'children',  // Default: 'children'
-    defaultExpandAllRows: false,     // Expand all rows by default
-    defaultExpandedRowKeys: [1],     // Initially expanded rows
-    accordion: false,                // Accordion mode (only one row expanded at a time)
-    showExpandColumn: true,          // Show expand icon column
-    expandColumnWidth: 50,           // Width of expand column
-    onExpand: (expanded, record) => {
-      console.log('Expand:', expanded, record)
-    },
-    onExpandedRowsChange: (expandedRowKeys) => {
-      console.log('Expanded keys:', expandedRowKeys)
-    },
-    expandIcon: ({ expanded, onExpand, record }) => (
-      <Button onClick={onExpand}>
-        {expanded ? '▼' : '▶'}
-      </Button>
-    )
+  search={{
+    filterType: 'query',
+    searchText: 'Search',
+    resetText: 'Reset',
+    labelWidth: 'auto',
+    defaultCollapsed: false,
   }}
 />
 ```
 
-**Tree Table Features:**
-- **Controlled/Uncontrolled Mode**: Use `expandedRowKeys` for controlled mode, or `defaultExpandedRowKeys` for uncontrolled
-- **Default Expand All**: Set `defaultExpandAllRows: true` to expand all rows by default
-- **Accordion Mode**: Set `accordion: true` to allow only one row to be expanded at a time
-- **Custom Children Field**: Use `childrenColumnName` to specify a custom field name for children (default: `'children'`)
-- **Custom Expand Icon**: Provide a custom `expandIcon` function to customize the expand/collapse icon
-- **Expand Callbacks**: Use `onExpand` and `onExpandedRowsChange` to handle expand state changes
-
-#### With Editable Rows
+---
 
-```tsx
-<ProTable
-  columns={columns}
-  dataSource={dataSource}
-  rowKey="id"
-  editable={{
-    type: 'multiple',
-    onSave: async (key, record, originRow) => {
-      console.log('Save:', { key, record, originRow })
-      // Handle save logic
-    }
-  }}
-/>
+### Pagination Configuration
+
+```typescript
+interface ProTablePagination {
+  mode?: 'client' | 'server'  // Pagination mode
+  pageSize?: number            // Items per page
+  current?: number             // Current page (controlled)
+  total?: number               // Total items
+  showSizeChanger?: boolean    // Show page size selector
+  showQuickJumper?: boolean    // Show quick jump input
+  showTotal?: (total, range) => ReactNode
+  pageSizeOptions?: string[]   // Page size options
+  size?: 'default' | 'small'
+  simple?: boolean             // Simple pagination
+  disabled?: boolean
+  onChange?: (page, pageSize) => void
+  onShowSizeChange?: (current, size) => void
+}
 ```
 
-#### With Row Selection and Batch Actions
+---
 
-```tsx
-<ProTable
-  columns={columns}
-  dataSource={dataSource}
-  rowKey="id"
-  rowSelection={{
-    type: 'checkbox',
-    onChange: (selectedRowKeys, selectedRows) => {
-      console.log('Selected:', selectedRowKeys, selectedRows)
-    },
-    batchActions: {
-      onDelete: (rows) => {
-        console.log('Delete:', rows)
-      },
-      onExport: (rows) => {
-        console.log('Export:', rows)
-      }
-    }
-  }}
-/>
+### Row Selection Configuration
+
+```typescript
+interface ProTableRowSelection<T> {
+  type?: 'checkbox' | 'radio'  // Selection type
+  selectedRowKeys?: React.Key[]  // Controlled selection
+  onChange?: (keys, rows) => void
+  preserveSelectedRowKeys?: boolean  // Keep selection across pages (default: true)
+  getCheckboxProps?: (record) => any
+  selections?: boolean | any[]
+  hideSelectAll?: boolean
+  fixed?: boolean              // Fix selection column
+  columnWidth?: number | string
+  renderCell?: (checked, record, index, originNode) => ReactNode
+  alwaysShowAlert?: boolean    // Always show batch actions bar
+  batchActions?: ProTableBatchActions<T>  // Batch operations config
+}
 ```
 
-**Cross-Page Selection Support:**
-
-When using `request` or `pagination.onChange` for remote data fetching, the table automatically maintains selection state across pages. This means:
+#### Cross-Page Selection
 
-- Selections made on one page are preserved when navigating to other pages
-- The batch actions bar shows the **total count** of selected rows across all pages
-- When you return to a previously visited page, your selections are automatically restored
-- The `onChange` callback receives all selected row keys across all pages
+When using `request` or `pagination.onChange`, selection automatically persists across pages:
 
 ```tsx
 <ProTable
-  columns={columns}
-  rowKey="id"
-  request={async (params) => {
-    const res = await fetchUsers(params)
-    return { data: res.items, total: res.total, success: true }
-  }}
+  request={fetchData}
   rowSelection={{
     type: 'checkbox',
+    preserveSelectedRowKeys: true,  // Default: true
     onChange: (selectedRowKeys, selectedRows) => {
-      // selectedRowKeys contains ALL selected keys across all pages
-      // selectedRows contains rows from the current page only
-      console.log('Total selected across all pages:', selectedRowKeys.length)
-    },
-    batchActions: {
-      onDelete: (rows) => {
-        // This will receive rows from current page only
-        // Use selectedRowKeys from onChange for full selection
-        console.log('Delete current page rows:', rows)
-      }
-    }
-  }}
-  pagination={{
-    pageSize: 10,
-    showSizeChanger: true,
-    onChange: (current, pageSize) => {
-      // Selection state is automatically preserved when page changes
+      // selectedRowKeys: all selected keys across all pages
+      // selectedRows: rows from current page only
+      console.log('Total selected:', selectedRowKeys.length)
     }
   }}
 />
 ```
 
-**Important Notes:**
-- Cross-page selection works automatically when using `request` or `pagination.onChange`
-- With `dataSource` (local data), selection works normally but doesn't need cross-page support
-- The batch actions bar always shows the total count of selected rows across all pages
-- Use `rowSelection.onChange` to get all selected keys if you need to perform operations on all selected rows
+---
+
+### Batch Actions Configuration (Updated API)
 
-**Automatic Selection Clearing:**
+```typescript
+interface ProTableBatchActions<T> {
+  actions?: Array<ProTableBatchAction<T>>  // Batch action list
+  maxVisibleActions?: number  // Max buttons to show directly (default: 3)
+  hideClearButton?: boolean   // Hide clear selection button
+}
 
-After certain batch operations, the selection state is automatically cleared:
+interface ProTableBatchAction<T> {
+  key: string                  // Unique action key
+  label: string                // Button text
+  icon?: ReactNode             // Button icon
+  onClick: (rows: T[]) => void // Click handler
+  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link'
+  clearSelection?: boolean     // Clear selection after action (default: false)
+  showInMore?: boolean         // Show in "More" menu (default: false)
+  isExportFormat?: boolean     // Mark as export format (auto-groups multiple export formats)
+}
+```
 
-- **Delete operation**: Automatically clears selection after deletion (since the data is removed)
-- **Archive operation**: Automatically clears selection after archiving
-- **Custom actions**: You can control whether to clear selection using the `clearSelection` option
+**Example:**
 
 ```tsx
+import { Trash2, Download, FileText, Mail } from 'lucide-react'
+
 <ProTable
   rowSelection={{
     type: 'checkbox',
     batchActions: {
-      onDelete: (rows) => {
-        // Delete operation - selection will be automatically cleared
-        console.log('Delete:', rows)
-      },
-      onArchive: (rows) => {
-        // Archive operation - selection will be automatically cleared
-        console.log('Archive:', rows)
-      },
-      // Hide the clear button if needed
-      hideClearButton: false,
-      customActions: [
+      maxVisibleActions: 3,  // Show max 3 buttons directly
+      actions: [
         {
-          key: 'approve',
-          label: 'Approve',
+          key: 'delete',
+          label: 'Delete',
+          icon: <Trash2 className="h-3 w-3 mr-1" />,
           onClick: (rows) => {
-            console.log('Approve:', rows)
+            console.log('Delete:', rows)
           },
-          // Control whether to clear selection after this action
-          clearSelection: true, // Set to true to clear selection after this action
+          variant: 'destructive',
+          clearSelection: true,  // Clear after delete
         },
         {
           key: 'export',
           label: 'Export',
+          icon: <Download className="h-3 w-3 mr-1" />,
           onClick: (rows) => {
             console.log('Export:', rows)
           },
-          clearSelection: false, // Keep selection after export (default)
-        }
-      ]
-    }
+          variant: 'outline',
+        },
+        {
+          key: 'exportExcel',
+          label: 'Export Excel',
+          icon: <FileText className="h-3 w-3 mr-1" />,
+          onClick: (rows) => {
+            console.log('Export Excel:', rows)
+          },
+          variant: 'outline',
+          isExportFormat: true,  // Groups with other export formats
+          showInMore: true,
+        },
+        {
+          key: 'exportCSV',
+          label: 'Export CSV',
+          icon: <FileText className="h-3 w-3 mr-1" />,
+          onClick: (rows) => {
+            console.log('Export CSV:', rows)
+          },
+          variant: 'outline',
+          isExportFormat: true,
+          showInMore: true,
+        },
+        {
+          key: 'email',
+          label: 'Send Email',
+          icon: <Mail className="h-3 w-3 mr-1" />,
+          onClick: (rows) => {
+            console.log('Email:', rows)
+          },
+          variant: 'outline',
+          showInMore: true,  // Move to "More" menu
+        },
+      ],
+    },
   }}
 />
 ```
 
-#### With Text Ellipsis and Tooltip
+**Features:**
+- Smart button grouping: buttons exceeding `maxVisibleActions` auto-move to "More" (⋯) menu
+- Export format grouping: multiple `isExportFormat: true` actions auto-merge into dropdown
+- Flexible action control: use `clearSelection` to auto-clear selection after certain actions
 
-```tsx
-<ProTable
-  columns={[
-    {
-      title: 'Description',
-      dataIndex: 'description',
-      key: 'description',
-      width: 200,
-      // Single-line ellipsis with tooltip
-      ellipsis: true,
-      tooltip: true
-    },
-    {
-      title: 'Content',
-      dataIndex: 'content',
-      key: 'content',
-      width: 250,
-      // Multi-line ellipsis (2 rows) with tooltip
-      ellipsis: {
-        multiline: true,
-        rows: 2
-      },
-      tooltip: true
-    },
-    {
-      title: 'Custom Tooltip',
-      dataIndex: 'name',
-      key: 'name',
-      width: 150,
-      ellipsis: true,
-      tooltip: {
-        content: (value, record) => `Full: ${record.fullName || value}`,
-        side: 'top',
-        delayDuration: 300
-      }
-    },
-    {
-      title: 'Header with Ellipsis',
-      dataIndex: 'email',
-      key: 'email',
-      width: 180,
-      // Header-specific ellipsis and tooltip
-      headerEllipsis: true,
-      headerTooltip: {
-        content: 'This is the full header title',
-        side: 'bottom'
-      },
-      // Cell ellipsis and tooltip
-      ellipsis: true,
-      tooltip: true
-    }
-  ]}
-  dataSource={dataSource}
-  rowKey="id"
-/>
+---
+
+### Editable Configuration
+
+```typescript
+interface ProTableEditable<T> {
+  type?: 'single' | 'multiple'  // Edit mode
+  form?: any                     // React Hook Form instance
+  formProps?: Record<string, any>
+  onSave?: (key, record, originRow) => Promise<void>
+  onDelete?: (key, record) => Promise<void>
+  onCancel?: (key, record, originRow) => void
+  actionRender?: (record, config) => ReactNode[]  // Custom action buttons
+  deletePopconfirmMessage?: ReactNode
+  onlyOneLineEditorAlertMessage?: ReactNode
+  onlyAddOneLineAlertMessage?: ReactNode
+}
 ```
 
-### API Reference
+---
 
-#### ProTable Props
+### Expandable Configuration (Tree Table)
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `columns` | `ProColumn[]` | `[]` | Table column definitions |
-| `dataSource` | `T[]` | `[]` | Table data source |
-| `rowKey` | `string \| (record: T) => string` | `'id'` | Unique key for each row |
-| `loading` | `boolean` | `false` | Loading state |
-| `pagination` | `ProTablePagination \| false` | `false` | Pagination configuration |
-| `search` | `ProTableSearch \| false` | `false` | Search form configuration |
-| `rowSelection` | `ProTableRowSelection` | `undefined` | Row selection configuration |
-| `editable` | `ProTableEditable` | `undefined` | Editable rows configuration |
-| `draggable` | `ProTableDraggable` | `undefined` | Drag and drop configuration |
-| `expandable` | `ProTableExpandable \| false` | `undefined` | Tree table expandable configuration |
-| `scroll` | `{ x?: number \| true; y?: number \| string }` | `undefined` | Scroll configuration |
-| `tableLayout` | `'auto' \| 'fixed'` | `'auto'` | Table layout mode |
-| `locale` | `ProTableLocale` | `en_US` | Internationalization locale |
-| `size` | `'small' \| 'middle' \| 'large'` | `'middle'` | Table size |
-| `bordered` | `boolean` | `false` | Show table borders |
+```typescript
+interface ProTableExpandable<T> {
+  childrenColumnName?: string    // Children field name (default: 'children')
+  defaultExpandedRowKeys?: React.Key[]  // Default expanded rows
+  expandedRowKeys?: React.Key[]  // Controlled expanded rows
+  onExpand?: (expanded, record) => void
+  onExpandedRowsChange?: (keys) => void
+  expandIcon?: (props: {
+    expanded: boolean
+    onExpand: () => void
+    record: T
+  }) => ReactNode
+  showExpandColumn?: boolean     // Show expand column (default: true)
+  expandColumnWidth?: number     // Expand column width (default: 50)
+  defaultExpandAllRows?: boolean // Expand all by default
+  accordion?: boolean            // Accordion mode (only one expanded)
+}
+```
 
-#### Column Configuration
+---
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `title` | `string` | Column header text |
-| `dataIndex` | `string` | Data field name |
-| `key` | `string` | Unique column key |
-| `width` | `number` | Column width in pixels |
-| `fixed` | `'left' \| 'right'` | Fixed column position |
-| `sorter` | `boolean` | Enable sorting |
-| `editable` | `boolean` | Enable inline editing |
-| `copyable` | `boolean` | Enable copy to clipboard |
-| `ellipsis` | `boolean \| ProColumnEllipsis` | Enable text ellipsis (single-line or multi-line) |
-| `tooltip` | `boolean \| ProColumnTooltip` | Enable tooltip on hover |
-| `headerEllipsis` | `boolean \| ProColumnEllipsis` | Enable ellipsis for header (defaults to `ellipsis`) |
-| `headerTooltip` | `boolean \| ProColumnTooltip` | Enable tooltip for header (defaults to `tooltip`) |
-| `search` | `boolean` | Include in search form |
-| `valueType` | `ProFieldValueType` | Value type for rendering |
-| `valueEnum` | `Record<string, { text: string; status?: string }>` | Enum values for select |
-| `filters` | `Array<{ text: string; value: any }>` | Filter options |
+### Ellipsis Configuration
 
-#### Ellipsis Configuration
+```typescript
+interface ProColumnEllipsis {
+  multiline?: boolean  // Multi-line ellipsis
+  rows?: number        // Number of rows (1-5, default: 2)
+}
+```
 
-The `ellipsis` and `headerEllipsis` properties support the following configurations:
+**Examples:**
 
 ```tsx
 // Single-line ellipsis
 ellipsis: true
 
-// Multi-line ellipsis
+// Multi-line ellipsis (2 lines)
 ellipsis: {
   multiline: true,
-  rows: 2  // Number of lines (1-5)
+  rows: 2
 }
 ```
 
-#### Tooltip Configuration
+---
 
-The `tooltip` and `headerTooltip` properties support the following configurations:
+### Tooltip Configuration
+
+```typescript
+interface ProColumnTooltip<T> {
+  content?: ReactNode | ((value, record, index) => ReactNode)
+  side?: 'top' | 'right' | 'bottom' | 'left'
+  align?: 'start' | 'center' | 'end'
+  delayDuration?: number
+  disabled?: boolean
+}
+```
+
+**Examples:**
 
 ```tsx
 // Simple tooltip (shows cell value)
@@ -677,821 +627,674 @@ tooltip: true
 // Custom tooltip
 tooltip: {
   content: 'Custom tooltip text',
-  side: 'top' | 'right' | 'bottom' | 'left',
-  align: 'start' | 'center' | 'end',
-  delayDuration: 300,
-  disabled: false
+  side: 'top',
+  delayDuration: 300
 }
 
 // Function-based tooltip
 tooltip: {
-  content: (value, record, index) => `Full: ${value}\nID: ${record.id}`,
+  content: (value, record) => `Full: ${value} (ID: ${record.id})`,
   side: 'top'
 }
 ```
 
-**Note**: When `ellipsis` is enabled and `tooltip` is `true`, the tooltip will automatically show the full original value (not the rendered value) when text is truncated.
-
-#### Expandable (Tree Table) Configuration
-
-The `expandable` property supports the following configurations:
-
-```tsx
-expandable: {
-  // Custom children field name (default: 'children')
-  childrenColumnName?: string
-
-  // Default expanded row keys (uncontrolled mode)
-  defaultExpandedRowKeys?: React.Key[]
-
-  // Currently expanded row keys (controlled mode)
-  expandedRowKeys?: React.Key[]
-
-  // Expand/collapse callback
-  onExpand?: (expanded: boolean, record: T) => void
-
-  // Expanded rows change callback
-  onExpandedRowsChange?: (expandedRowKeys: React.Key[]) => void
-
-  // Custom expand icon
-  expandIcon?: (props: {
-    expanded: boolean
-    onExpand: () => void
-    record: T
-  }) => ReactNode
-
-  // Show expand column (default: true)
-  showExpandColumn?: boolean
-
-  // Expand column width (default: 50)
-  expandColumnWidth?: number
-
-  // Expand all rows by default (default: false)
-  defaultExpandAllRows?: boolean
+---
 
-  // Accordion mode - only one row expanded at a time (default: false)
-  accordion?: boolean
+### Action Reference
+
+Access table methods via `actionRef`:
+
+```typescript
+interface ProTableAction<T> {
+  reload: (resetPageIndex?: boolean) => Promise<void>  // Reload data
+  reloadAndRest: () => Promise<void>  // Reload and reset to page 1
+  reset: () => void                    // Reset filters and search
+  clearSelected: () => void            // Clear row selection
+  startEditable: (rowKey) => boolean   // Start editing row
+  cancelEditable: (rowKey) => boolean  // Cancel editing row
+  saveEditable: (rowKey, record) => boolean  // Save edited row
+  getRowData: (rowKey) => T | undefined     // Get row data
+  getTableData: () => T[]              // Get all table data
+  setTableData: (data: T[]) => void    // Set table data
 }
 ```
 
-### Development
-
-```bash
-# Install dependencies
-pnpm install
-
-# Build the library
-pnpm run build
-
-# Start development server
-pnpm run dev
-```
-
-### License
-
-MIT
-
----
-
-## Chinese
-
-一个基于 shadcn/ui 组件和 TanStack Table 构建的强大 React 表格组件库。
+**Example:**
 
-### 前置要求
-
-此库需要您的项目中安装并配置 **Tailwind CSS**。
+```tsx
+const actionRef = useRef<ProTableAction<DataType>>(null)
 
-### 安装
+// Reload data
+actionRef.current?.reload()
 
-```bash
-# 安装库
-pnpm add @gulibs/react-vtable
+// Reset filters
+actionRef.current?.reset()
 
-# 安装对等依赖
-pnpm add react react-dom tailwindcss
+// Clear selection
+actionRef.current?.clearSelected()
 ```
 
-### 配置
-
-#### 配置 Tailwind CSS
-
-```javascript
-// tailwind.config.js
-export default {
-  content: [
-    './src/**/*.{js,ts,jsx,tsx}',
-    './node_modules/@gulibs/react-vtable/dist/**/*.js'
-  ],
-  // 无需额外配置 - 样式会自动注入
-}
-```
+---
 
-> 💡 **注意**: 库会自动注入其 CSS 样式，因此无需手动导入 CSS。
+## Advanced Examples
 
-### 使用方法
+### 1. Remote Data with Search and Pagination
 
 ```tsx
-import { ProTable } from '@gulibs/react-vtable'
-// 无需手动导入 CSS，样式已自动内联
-
-function App() {
-  const columns = [
-    {
-      title: '姓名',
-      dataIndex: 'name',
-      key: 'name',
-    },
+<ProTable
+  request={async (params) => {
+    // params includes: current, pageSize, keyword, ...filters, ...sorter
+    const response = await fetch('/api/users', {
+      method: 'POST',
+      body: JSON.stringify(params)
+    })
+    const data = await response.json()
+    return {
+      data: data.items,
+      total: data.total,
+      success: true
+    }
+  }}
+  columns={[
+    { title: 'Name', dataIndex: 'name', search: true },
+    { title: 'Email', dataIndex: 'email', search: true },
     {
-      title: '年龄',
-      dataIndex: 'age',
-      key: 'age',
+      title: 'Status',
+      dataIndex: 'status',
+      valueType: 'select',
+      search: true,
+      valueEnum: {
+        active: { text: 'Active', status: 'success' },
+        inactive: { text: 'Inactive', status: 'default' },
+      },
     },
-  ]
-
-  const dataSource = [
-    { name: '张三', age: 30 },
-    { name: '李四', age: 25 },
-  ]
-
-  return (
-    <ProTable
-      columns={columns}
-      dataSource={dataSource}
-      rowKey="name"
-    />
-  )
-}
-```
-
-### 功能特性
-
-- **强大表格**: 基于 TanStack Table 构建，提供最大灵活性
-- **shadcn/ui 组件**: 美观、可访问的 UI 组件
-- **拖拽排序**: 使用 @dnd-kit 实现行和列重排序
-- **搜索筛选**: 高级搜索和筛选功能，支持本地和远程数据模式的默认行为
-- **分页**: 内置分页，支持自定义选项
-- **列设置**: 显示 / 隐藏列，拖拽重排序
-- **行选择**: 单选和多选行，支持批量操作，**跨页选中支持**（使用 `request` 或 `pagination.onChange` 时，选中状态会在切换页面时保留）
-- **可编辑行**: 内联编辑功能，支持多种值类型
-- **固定列**: 左右固定列，自动计算位置并应用柔和阴影效果（基于 TanStack Table column pinning）
-- **树形表格**: 层次数据展示，支持展开 / 收起行、自定义展开图标和手风琴模式
-- **国际化**: 内置 i18n 支持，提供中英文语言包
-- **横向滚动**: 可配置表格宽度，支持滚动
-- **复制功能**: 一键复制单元格内容
-- **文本省略**: 单行和多行文本截断，支持省略号
-- **提示框**: 单元格和表头悬停提示，支持自定义内容
-- **响应式**: 移动端友好设计
-- **TypeScript**: 完整的 TypeScript 支持
-
-### 示例
-
-#### 基础表格
-
-```tsx
-<ProTable
-  columns={columns}
-  dataSource={dataSource}
+  ]}
+  search={{ filterType: 'query' }}
+  pagination={{
+    pageSize: 10,
+    showSizeChanger: true,
+    showQuickJumper: true,
+  }}
   rowKey="id"
 />
 ```
 
-#### 带搜索
-
-表格提供了**默认搜索行为**，会自动工作：
-
-- **本地数据模式**（无 `request` 属性）：搜索值会自动转换为 TanStack Table 的 `columnFilters`，表格使用 `getFilteredRowModel()` 实时过滤数据。
-- **远程数据模式**（有 `request` 属性）：搜索会触发新的数据获取，搜索参数会传递给后端。
-
-默认过滤函数支持：
-- **文本类字段**：不区分大小写的字符串匹配（包含）
-- **枚举 / 筛选类字段**：精确匹配（例如 `valueEnum`、`filters`、`valueType: 'select' | 'status'`）
-- 基于数组的多选过滤（枚举 / 筛选类字段为精确匹配；文本类字段为包含匹配）
-- 自动处理空值 /null 值
+### 2. Fixed Columns with Horizontal Scroll
 
 ```tsx
 <ProTable
-  columns={columns}
-  dataSource={dataSource}
+  columns={[
+    {
+      title: 'ID',
+      dataIndex: 'id',
+      width: 80,
+      fixed: 'left',  // Pin to left
+    },
+    {
+      title: 'Name',
+      dataIndex: 'name',
+      width: 150,
+      fixed: 'left',
+    },
+    { title: 'Email', dataIndex: 'email', width: 200 },
+    { title: 'Phone', dataIndex: 'phone', width: 150 },
+    { title: 'Address', dataIndex: 'address', width: 300 },
+    {
+      title: 'Actions',
+      key: 'actions',
+      width: 100,
+      fixed: 'right',  // Pin to right
+      render: (_, record) => (
+        <Button size="sm">Edit</Button>
+      ),
+    },
+  ]}
+  dataSource={data}
+  scroll={{ x: 1200 }}  // Enable horizontal scroll
+  tableLayout="fixed"    // Required for fixed columns
   rowKey="id"
-  search={{
-    filterType: 'query',
-    searchText: '搜索',
-    resetText: '重置'
-  }}
 />
 ```
 
-**自定义搜索行为：**
-
-您可以提供自定义的 `onSearch` 和 `onReset` 回调来覆盖默认行为：
+### 3. Tree Table with Expandable Rows
 
 ```tsx
 <ProTable
-  columns={columns}
-  dataSource={dataSource}
-  rowKey="id"
-  search={{
-    filterType: 'query',
-    onSearch: (values) => {
-      // 自定义搜索逻辑
-      console.log('搜索值:', values)
+  columns={[
+    { title: 'Name', dataIndex: 'name', width: 200 },
+    { title: 'Size', dataIndex: 'size' },
+    { title: 'Type', dataIndex: 'type' },
+  ]}
+  dataSource={[
+    {
+      id: 1,
+      name: 'Folder 1',
+      type: 'folder',
+      children: [
+        { id: 11, name: 'File 1.1', type: 'file', size: '1.2 MB' },
+        { id: 12, name: 'File 1.2', type: 'file', size: '2.5 MB' },
+      ],
     },
-    onReset: () => {
-      // 自定义重置逻辑
-      console.log('重置搜索')
-    }
+    {
+      id: 2,
+      name: 'Folder 2',
+      type: 'folder',
+      children: [
+        { id: 21, name: 'File 2.1', type: 'file', size: '3.1 MB' },
+      ],
+    },
+  ]}
+  expandable={{
+    defaultExpandAllRows: false,
+    accordion: false,  // Allow multiple rows expanded
   }}
+  rowKey="id"
 />
 ```
 
-#### 带分页
+### 4. Inline Editing
 
 ```tsx
+const [editableKeys, setEditableKeys] = useState<React.Key[]>([])
+
 <ProTable
-  columns={columns}
-  dataSource={dataSource}
-  rowKey="id"
-  pagination={{
-    pageSize: 10,
-    showSizeChanger: true
+  columns={[
+    {
+      title: 'Name',
+      dataIndex: 'name',
+      editable: true,
+    },
+    {
+      title: 'Age',
+      dataIndex: 'age',
+      valueType: 'number',
+      editable: true,
+    },
+    {
+      title: 'Email',
+      dataIndex: 'email',
+      editable: true,
+    },
+  ]}
+  dataSource={data}
+  editable={{
+    type: 'multiple',
+    editableKeys,
+    onChange: setEditableKeys,
+    onSave: async (key, record, originRow) => {
+      // Save to backend
+      await updateUser(key, record)
+      message.success('Saved successfully')
+    },
   }}
+  rowKey="id"
 />
 ```
 
-#### 远程分页（配合 `request`）
-
-在**远程数据模式**（传入 `request`）下，分页规则如下：
-
-- **`total` 决定页码数量**：推荐让 `request` 返回 `{ total }`，也可以 / 同时传入 `pagination.total`。
-- **不要把 `pagination.current/pageSize` 写死**（例如 `current: 1`），除非你就是想把表格锁死在那一页；如果需要受控分页，请把它们放到 state 里，并在 `pagination.onChange` 里更新。
-
-**非受控（推荐：不需要外部同步分页状态时）**：
+### 5. Drag & Drop Reordering
 
 ```tsx
 <ProTable
   columns={columns}
-  rowKey="id"
-  request={async (params) => {
-    // params 包含：current, pageSize, ...filters, ...sorter
-    const res = await fetchUsers(params)
-    return { data: res.items, total: res.total, success: true }
-  }}
-  pagination={{
-    pageSize: 10,
-    showSizeChanger: true,
-    showQuickJumper: true,
+  dataSource={data}
+  draggable={{
+    enabled: true,
+    handle: true,  // Show drag handle
+    onDragEnd: (result) => {
+      const { items, oldIndex, newIndex } = result
+      console.log('New order:', items)
+      // Update backend order
+      updateOrder(items.map(item => item.id))
+    },
   }}
+  rowKey="id"
 />
 ```
 
-**受控（需要把分页状态同步到外部 state / URL 时）**：
-
-```tsx
-function Page() {
-  const [pagination, setPagination] = useState({
-    current: 1,
-    pageSize: 10,
-    total: 0,
-  })
-
-  return (
-    <ProTable
-      columns={columns}
-      rowKey="id"
-      request={async (params) => {
-        const res = await fetchUsers(params)
-        setPagination((prev) => ({ ...prev, total: res.total }))
-        return { data: res.items, total: res.total, success: true }
-      }}
-      pagination={{
-        current: pagination.current,
-        pageSize: pagination.pageSize,
-        total: pagination.total,
-        showSizeChanger: true,
-        showQuickJumper: true,
-        onChange: (current, pageSize) => {
-          setPagination((prev) => ({ ...prev, current, pageSize }))
-        },
-      }}
-    />
-  )
-}
-```
-
-#### 服务端分页（不传 `request`，外部自行请求）
-
-如果你**不使用** `request`，但希望实现**服务端分页**（也就是 `dataSource` 只提供“当前页 items”），请设置
-`pagination.mode: 'server'`，避免 TanStack Table 再次 slice 导致第 2 页为空 / 数据错乱。
-
-```tsx
-function Page() {
-  const [pagination, setPagination] = useState({ current: 1, pageSize: 10, total: 0 })
-  const [data, setData] = useState<any[]>([])
-
-  const fetchPage = async (current: number, pageSize: number) => {
-    const res = await fetchUsers({ current, pageSize })
-    setData(res.items)
-    setPagination((prev) => ({ ...prev, current, pageSize, total: res.total }))
-  }
-
-  useEffect(() => {
-    void fetchPage(pagination.current, pagination.pageSize)
-  }, [])
-
-  return (
-    <ProTable
-      columns={columns}
-      rowKey="id"
-      dataSource={data}
-      pagination={{
-        mode: "server",
-        current: pagination.current,
-        pageSize: pagination.pageSize,
-        total: pagination.total,
-        onChange: (current, pageSize) => void fetchPage(current, pageSize),
-      }}
-    />
-  )
-}
-```
-
-#### 自定义分页渲染（`paginationRender`）
-
-当你想把分页 UI 放到任意布局 / 卡片里，并且仍复用 ProTable 内置分页状态 / 逻辑时，使用 `paginationRender`：
-
-- `paginationRender` 会拿到 `pagination`、`onChange`、`defaultDom`
-- 如果你是 **服务端分页模式**（`pagination.mode: 'server'`），务必同时提供 `pagination.onChange` 去请求数据
+### 6. Custom Cell Rendering
 
 ```tsx
 <ProTable
-  columns={columns}
-  rowKey="id"
-  dataSource={data}
-  pagination={{
-    mode: "server",
-    current,
-    pageSize,
-    total,
-    onChange: (page, pageSize) => void fetchPage(page, pageSize),
-  }}
-  paginationRender={({ pagination, onChange, defaultDom }) => (
-    <div className="space-y-2">
-      <div className="flex items-center justify-between rounded border p-2">
-        <div className="text-sm text-muted-foreground">
-          自定义分页：第 {pagination.current} 页 / 每页 {pagination.pageSize} 条 / 共 {pagination.total} 条
-        </div>
-        <div className="flex gap-2">
-          <button onClick={() => onChange(Math.max(1, pagination.current - 1), pagination.pageSize)}>
-            上一页
-          </button>
-          <button onClick={() => onChange(pagination.current + 1, pagination.pageSize)}>
-            下一页
-          </button>
+  columns={[
+    {
+      title: 'Avatar',
+      dataIndex: 'avatar',
+      valueType: 'avatar',
+      render: (_, record) => (
+        <Avatar>
+          <AvatarImage src={record.avatar} />
+          <AvatarFallback>{record.name[0]}</AvatarFallback>
+        </Avatar>
+      ),
+    },
+    {
+      title: 'Status',
+      dataIndex: 'status',
+      valueType: 'status',
+      valueEnum: {
+        active: { text: 'Active', status: 'success' },
+        inactive: { text: 'Inactive', status: 'default' },
+        pending: { text: 'Pending', status: 'warning' },
+      },
+      render: (_, record) => (
+        <Badge variant={record.status === 'active' ? 'success' : 'secondary'}>
+          {record.status}
+        </Badge>
+      ),
+    },
+    {
+      title: 'Progress',
+      dataIndex: 'progress',
+      valueType: 'progress',
+      render: (_, record) => (
+        <div className="flex items-center gap-2">
+          <Progress value={record.progress} className="w-20" />
+          <span className="text-xs">{record.progress}%</span>
         </div>
-      </div>
-      {defaultDom}
-    </div>
-  )}
+      ),
+    },
+  ]}
+  dataSource={data}
+  rowKey="id"
 />
 ```
 
-#### 带国际化
+### 7. Multi-line Ellipsis with Tooltip
 
 ```tsx
-import { ProTable, zh_CN } from '@gulibs/react-vtable'
-
 <ProTable
-  columns={columns}
-  dataSource={dataSource}
+  columns={[
+    {
+      title: 'Description',
+      dataIndex: 'description',
+      width: 300,
+      ellipsis: {
+        multiline: true,
+        rows: 3,  // Show 3 lines max
+      },
+      tooltip: {
+        content: (value) => value,
+        side: 'top',
+      },
+    },
+    {
+      title: 'Long Title Column with Header Tooltip',
+      dataIndex: 'data',
+      width: 150,
+      headerEllipsis: true,  // Header ellipsis
+      headerTooltip: {
+        content: 'This is a very long header title that needs tooltip',
+        side: 'bottom',
+      },
+      ellipsis: true,  // Cell ellipsis
+      tooltip: true,   // Cell tooltip
+    },
+  ]}
+  dataSource={data}
   rowKey="id"
-  locale={zh_CN}
 />
 ```
 
-#### 带固定列
-
-固定列功能基于 TanStack Table 的 column pinning 实现。库会自动计算位置并应用柔和的阴影效果来标识固定列边界。
+### 8. Custom Search Form
 
 ```tsx
 <ProTable
   columns={[
     {
-      title: 'ID',
-      dataIndex: 'id',
-      key: 'id',
-      width: 80,
-      fixed: 'left'  // 固定在左侧
+      title: 'Name',
+      dataIndex: 'name',
+      search: true,
     },
     {
-      title: '姓名',
-      dataIndex: 'name',
-      key: 'name',
-      width: 120
+      title: 'Date Range',
+      dataIndex: 'dateRange',
+      valueType: 'dateRange',
+      search: true,
+      renderFormItem: (value, onChange) => (
+        <DateRangePicker
+          value={value}
+          onChange={onChange}
+        />
+      ),
     },
     {
-      title: '操作',
-      dataIndex: 'actions',
-      key: 'actions',
-      width: 100,
-      fixed: 'right'  // 固定在右侧
-    }
+      title: 'Custom Filter',
+      dataIndex: 'customField',
+      search: {
+        transform: (value) => {
+          // Transform before sending to backend
+          return { customFieldQuery: value.toUpperCase() }
+        },
+      },
+      renderFormItem: (value, onChange) => (
+        <CustomFilterComponent
+          value={value}
+          onChange={onChange}
+        />
+      ),
+    },
   ]}
-  dataSource={dataSource}
+  request={fetchData}
+  search={{ filterType: 'query' }}
   rowKey="id"
-  scroll={{ x: 1000 }}  // 启用横向滚动
-  tableLayout="fixed"    // 固定列推荐使用 fixed 布局
 />
 ```
 
-**重要提示：**
-- 固定列需要设置 `width` 属性才能正确计算位置
-- 库会自动使用 TanStack Table 的 `getStart()` 和 `getAfter()` 方法计算位置
-- 最后一个左侧固定列和第一个右侧固定列会自动应用柔和的阴影效果
-- 无需额外 CSS - 所有样式都通过内联样式应用
+---
+
+## Best Practices
 
-#### 带树形表格（可展开行）
+### 1. Performance Optimization
 
-树形表格支持层次数据结构，可展开 / 收起行。数据结构应包含 `children` 属性（或自定义字段名）来存储嵌套行。
+#### Use `rowKey` Correctly
+Always provide a stable, unique `rowKey`:
 
 ```tsx
-<ProTable
-  columns={columns}
-  dataSource={[
-    {
-      id: 1,
-      name: '父节点',
-      children: [
-        { id: 11, name: '子节点 1' },
-        { id: 12, name: '子节点 2' }
-      ]
-    }
-  ]}
-  rowKey="id"
-  expandable={{
-    childrenColumnName: 'children',  // 默认: 'children'
-    defaultExpandAllRows: false,     // 默认展开所有行
-    defaultExpandedRowKeys: [1],     // 初始展开的行
-    accordion: false,                // 手风琴模式（同时只能展开一行）
-    showExpandColumn: true,          // 显示展开图标列
-    expandColumnWidth: 50,           // 展开列宽度
-    onExpand: (expanded, record) => {
-      console.log('展开:', expanded, record)
-    },
-    onExpandedRowsChange: (expandedRowKeys) => {
-      console.log('展开的行:', expandedRowKeys)
-    },
-    expandIcon: ({ expanded, onExpand, record }) => (
-      <Button onClick={onExpand}>
-        {expanded ? '▼' : '▶'}
-      </Button>
-    )
-  }}
-/>
+// Good: Use unique ID
+<ProTable rowKey="id" />
+
+// Good: Use function for complex keys
+<ProTable rowKey={(record) => `${record.type}-${record.id}`} />
+
+// Bad: Use index (causes re-render issues)
+<ProTable rowKey={(record, index) => index} />
 ```
 
-**树形表格特性：**
-- **受控 / 非受控模式**: 使用 `expandedRowKeys` 实现受控模式，或使用 `defaultExpandedRowKeys` 实现非受控模式
-- **默认全部展开**: 设置 `defaultExpandAllRows: true` 来默认展开所有行
-- **手风琴模式**: 设置 `accordion: true` 来同时只允许展开一行
-- **自定义子字段**: 使用 `childrenColumnName` 指定自定义的子字段名（默认：`'children'`）
-- **自定义展开图标**: 提供自定义 `expandIcon` 函数来定制展开 / 收起图标
-- **展开回调**: 使用 `onExpand` 和 `onExpandedRowsChange` 来处理展开状态变化
+#### Memoize Large Data
+For large datasets, memoize your data:
+
+```tsx
+const data = useMemo(() => generateLargeData(), [])
+
+<ProTable dataSource={data} />
+```
 
-#### 带可编辑行
+#### Optimize Column Rendering
+Use `useMemo` for column definitions with complex render functions:
 
+```tsx
+const columns = useMemo(() => [
+  {
+    title: 'Name',
+    render: (_, record) => <ComplexComponent record={record} />,
+  },
+], [dependencies])
+```
+
+### 2. Request Best Practices
+
+#### Handle Errors Gracefully
 ```tsx
 <ProTable
-  columns={columns}
-  dataSource={dataSource}
-  rowKey="id"
-  editable={{
-    type: 'multiple',
-    onSave: async (key, record, originRow) => {
-      console.log('保存:', { key, record, originRow })
-      // 处理保存逻辑
+  request={async (params) => {
+    try {
+      const res = await fetchData(params)
+      return { data: res.items, total: res.total, success: true }
+    } catch (error) {
+      message.error('Failed to load data')
+      return { data: [], total: 0, success: false }
     }
   }}
+  onRequestError={(error) => {
+    console.error('Request error:', error)
+    // Report to error tracking service
+  }}
 />
 ```
 
-#### 带行选择和批量操作
+#### Debounce Search Requests
+Use `params` prop to trigger re-fetch:
 
 ```tsx
+const [searchParams, setSearchParams] = useState({})
+const debouncedSearch = useMemo(
+  () => debounce((value) => setSearchParams({ keyword: value }), 500),
+  []
+)
+
 <ProTable
-  columns={columns}
-  dataSource={dataSource}
-  rowKey="id"
-  rowSelection={{
-    type: 'checkbox',
-    onChange: (selectedRowKeys, selectedRows) => {
-      console.log('已选择:', selectedRowKeys, selectedRows)
+  request={fetchData}
+  params={searchParams}
+  toolbar={{
+    search: {
+      onSearch: debouncedSearch,
     },
-    batchActions: {
-      onDelete: (rows) => {
-        console.log('删除:', rows)
-      },
-      onExport: (rows) => {
-        console.log('导出:', rows)
-      }
-    }
   }}
 />
 ```
 
-**跨页选中支持：**
-
-当使用 `request` 或 `pagination.onChange` 进行远程数据获取时，表格会自动维护跨页选中状态。这意味着：
+### 3. State Management
 
-- 在某一页选择的行，在切换到其他页面时会保留
-- 批量操作栏会显示**所有页面**的选中总数
-- 当返回到之前访问过的页面时，之前的选中状态会自动恢复
-- `onChange` 回调会接收到所有页面的选中行 keys
+#### Controlled Components
+For complex state management, use controlled mode:
 
 ```tsx
+const [selectedRowKeys, setSelectedRowKeys] = useState<React.Key[]>([])
+const [pagination, setPagination] = useState({ current: 1, pageSize: 10 })
+
 <ProTable
-  columns={columns}
-  rowKey="id"
-  request={async (params) => {
-    const res = await fetchUsers(params)
-    return { data: res.items, total: res.total, success: true }
-  }}
   rowSelection={{
-    type: 'checkbox',
-    onChange: (selectedRowKeys, selectedRows) => {
-      // selectedRowKeys 包含所有页面的选中 keys
-      // selectedRows 仅包含当前页的行数据
-      console.log('所有页面选中的总数:', selectedRowKeys.length)
-    },
-    batchActions: {
-      onDelete: (rows) => {
-        // 这里只会收到当前页的行数据
-        // 如需操作所有选中的行，请使用 onChange 中的 selectedRowKeys
-        console.log('删除当前页行:', rows)
-      }
-    }
+    selectedRowKeys,
+    onChange: setSelectedRowKeys,
   }}
   pagination={{
-    pageSize: 10,
-    showSizeChanger: true,
+    ...pagination,
     onChange: (current, pageSize) => {
-      // 切换页面时，选中状态会自动保留
-    }
+      setPagination({ current, pageSize })
+    },
   }}
 />
 ```
 
-**重要提示：**
-- 跨页选中在使用 `request` 或 `pagination.onChange` 时会自动生效
-- 使用 `dataSource`（本地数据）时，选中功能正常工作，但不需要跨页支持
-- 批量操作栏始终显示所有页面的选中总数
-- 如需对所有选中的行进行操作，请使用 `rowSelection.onChange` 获取所有选中的 keys
+#### Use Action Ref
+Access table methods via `actionRef`:
 
-**自动清空选中状态：**
+```tsx
+const actionRef = useRef<ProTableAction<DataType>>(null)
 
-某些批量操作后，选中状态会自动清空：
+const handleRefresh = () => {
+  actionRef.current?.reload()
+}
 
-- **删除操作**：删除后自动清空选中状态（因为数据已被删除）
-- **归档操作**：归档后自动清空选中状态
-- **自定义操作**：可以通过 `clearSelection` 选项控制是否清空选中状态
-- **隐藏清空按钮**：可以通过 `hideClearButton` 选项隐藏清空按钮
+const handleReset = () => {
+  actionRef.current?.reset()
+  actionRef.current?.clearSelected()
+}
 
-```tsx
-<ProTable
-  rowSelection={{
-    type: 'checkbox',
-    batchActions: {
-      onDelete: (rows) => {
-        // 删除操作 - 选中状态会自动清空
-        console.log('删除:', rows)
-      },
-      onArchive: (rows) => {
-        // 归档操作 - 选中状态会自动清空
-        console.log('归档:', rows)
-      },
-      // 如需隐藏清空按钮
-      hideClearButton: false,
-      customActions: [
-        {
-          key: 'approve',
-          label: '批量审批',
-          onClick: (rows) => {
-            console.log('审批:', rows)
-          },
-          // 控制操作后是否清空选中状态
-          clearSelection: true, // 设置为 true 表示操作后清空选中状态
-        },
-        {
-          key: 'export',
-          label: '导出',
-          onClick: (rows) => {
-            console.log('导出:', rows)
-          },
-          clearSelection: false, // 导出后保留选中状态（默认值）
-        }
-      ]
-    }
-  }}
-/>
+<ProTable actionRef={actionRef} />
 ```
 
-#### 带文本省略和提示框
+### 4. Accessibility
 
-```tsx
-<ProTable
-  columns={[
-    {
-      title: '描述',
-      dataIndex: 'description',
-      key: 'description',
-      width: 200,
-      // 单行省略，带提示框
-      ellipsis: true,
-      tooltip: true
-    },
-    {
-      title: '内容',
-      dataIndex: 'content',
-      key: 'content',
-      width: 250,
-      // 多行省略（2行），带提示框
-      ellipsis: {
-        multiline: true,
-        rows: 2
-      },
-      tooltip: true
-    },
-    {
-      title: '自定义提示',
-      dataIndex: 'name',
-      key: 'name',
-      width: 150,
-      ellipsis: true,
-      tooltip: {
-        content: (value, record) => `完整内容: ${record.fullName || value}`,
-        side: 'top',
-        delayDuration: 300
-      }
-    },
-    {
-      title: '表头省略',
-      dataIndex: 'email',
-      key: 'email',
-      width: 180,
-      // 表头独立的省略和提示配置
-      headerEllipsis: true,
-      headerTooltip: {
-        content: '这是完整的表头标题',
-        side: 'bottom'
-      },
-      // 单元格省略和提示
-      ellipsis: true,
-      tooltip: true
-    }
-  ]}
-  dataSource={dataSource}
-  rowKey="id"
-/>
-```
+- Always provide meaningful `title` for columns
+- Use `aria-label` for action buttons
+- Ensure color contrast for status badges
+- Test with keyboard navigation
 
-### API 参考
-
-#### ProTable 属性
-
-| 属性 | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `columns` | `ProColumn[]` | `[]` | 表格列定义 |
-| `dataSource` | `T[]` | `[]` | 表格数据源 |
-| `rowKey` | `string \| (record: T) => string` | `'id'` | 每行的唯一键 |
-| `loading` | `boolean` | `false` | 加载状态 |
-| `pagination` | `ProTablePagination \| false` | `false` | 分页配置 |
-| `search` | `ProTableSearch \| false` | `false` | 搜索表单配置 |
-| `rowSelection` | `ProTableRowSelection` | `undefined` | 行选择配置 |
-| `editable` | `ProTableEditable` | `undefined` | 可编辑行配置 |
-| `draggable` | `ProTableDraggable` | `undefined` | 拖拽配置 |
-| `expandable` | `ProTableExpandable \| false` | `undefined` | 树形表格展开配置 |
-| `scroll` | `{ x?: number \| true; y?: number \| string }` | `undefined` | 滚动配置 |
-| `tableLayout` | `'auto' \| 'fixed'` | `'auto'` | 表格布局模式 |
-| `locale` | `ProTableLocale` | `en_US` | 国际化语言包 |
-| `size` | `'small' \| 'middle' \| 'large'` | `'middle'` | 表格尺寸 |
-| `bordered` | `boolean` | `false` | 显示表格边框 |
-
-#### 列配置
-
-| 属性 | 类型 | 描述 |
-|------|------|------|
-| `title` | `string` | 列头文本 |
-| `dataIndex` | `string` | 数据字段名 |
-| `key` | `string` | 唯一列键 |
-| `width` | `number` | 列宽度（像素） |
-| `fixed` | `'left' \| 'right'` | 固定列位置 |
-| `sorter` | `boolean` | 启用排序 |
-| `editable` | `boolean` | 启用内联编辑 |
-| `copyable` | `boolean` | 启用复制到剪贴板 |
-| `ellipsis` | `boolean \| ProColumnEllipsis` | 启用文本省略（单行或多行） |
-| `tooltip` | `boolean \| ProColumnTooltip` | 启用悬停提示框 |
-| `headerEllipsis` | `boolean \| ProColumnEllipsis` | 启用表头省略（默认使用 `ellipsis`） |
-| `headerTooltip` | `boolean \| ProColumnTooltip` | 启用表头提示框（默认使用 `tooltip`） |
-| `search` | `boolean` | 包含在搜索表单中 |
-| `valueType` | `ProFieldValueType` | 值类型渲染 |
-| `valueEnum` | `Record<string, { text: string; status?: string }>` | 枚举值选择 |
-| `filters` | `Array<{ text: string; value: any }>` | 筛选选项 |
-
-#### 省略号配置
-
-`ellipsis` 和 `headerEllipsis` 属性支持以下配置：
+### 5. Internationalization
 
 ```tsx
-// 单行省略
-ellipsis: true
+import { ProTable, zh_CN, en_US } from '@gulibs/react-vtable'
+import { useState } from 'react'
 
-// 多行省略
-ellipsis: {
-  multiline: true,
-  rows: 2  // 行数（1-5）
+function App() {
+  const [locale, setLocale] = useState(en_US)
+
+  return (
+    <>
+      <Button onClick={() => setLocale(zh_CN)}>中文</Button>
+      <Button onClick={() => setLocale(en_US)}>English</Button>
+      
+      <ProTable
+        locale={locale}
+        columns={columns}
+        dataSource={data}
+      />
+    </>
+  )
 }
 ```
 
-#### 提示框配置
+### 6. Type Safety
 
-`tooltip` 和 `headerTooltip` 属性支持以下配置：
+Always provide TypeScript types for your data:
 
 ```tsx
-// 简单提示框（显示单元格值）
-tooltip: true
-
-// 自定义提示框
-tooltip: {
-  content: '自定义提示文本',
-  side: 'top' | 'right' | 'bottom' | 'left',
-  align: 'start' | 'center' | 'end',
-  delayDuration: 300,
-  disabled: false
+interface User {
+  id: string
+  name: string
+  email: string
+  age: number
+  status: 'active' | 'inactive'
 }
 
-// 函数式提示框
-tooltip: {
-  content: (value, record, index) => `完整内容: ${value}\nID: ${record.id}`,
-  side: 'top'
-}
+const columns: ProColumn<User>[] = [
+  {
+    title: 'Name',
+    dataIndex: 'name',
+    // TypeScript will validate dataIndex, valueType, render function params, etc.
+  },
+]
+
+<ProTable<User>
+  columns={columns}
+  dataSource={users}
+  rowKey="id"
+/>
 ```
 
-**注意**: 当 `ellipsis` 启用且 `tooltip` 为 `true` 时，如果文本被截断，提示框会自动显示完整的原始值（而不是渲染后的值）。
+---
 
-#### 展开配置（树形表格）
+## Development
 
-`expandable` 属性支持以下配置：
+```bash
+# Install dependencies
+pnpm install
 
-```tsx
-expandable: {
-  // 自定义子字段名（默认: 'children'）
-  childrenColumnName?: string
+# Start development server
+pnpm run dev
 
-  // 默认展开的行 key 数组（非受控模式）
-  defaultExpandedRowKeys?: React.Key[]
+# Build library
+pnpm run build
 
-  // 当前展开的行 key 数组（受控模式）
-  expandedRowKeys?: React.Key[]
+# Lint code
+pnpm run lint
+```
 
-  // 展开/收起回调
-  onExpand?: (expanded: boolean, record: T) => void
+---
 
-  // 展开的行 key 变化回调
-  onExpandedRowsChange?: (expandedRowKeys: React.Key[]) => void
+## License
 
-  // 自定义展开图标
-  expandIcon?: (props: {
-    expanded: boolean
-    onExpand: () => void
-    record: T
-  }) => ReactNode
+MIT © [@gulibs](https://github.com/gulibs)
+
+---
+
+## Chinese
+
+## 中文文档
 
-  // 显示展开列（默认: true）
-  showExpandColumn?: boolean
+[查看完整中文文档 ↗](./README.zh-CN.md)
 
-  // 展开列宽度（默认: 50）
-  expandColumnWidth?: number
+### 快速开始
+
+```tsx
+import { ProTable, zh_CN } from '@gulibs/react-vtable'
+
+function App() {
+  const columns = [
+    { title: '姓名', dataIndex: 'name', key: 'name' },
+    { title: '年龄', dataIndex: 'age', key: 'age' },
+  ]
 
-  // 默认展开所有行（默认: false）
-  defaultExpandAllRows?: boolean
+  const dataSource = [
+    { id: 1, name: '张三', age: 30 },
+    { id: 2, name: '李四', age: 25 },
+  ]
 
-  // 手风琴模式 - 同时只能展开一行（默认: false）
-  accordion?: boolean
+  return (
+    <ProTable
+      columns={columns}
+      dataSource={dataSource}
+      rowKey="id"
+      locale={zh_CN}
+    />
+  )
 }
 ```
 
-### 开发
-
-```bash
-# 安装依赖
-pnpm install
+### 主要特性
+
+- ✨ 强大的表格：基于 TanStack Table v8
+- 🎨 精美组件：shadcn/ui 设计
+- 🔍 搜索筛选：自动处理本地/远程数据
+- 📄 分页支持：客户端和服务端分页
+- ✅ 行选择：支持跨页选中
+- 🎯 批量操作：灵活的批量操作配置
+- ✏️ 内联编辑：支持验证
+- 📌 固定列：左右固定，自动阴影
+- 🌳 树形表格：层次数据展示
+- 🔄 拖拽排序：行列拖拽重排
+- 📱 响应式设计：移动端友好
+- 🌐 国际化：内置中英文
+- 🎭 丰富类型：20+ 值类型
+- 💬 提示框：单元格和表头提示
+- 📏 文本省略：单行和多行截断
+- 🔧 TypeScript：完整类型支持
+
+### 批量操作示例
 
-# 构建库
-pnpm run build
+```tsx
+import { Trash2, Download, FileText } from 'lucide-react'
 
-# 启动开发服务器
-pnpm run dev
+<ProTable
+  rowSelection={{
+    type: 'checkbox',
+    batchActions: {
+      maxVisibleActions: 3,
+      actions: [
+        {
+          key: 'delete',
+          label: '删除',
+          icon: <Trash2 className="h-3 w-3 mr-1" />,
+          onClick: (rows) => console.log('删除:', rows),
+          variant: 'destructive',
+          clearSelection: true,
+        },
+        {
+          key: 'export',
+          label: '导出',
+          icon: <Download className="h-3 w-3 mr-1" />,
+          onClick: (rows) => console.log('导出:', rows),
+          variant: 'outline',
+        },
+        {
+          key: 'exportExcel',
+          label: '导出 Excel',
+          icon: <FileText className="h-3 w-3 mr-1" />,
+          onClick: (rows) => console.log('导出 Excel:', rows),
+          variant: 'outline',
+          isExportFormat: true,
+          showInMore: true,
+        },
+      ],
+    },
+  }}
+  dataSource={data}
+  rowKey="id"
+  locale={zh_CN}
+/>
 ```
 
-### 许可证
+### 更多文档
+
+完整的中文文档和 API 参考，请查看英文部分。所有功能和 API 在中英文版本中都是一致的。
+
+---
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Support
 
-MIT
+If you have any questions or need help, please open an issue on [GitHub](https://github.com/gulibs/react-vtable).