npm - @beppla/tapas-ui - Versions diffs - 1.5.12 → 1.5.13 - Mend

@beppla/tapas-ui 1.5.12 → 1.5.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1231) hide show

package/package/module/TableColumnHeader/README.md DELETED Viewed

@@ -1,682 +0,0 @@
-# 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. 排序图标使用绝对定位以确保正确的视觉效果