@beppla/tapas-ui 1.5.10 → 1.5.12

package/package/module/TableColumnHeader/README.md

@@ -0,0 +1,682 @@
+# TapasTableColumnHeader
+
+一个功能完整的表格列头组件，支持排序功能、文本对齐、自定义样式和丰富的交互选项。适用于数据表格、网格视图和可排序列表。
+
+## 功能特性
+
+- ✅ 完整的排序功能（升序、降序、无排序）
+- ✅ 灵活的文本对齐选项（左、中、右）
+- ✅ 可自定义的排序指示器
+- ✅ 丰富的样式配置选项
+- ✅ 完整的交互支持（点击、长按）
+- ✅ 响应式设计和可访问性
+- ✅ TypeScript 类型支持
+- ✅ 向后兼容的导出别名
+
+## 安装使用
+
+```tsx
+import { TapasTableColumnHeader } from '@beppla/tapas-ui';
+
+// 基础用法
+<TapasTableColumnHeader title="Product Name" />
+
+// 可排序列头
+<TapasTableColumnHeader 
+  title="Price"
+  fieldName="price"
+  sortable={true}
+  sortDirection="ASC"
+  onSort={(field, direction) => handleSort(field, direction)}
+/>
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `title` | `string` | **必填** | 列标题文本 |
+| `columnIndex` | `number` | - | 列索引 |
+| `fieldName` | `string` | - | 字段名称（用于排序标识） |
+| `sortable` | `boolean` | `false` | 是否支持排序 |
+| `sortDirection` | `SortDirection` | `null` | 当前排序状态 (`"ASC"` \| `"DESC"` \| `null`) |
+| `textAlign` | `"left" \| "center" \| "right"` | `"left"` | 文本对齐方式 |
+| `titleStyle` | `StyleProp<TextStyle>` | - | 标题文本样式 |
+| `sortButtonStyle` | `StyleProp<ViewStyle>` | - | 排序按钮样式 |
+| `padding` | `{horizontal?: number, vertical?: number}` | `{horizontal: 16, vertical: 8}` | 容器内边距 |
+| `onSort` | `(fieldName: string, direction: SortDirection, columnIndex?: number) => void` | - | 排序回调函数 |
+| `onPress` | `(fieldName: string, columnIndex?: number) => void` | - | 点击回调函数 |
+| `onLongPress` | `(fieldName: string, columnIndex?: number) => void` | - | 长按回调函数 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `sortIconSize` | `number` | `18` | 排序图标大小 |
+| `activeSortIconColor` | `string` | 主题色 | 排序图标颜色（激活状态） |
+| `inactiveSortIconColor` | `string` | 灰色 | 排序图标颜色（非激活状态） |
+| `sortIcons` | `{ascending?: string, descending?: string}` | `{ascending: "arrow_drop_up", descending: "arrow_drop_down"}` | 自定义排序图标名称 |
+| `showSortIndicator` | `boolean` | `true` | 是否显示排序状态指示器 |
+| `minHeight` | `number` | `40` | 最小高度 |
+
+## 类型定义
+
+```tsx
+export type SortDirection = "ASC" | "DESC" | null;
+
+export interface SortState {
+  field: string;
+  direction: SortDirection;
+}
+```
+
+## 使用示例
+
+### 基础列头
+
+```tsx
+import React from 'react';
+import { TapasTableColumnHeader } from '@beppla/tapas-ui';
+
+const BasicExample = () => {
+  return (
+    <TapasTableColumnHeader 
+      title="Product Name"
+      textAlign="left"
+    />
+  );
+};
+```
+
+### 可排序列头
+
+```tsx
+import React, { useState } from 'react';
+import { TapasTableColumnHeader, SortDirection } from '@beppla/tapas-ui';
+
+const SortableExample = () => {
+  const [sortDirection, setSortDirection] = useState<SortDirection>(null);
+  
+  const handleSort = (fieldName: string, direction: SortDirection) => {
+    setSortDirection(direction);
+    console.log(`Sorting ${fieldName} in ${direction || 'default'} order`);
+  };
+
+  return (
+    <TapasTableColumnHeader 
+      title="Price"
+      fieldName="price"
+      sortable={true}
+      sortDirection={sortDirection}
+      textAlign="right"
+      onSort={handleSort}
+    />
+  );
+};
+```
+
+### 完整数据表格
+
+```tsx
+import React, { useState } from 'react';
+import { View } from 'react-native';
+import { TapasTableColumnHeader, SortDirection, SortState } from '@beppla/tapas-ui';
+
+const DataTable = () => {
+  const [sortState, setSortState] = useState<SortState>({
+    field: '',
+    direction: null
+  });
+
+  const columns = [
+    { title: 'ID', field: 'id', sortable: true, align: 'left' },
+    { title: 'Product Name', field: 'name', sortable: true, align: 'left' },
+    { title: 'Category', field: 'category', sortable: true, align: 'center' },
+    { title: 'Price', field: 'price', sortable: true, align: 'right' },
+    { title: 'Stock', field: 'stock', sortable: true, align: 'right' },
+    { title: 'Actions', field: 'actions', sortable: false, align: 'center' },
+  ];
+
+  const handleSort = (fieldName: string, direction: SortDirection) => {
+    setSortState({ field: fieldName, direction });
+    
+    // 这里可以调用 API 或本地排序逻辑
+    console.log(`Sorting by ${fieldName} in ${direction || 'default'} order`);
+  };
+
+  return (
+    <View style={{ flexDirection: 'row', backgroundColor: 'white' }}>
+      {columns.map((column, index) => (
+        <View key={column.field} style={{ flex: 1 }}>
+          <TapasTableColumnHeader
+            title={column.title}
+            fieldName={column.field}
+            columnIndex={index}
+            sortable={column.sortable}
+            textAlign={column.align as any}
+            sortDirection={
+              sortState.field === column.field ? sortState.direction : null
+            }
+            onSort={handleSort}
+          />
+        </View>
+      ))}
+    </View>
+  );
+};
+```
+
+### 自定义样式
+
+```tsx
+import React from 'react';
+import { TapasTableColumnHeader } from '@beppla/tapas-ui';
+
+const CustomStyledExample = () => {
+  return (
+    <View style={{ gap: 16 }}>
+      {/* 自定义颜色主题 */}
+      <TapasTableColumnHeader 
+        title="Custom Colors"
+        fieldName="custom"
+        sortable={true}
+        sortDirection="ASC"
+        titleStyle={{ 
+          color: '#FF6B6B', 
+          fontWeight: 'bold',
+          fontSize: 16 
+        }}
+        activeSortIconColor="#FF6B6B"
+        inactiveSortIconColor="#DDD"
+        style={{ backgroundColor: '#F8F9FA' }}
+      />
+      
+      {/* 大尺寸列头 */}
+      <TapasTableColumnHeader 
+        title="Large Header"
+        fieldName="large"
+        sortable={true}
+        minHeight={60}
+        sortIconSize={24}
+        padding={{ horizontal: 24, vertical: 12 }}
+        titleStyle={{ fontSize: 18 }}
+      />
+      
+      {/* 紧凑型列头 */}
+      <TapasTableColumnHeader 
+        title="Compact"
+        fieldName="compact"
+        sortable={true}
+        minHeight={32}
+        sortIconSize={14}
+        padding={{ horizontal: 8, vertical: 4 }}
+        titleStyle={{ fontSize: 12 }}
+      />
+    </View>
+  );
+};
+```
+
+### 响应式表格
+
+```tsx
+import React, { useState } from 'react';
+import { ScrollView, View, Dimensions } from 'react-native';
+import { TapasTableColumnHeader, SortDirection } from '@beppla/tapas-ui';
+
+const ResponsiveTable = () => {
+  const [sortState, setSortState] = useState<{
+    field: string;
+    direction: SortDirection;
+  }>({ field: '', direction: null });
+
+  const screenWidth = Dimensions.get('window').width;
+  const isNarrowScreen = screenWidth < 768;
+
+  const columns = [
+    { 
+      title: 'Name', 
+      field: 'name', 
+      width: isNarrowScreen ? 120 : 200,
+      align: 'left' as const
+    },
+    { 
+      title: 'Email', 
+      field: 'email', 
+      width: isNarrowScreen ? 150 : 250,
+      align: 'left' as const
+    },
+    { 
+      title: 'Role', 
+      field: 'role', 
+      width: isNarrowScreen ? 80 : 120,
+      align: 'center' as const
+    },
+    { 
+      title: 'Status', 
+      field: 'status', 
+      width: isNarrowScreen ? 80 : 100,
+      align: 'center' as const
+    },
+  ];
+
+  const handleSort = (fieldName: string, direction: SortDirection) => {
+    setSortState({ field: fieldName, direction });
+  };
+
+  return (
+    <ScrollView horizontal showsHorizontalScrollIndicator={false}>
+      <View style={{ flexDirection: 'row' }}>
+        {columns.map((column) => (
+          <View key={column.field} style={{ width: column.width }}>
+            <TapasTableColumnHeader
+              title={column.title}
+              fieldName={column.field}
+              sortable={true}
+              textAlign={column.align}
+              sortDirection={
+                sortState.field === column.field ? sortState.direction : null
+              }
+              onSort={handleSort}
+              minHeight={isNarrowScreen ? 36 : 44}
+              padding={{
+                horizontal: isNarrowScreen ? 8 : 16,
+                vertical: isNarrowScreen ? 6 : 8
+              }}
+              titleStyle={{
+                fontSize: isNarrowScreen ? 12 : 14
+              }}
+              sortIconSize={isNarrowScreen ? 16 : 18}
+            />
+          </View>
+        ))}
+      </View>
+    </ScrollView>
+  );
+};
+```
+
+### 事件处理
+
+```tsx
+import React, { useState } from 'react';
+import { Alert } from 'react-native';
+import { TapasTableColumnHeader, SortDirection } from '@beppla/tapas-ui';
+
+const EventHandlingExample = () => {
+  const [events, setEvents] = useState<string[]>([]);
+  
+  const addEvent = (event: string) => {
+    setEvents(prev => [event, ...prev.slice(0, 4)]);
+  };
+
+  const handleSort = (fieldName: string, direction: SortDirection, columnIndex?: number) => {
+    addEvent(`Sort: ${fieldName} ${direction || 'none'} (column ${columnIndex})`);
+  };
+
+  const handlePress = (fieldName: string, columnIndex?: number) => {
+    addEvent(`Press: ${fieldName} (column ${columnIndex})`);
+  };
+
+  const handleLongPress = (fieldName: string, columnIndex?: number) => {
+    Alert.alert(
+      'Column Menu',
+      `Options for ${fieldName}`,
+      [
+        { text: 'Hide Column', onPress: () => addEvent(`Hide: ${fieldName}`) },
+        { text: 'Filter', onPress: () => addEvent(`Filter: ${fieldName}`) },
+        { text: 'Cancel', style: 'cancel' },
+      ]
+    );
+  };
+
+  return (
+    <View>
+      <TapasTableColumnHeader 
+        title="Interactive Column"
+        fieldName="interactive"
+        columnIndex={0}
+        sortable={true}
+        onSort={handleSort}
+        onPress={handlePress}
+        onLongPress={handleLongPress}
+      />
+      
+      <View style={{ marginTop: 16 }}>
+        <Text style={{ fontWeight: 'bold' }}>Event Log:</Text>
+        {events.map((event, index) => (
+          <Text key={index} style={{ fontSize: 12, color: '#666' }}>
+            {event}
+          </Text>
+        ))}
+      </View>
+    </View>
+  );
+};
+```
+
+### 自定义排序图标
+
+```tsx
+import React from 'react';
+import { TapasTableColumnHeader } from '@beppla/tapas-ui';
+
+const CustomIconsExample = () => {
+  return (
+    <View style={{ gap: 16 }}>
+      {/* 使用不同的箭头图标 */}
+      <TapasTableColumnHeader 
+        title="Custom Arrows"
+        fieldName="arrows"
+        sortable={true}
+        sortDirection="ASC"
+        sortIcons={{
+          ascending: "keyboard_arrow_up",
+          descending: "keyboard_arrow_down"
+        }}
+      />
+      
+      {/* 使用展开/收缩图标 */}
+      <TapasTableColumnHeader 
+        title="Expand/Collapse"
+        fieldName="expand"
+        sortable={true}
+        sortDirection="DESC"
+        sortIcons={{
+          ascending: "expand_less",
+          descending: "expand_more"
+        }}
+      />
+      
+      {/* 隐藏排序指示器，仅通过回调处理 */}
+      <TapasTableColumnHeader 
+        title="Hidden Indicators"
+        fieldName="hidden"
+        sortable={true}
+        showSortIndicator={false}
+        onSort={(field, direction) => {
+          console.log(`Custom sort logic: ${field} ${direction}`);
+        }}
+      />
+    </View>
+  );
+};
+```
+
+### 条件渲染和动态属性
+
+```tsx
+import React, { useState } from 'react';
+import { Switch, Text } from 'react-native';
+import { TapasTableColumnHeader, SortDirection } from '@beppla/tapas-ui';
+
+const ConditionalExample = () => {
+  const [isAdmin, setIsAdmin] = useState(false);
+  const [sortDirection, setSortDirection] = useState<SortDirection>(null);
+  
+  const userRole = isAdmin ? 'admin' : 'user';
+  
+  return (
+    <View>
+      <View style={{ 
+        flexDirection: 'row', 
+        alignItems: 'center', 
+        marginBottom: 16 
+      }}>
+        <Text>Admin Mode: </Text>
+        <Switch value={isAdmin} onValueChange={setIsAdmin} />
+      </View>
+      
+      <TapasTableColumnHeader 
+        title={isAdmin ? "User Management" : "My Profile"}
+        fieldName="user_data"
+        sortable={isAdmin} // 只有管理员可以排序
+        disabled={!isAdmin && sortDirection !== null} // 非管理员时禁用已排序状态
+        sortDirection={isAdmin ? sortDirection : null}
+        textAlign={isAdmin ? "left" : "center"}
+        onSort={isAdmin ? (field, direction) => {
+          setSortDirection(direction);
+        } : undefined}
+        titleStyle={{
+          color: isAdmin ? '#007AFF' : '#666',
+          fontWeight: isAdmin ? 'bold' : 'normal'
+        }}
+        style={{
+          backgroundColor: isAdmin ? '#F0F8FF' : '#F8F9FA'
+        }}
+      />
+      
+      <Text style={{ marginTop: 8, fontSize: 12, color: '#666' }}>
+        Current role: {userRole}
+      </Text>
+    </View>
+  );
+};
+```
+
+## 排序逻辑
+
+组件实现了标准的三状态排序循环：
+
+```
+null (无排序) → ASC (升序) → DESC (降序) → null (无排序) → ...
+```
+
+### 排序状态管理
+
+```tsx
+const [sortState, setSortState] = useState<{
+  field: string;
+  direction: SortDirection;
+}>({ field: '', direction: null });
+
+const handleSort = (fieldName: string, direction: SortDirection) => {
+  setSortState({ field: fieldName, direction });
+  
+  // 应用排序逻辑
+  if (direction === null) {
+    // 重置为原始顺序
+    resetDataOrder();
+  } else if (direction === 'ASC') {
+    // 升序排序
+    sortDataAscending(fieldName);
+  } else if (direction === 'DESC') {
+    // 降序排序
+    sortDataDescending(fieldName);
+  }
+};
+```
+
+### 与后端API集成
+
+```tsx
+const handleSort = async (fieldName: string, direction: SortDirection) => {
+  setSortState({ field: fieldName, direction });
+  
+  try {
+    const params = {
+      sortBy: fieldName,
+      sortOrder: direction || 'default',
+      page: 1, // 排序时重置到第一页
+    };
+    
+    const response = await fetch('/api/data', {
+      method: 'POST',
+      body: JSON.stringify(params),
+      headers: { 'Content-Type': 'application/json' }
+    });
+    
+    const data = await response.json();
+    setTableData(data.items);
+  } catch (error) {
+    console.error('Sort failed:', error);
+  }
+};
+```
+
+## 样式主题
+
+组件会自动使用应用主题的以下属性：
+
+```tsx
+// 默认样式
+{
+  backgroundColor: theme?.colors?.grey5 || "#f8f9fa",
+  borderColor: theme?.colors?.grey3 || "#e0e0e0",
+  titleColor: theme?.colors?.colorTextSecondary || theme?.colors?.grey1 || "#333",
+  activeSortIconColor: theme?.colors?.primary || "#007AFF",
+  inactiveSortIconColor: theme?.colors?.grey2 || "#999",
+}
+```
+
+### 主题定制
+
+```tsx
+const customTheme = {
+  colors: {
+    grey5: '#FFFFFF',
+    grey3: '#E0E7FF',
+    grey1: '#1E40AF',
+    primary: '#3B82F6',
+    grey2: '#94A3B8',
+  }
+};
+
+<ThemeProvider theme={customTheme}>
+  <TapasTableColumnHeader 
+    title="Themed Header"
+    sortable={true}
+  />
+</ThemeProvider>
+```
+
+## 可访问性支持
+
+组件继承了 `Pressable` 和 `View` 的所有可访问性属性：
+
+```tsx
+<TapasTableColumnHeader 
+  title="Accessible Header"
+  fieldName="accessible"
+  sortable={true}
+  sortDirection="ASC"
+  accessible={true}
+  accessibilityRole="button"
+  accessibilityLabel="Sort by product name, currently ascending"
+  accessibilityHint="Double tap to change sort order"
+  accessibilityState={{ 
+    selected: sortDirection === 'ASC',
+    disabled: false 
+  }}
+/>
+```
+
+### 动态可访问性标签
+
+```tsx
+const getAccessibilityLabel = (title: string, sortDirection: SortDirection) => {
+  const baseLabel = `Sort by ${title}`;
+  
+  switch (sortDirection) {
+    case 'ASC':
+      return `${baseLabel}, currently sorted ascending`;
+    case 'DESC':
+      return `${baseLabel}, currently sorted descending`;
+    default:
+      return `${baseLabel}, not sorted`;
+  }
+};
+
+<TapasTableColumnHeader 
+  title="Smart Accessible"
+  fieldName="smart"
+  sortable={true}
+  sortDirection={sortDirection}
+  accessibilityLabel={getAccessibilityLabel("Smart Accessible", sortDirection)}
+/>
+```
+
+## 性能优化
+
+### 使用 React.memo 优化重渲染
+
+```tsx
+import React, { memo } from 'react';
+
+const OptimizedTableHeader = memo(({ columns, sortState, onSort }) => {
+  return (
+    <View style={{ flexDirection: 'row' }}>
+      {columns.map((column) => (
+        <TapasTableColumnHeader
+          key={column.field}
+          title={column.title}
+          fieldName={column.field}
+          sortable={column.sortable}
+          sortDirection={
+            sortState.field === column.field ? sortState.direction : null
+          }
+          onSort={onSort}
+        />
+      ))}
+    </View>
+  );
+});
+```
+
+### 缓存排序函数
+
+```tsx
+const handleSort = useCallback((fieldName: string, direction: SortDirection) => {
+  setSortState({ field: fieldName, direction });
+  // 排序逻辑...
+}, [/* 依赖项 */]);
+```
+
+## 最佳实践
+
+1. **排序状态管理**
+   - 使用单一的排序状态对象管理整个表格的排序
+   - 在组件外部管理数据排序逻辑
+
+2. **性能考虑**
+   - 对于大型表格，考虑使用虚拟化
+   - 使用 `React.memo` 避免不必要的重渲染
+
+3. **用户体验**
+   - 提供清晰的排序状态视觉反馈
+   - 在数据加载时显示适当的加载状态
+
+4. **可访问性**
+   - 为排序状态提供清晰的辅助技术支持
+   - 使用语义化的可访问性标签
+
+5. **响应式设计**
+   - 在小屏幕上适当调整列头大小和间距
+   - 考虑横向滚动的表格布局
+
+## 向后兼容
+
+为了确保向后兼容，组件同时导出了以下别名：
+
+```tsx
+// 新的推荐用法
+import { TapasTableColumnHeader } from '@beppla/tapas-ui';
+
+// 向后兼容的用法
+import { TableColumnHeader } from '@beppla/tapas-ui';
+```
+
+## 使用场景
+
+- 数据表格列头
+- 网格视图列头
+- 列表排序控制
+- 报表表格列头
+- 管理后台数据表格
+- 电商产品列表
+- 用户管理界面
+
+## 注意事项
+
+1. `fieldName` 对于排序功能是必需的
+2. 排序方向会在点击时自动循环切换
+3. 组件会根据 `sortable` 属性自动选择渲染为 `Pressable` 或 `View`
+4. 长文本会自动截断并显示省略号（最多2行）
+5. 组件支持React Native和React Native Web环境
+6. 排序图标使用绝对定位以确保正确的视觉效果