@beppla/tapas-ui 1.5.10 → 1.5.12

package/package/module/DataCell/README.md

@@ -0,0 +1,1042 @@
+# TapasDataCell
+
+一个功能强大的数据单元格组件，支持多种数据类型格式化、状态显示、交互操作和自定义样式。适用于表格、网格、列表和数据展示场景。
+
+## 功能特性
+
+- ✅ 多种数据类型支持（文本、数字、货币、日期、状态、布尔值）
+- ✅ 灵活的文本对齐和样式配置
+- ✅ 状态指示器和自定义颜色配置
+- ✅ 交互操作支持（点击、长按、操作按钮）
+- ✅ 自定义格式化函数
+- ✅ 完整的主题集成
+- ✅ TypeScript 类型支持
+- ✅ 响应式设计和可访问性
+- ✅ 向后兼容的导出别名
+
+## 安装使用
+
+```tsx
+import { TapasDataCell } from '@beppla/tapas-ui';
+
+// 基础文本显示
+<TapasDataCell value="Hello World" />
+
+// 货币格式化
+<TapasDataCell 
+  value={99.99}
+  dataType="currency"
+  currencySymbol="$"
+  alignment="right"
+/>
+
+// 状态显示
+<TapasDataCell 
+  value="active"
+  dataType="status"
+  statusConfig={{
+    active: { color: '#00C851', backgroundColor: '#E8F5E8' }
+  }}
+/>
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `any` | - | 显示的值 |
+| `dataType` | `DataType` | `"text"` | 数据类型 |
+| `alignment` | `CellAlignment` | `"left"` | 文本对齐方式 |
+| `columnIndex` | `number` | - | 列索引 |
+| `rowIndex` | `number` | - | 行索引 |
+| `fieldName` | `string` | - | 字段名称 |
+| `clickable` | `boolean` | `false` | 是否可点击 |
+| `ellipsizeMode` | `"head" \| "middle" \| "tail" \| "clip"` | `"tail"` | 文本截断模式 |
+| `numberOfLines` | `number` | `1` | 最大行数 |
+| `textStyle` | `StyleProp<TextStyle>` | - | 文本样式 |
+| `padding` | `{horizontal?: number, vertical?: number}` | `{horizontal: 16, vertical: 8}` | 容器内边距 |
+| `statusConfig` | `Record<string, StatusConfig>` | `{}` | 状态配置映射 |
+| `actions` | `ActionItem[]` | `[]` | 操作项列表 |
+| `showActions` | `boolean` | `false` | 是否显示操作按钮 |
+| `actionIcon` | `string` | `"more_vert"` | 操作按钮图标 |
+| `formatter` | `(value: any, dataType: DataType) => string` | - | 自定义格式化函数 |
+| `currencySymbol` | `string` | `"$"` | 货币符号 |
+| `currencyPrecision` | `number` | `2` | 货币精度 |
+| `dateFormat` | `string` | `"YYYY-MM-DD"` | 日期格式 |
+| `booleanTrueText` | `string` | `"Yes"` | 布尔值真值文本 |
+| `booleanFalseText` | `string` | `"No"` | 布尔值假值文本 |
+| `emptyText` | `string` | `"-"` | 空值显示文本 |
+| `onCellPress` | `(value: any, rowIndex?: number, columnIndex?: number, fieldName?: string) => void` | - | 单元格点击回调 |
+| `onActionPress` | `(action: ActionItem, value: any, rowIndex?: number, columnIndex?: number) => void` | - | 操作项点击回调 |
+| `onLongPress` | `(value: any, rowIndex?: number, columnIndex?: number, fieldName?: string) => void` | - | 长按回调 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `minHeight` | `number` | `40` | 最小高度 |
+| `isBlank` | `boolean` | `false` | 是否为空白单元格 |
+
+## 类型定义
+
+```tsx
+export type DataType = 
+  | "text" 
+  | "number" 
+  | "currency" 
+  | "date" 
+  | "status" 
+  | "boolean" 
+  | "custom";
+
+export type CellAlignment = "left" | "center" | "right";
+
+export interface StatusConfig {
+  color: string;
+  backgroundColor?: string;
+  borderColor?: string;
+}
+
+export interface ActionItem {
+  id: string;
+  label: string;
+  icon?: string;
+  disabled?: boolean;
+}
+```
+
+## 使用示例
+
+### 基础数据显示
+
+```tsx
+import React from 'react';
+import { TapasDataCell } from '@beppla/tapas-ui';
+
+const BasicExample = () => {
+  return (
+    <View style={{ padding: 16 }}>
+      {/* 文本数据 */}
+      <TapasDataCell 
+        value="Hello World"
+        dataType="text"
+      />
+      
+      {/* 数字数据 */}
+      <TapasDataCell 
+        value={1234567.89}
+        dataType="number"
+        alignment="right"
+      />
+      
+      {/* 布尔值数据 */}
+      <TapasDataCell 
+        value={true}
+        dataType="boolean"
+        booleanTrueText="Active"
+        booleanFalseText="Inactive"
+        alignment="center"
+      />
+    </View>
+  );
+};
+```
+
+### 货币和日期格式化
+
+```tsx
+import React from 'react';
+import { TapasDataCell } from '@beppla/tapas-ui';
+
+const FormattingExample = () => {
+  return (
+    <View style={{ padding: 16 }}>
+      {/* 美元货币 */}
+      <TapasDataCell 
+        value={99.99}
+        dataType="currency"
+        currencySymbol="$"
+        currencyPrecision={2}
+        alignment="right"
+      />
+      
+      {/* 欧元货币 */}
+      <TapasDataCell 
+        value={299.95}
+        dataType="currency"
+        currencySymbol="€"
+        currencyPrecision={2}
+        alignment="right"
+      />
+      
+      {/* 日期格式 */}
+      <TapasDataCell 
+        value="2023-12-25T10:30:00Z"
+        dataType="date"
+        dateFormat="YYYY-MM-DD"
+        alignment="center"
+      />
+      
+      {/* 日期格式 (美式) */}
+      <TapasDataCell 
+        value="2023-12-25T10:30:00Z"
+        dataType="date"
+        dateFormat="MM/DD/YYYY"
+        alignment="center"
+      />
+    </View>
+  );
+};
+```
+
+### 状态指示器
+
+```tsx
+import React from 'react';
+import { TapasDataCell, StatusConfig } from '@beppla/tapas-ui';
+
+const StatusExample = () => {
+  const statusConfig: Record<string, StatusConfig> = {
+    'active': {
+      color: '#00C851',
+      backgroundColor: '#E8F5E8',
+      borderColor: '#00C851'
+    },
+    'inactive': {
+      color: '#FF4444',
+      backgroundColor: '#FFE8E8',
+      borderColor: '#FF4444'
+    },
+    'pending': {
+      color: '#FF9500',
+      backgroundColor: '#FFF4E8',
+      borderColor: '#FF9500'
+    },
+    'completed': {
+      color: '#007AFF',
+      backgroundColor: '#E8F4FF',
+      borderColor: '#007AFF'
+    }
+  };
+
+  return (
+    <View style={{ padding: 16, gap: 12 }}>
+      <TapasDataCell 
+        value="active"
+        dataType="status"
+        statusConfig={statusConfig}
+        alignment="center"
+      />
+      
+      <TapasDataCell 
+        value="pending"
+        dataType="status"
+        statusConfig={statusConfig}
+        alignment="center"
+      />
+      
+      <TapasDataCell 
+        value="completed"
+        dataType="status"
+        statusConfig={statusConfig}
+        alignment="center"
+      />
+    </View>
+  );
+};
+```
+
+### 交互功能
+
+```tsx
+import React from 'react';
+import { Alert } from 'react-native';
+import { TapasDataCell, ActionItem } from '@beppla/tapas-ui';
+
+const InteractiveExample = () => {
+  const actions: ActionItem[] = [
+    { id: 'edit', label: 'Edit', icon: 'edit' },
+    { id: 'copy', label: 'Copy', icon: 'content_copy' },
+    { id: 'delete', label: 'Delete', icon: 'delete' },
+  ];
+
+  const handleCellPress = (value: any, rowIndex?: number, columnIndex?: number, fieldName?: string) => {
+    Alert.alert('Cell Pressed', `Value: ${value}\nRow: ${rowIndex}\nColumn: ${columnIndex}\nField: ${fieldName}`);
+  };
+
+  const handleActionPress = (action: ActionItem, value: any) => {
+    Alert.alert('Action Pressed', `Action: ${action.label}\nValue: ${value}`);
+  };
+
+  const handleLongPress = (value: any) => {
+    Alert.alert('Long Pressed', `Value: ${value}`);
+  };
+
+  return (
+    <View style={{ padding: 16, gap: 12 }}>
+      {/* 可点击单元格 */}
+      <TapasDataCell 
+        value="Click me!"
+        clickable={true}
+        onCellPress={handleCellPress}
+        rowIndex={0}
+        columnIndex={0}
+        fieldName="clickable"
+      />
+      
+      {/* 长按单元格 */}
+      <TapasDataCell 
+        value="Long press me!"
+        onLongPress={handleLongPress}
+      />
+      
+      {/* 带操作按钮的单元格 */}
+      <TapasDataCell 
+        value="Has actions"
+        showActions={true}
+        actions={actions}
+        onActionPress={handleActionPress}
+      />
+    </View>
+  );
+};
+```
+
+### 数据表格
+
+```tsx
+import React, { useState } from 'react';
+import { View, Text, ScrollView } from 'react-native';
+import { TapasDataCell, DataType, StatusConfig, ActionItem } from '@beppla/tapas-ui';
+
+const DataTableExample = () => {
+  const [selectedCell, setSelectedCell] = useState<string | null>(null);
+
+  const columns = [
+    { title: 'ID', field: 'id', dataType: 'text' as DataType, width: 80 },
+    { title: 'Name', field: 'name', dataType: 'text' as DataType, width: 150 },
+    { title: 'Price', field: 'price', dataType: 'currency' as DataType, width: 100 },
+    { title: 'Date', field: 'date', dataType: 'date' as DataType, width: 120 },
+    { title: 'Status', field: 'status', dataType: 'status' as DataType, width: 100 },
+    { title: 'Active', field: 'active', dataType: 'boolean' as DataType, width: 80 },
+    { title: 'Actions', field: 'actions', dataType: 'custom' as DataType, width: 80 },
+  ];
+
+  const data = [
+    {
+      id: '001',
+      name: 'Product A',
+      price: 99.99,
+      date: '2023-12-01',
+      status: 'active',
+      active: true,
+    },
+    {
+      id: '002',
+      name: 'Product B',
+      price: 149.50,
+      date: '2023-12-02',
+      status: 'pending',
+      active: false,
+    },
+    {
+      id: '003',
+      name: 'Product C',
+      price: 75.25,
+      date: '2023-12-03',
+      status: 'inactive',
+      active: true,
+    },
+  ];
+
+  const statusConfig: Record<string, StatusConfig> = {
+    'active': { color: '#00C851', backgroundColor: '#E8F5E8', borderColor: '#00C851' },
+    'inactive': { color: '#FF4444', backgroundColor: '#FFE8E8', borderColor: '#FF4444' },
+    'pending': { color: '#FF9500', backgroundColor: '#FFF4E8', borderColor: '#FF9500' },
+  };
+
+  const actions: ActionItem[] = [
+    { id: 'edit', label: 'Edit', icon: 'edit' },
+    { id: 'delete', label: 'Delete', icon: 'delete' },
+  ];
+
+  const handleCellPress = (value: any, rowIndex?: number, columnIndex?: number, fieldName?: string) => {
+    setSelectedCell(`Row ${rowIndex}, Field ${fieldName}: ${value}`);
+  };
+
+  const handleActionPress = (action: ActionItem, value: any, rowIndex?: number) => {
+    alert(`${action.label} on row ${rowIndex}`);
+  };
+
+  return (
+    <View style={{ padding: 16 }}>
+      <Text style={{ fontSize: 18, fontWeight: 'bold', marginBottom: 16 }}>
+        Product Data Table
+      </Text>
+      
+      <ScrollView horizontal showsHorizontalScrollIndicator={false}>
+        <View style={{ backgroundColor: '#fff', borderRadius: 8, overflow: 'hidden' }}>
+          {/* Header */}
+          <View style={{ flexDirection: 'row', backgroundColor: '#f5f5f5' }}>
+            {columns.map((column) => (
+              <View key={column.field} style={{ width: column.width, padding: 12, borderRightWidth: 1, borderRightColor: '#e0e0e0' }}>
+                <Text style={{ fontWeight: 'bold', fontSize: 14 }}>{column.title}</Text>
+              </View>
+            ))}
+          </View>
+          
+          {/* Data Rows */}
+          {data.map((row, rowIndex) => (
+            <View key={rowIndex} style={{ flexDirection: 'row', borderBottomWidth: 1, borderBottomColor: '#f0f0f0' }}>
+              {columns.map((column, columnIndex) => (
+                <View key={column.field} style={{ width: column.width, borderRightWidth: 1, borderRightColor: '#f0f0f0' }}>
+                  <TapasDataCell
+                    value={column.field === 'actions' ? 'Actions' : row[column.field as keyof typeof row]}
+                    dataType={column.dataType}
+                    alignment={
+                      column.dataType === 'currency' || column.dataType === 'number' ? 'right' :
+                      column.dataType === 'boolean' || column.dataType === 'status' ? 'center' : 'left'
+                    }
+                    rowIndex={rowIndex}
+                    columnIndex={columnIndex}
+                    fieldName={column.field}
+                    clickable={column.field !== 'actions'}
+                    showActions={column.field === 'actions'}
+                    actions={column.field === 'actions' ? actions : []}
+                    statusConfig={statusConfig}
+                    currencySymbol="$"
+                    booleanTrueText="✓"
+                    booleanFalseText="✗"
+                    onCellPress={handleCellPress}
+                    onActionPress={handleActionPress}
+                    style={{ borderBottomWidth: 0, margin: 0 }}
+                  />
+                </View>
+              ))}
+            </View>
+          ))}
+        </View>
+      </ScrollView>
+      
+      {selectedCell && (
+        <View style={{ backgroundColor: '#f0f8ff', padding: 12, borderRadius: 8, marginTop: 16 }}>
+          <Text style={{ color: '#333' }}>Selected: {selectedCell}</Text>
+        </View>
+      )}
+    </View>
+  );
+};
+```
+
+### 自定义格式化
+
+```tsx
+import React from 'react';
+import { TapasDataCell } from '@beppla/tapas-ui';
+
+const CustomFormattingExample = () => {
+  // 自定义格式化函数
+  const emailFormatter = (value: string) => {
+    if (!value || !value.includes('@')) return value;
+    const [user, domain] = value.split('@');
+    return `${user.substring(0, 3)}***@${domain}`;
+  };
+
+  const scoreFormatter = (value: number) => {
+    if (value >= 90) return `🏆 ${value}`;
+    if (value >= 80) return `🥉 ${value}`;
+    if (value >= 70) return `📊 ${value}`;
+    return `📉 ${value}`;
+  };
+
+  const percentageFormatter = (value: number) => {
+    return `${(value * 100).toFixed(1)}%`;
+  };
+
+  return (
+    <View style={{ padding: 16, gap: 12 }}>
+      {/* 邮箱脱敏 */}
+      <TapasDataCell 
+        value="user@example.com"
+        formatter={emailFormatter}
+      />
+      
+      {/* 分数等级 */}
+      <TapasDataCell 
+        value={95}
+        formatter={scoreFormatter}
+        alignment="center"
+      />
+      
+      {/* 百分比显示 */}
+      <TapasDataCell 
+        value={0.856}
+        formatter={percentageFormatter}
+        alignment="right"
+      />
+      
+      {/* 自定义状态 */}
+      <TapasDataCell 
+        value="premium_user"
+        formatter={(value) => value.replace('_', ' ').toUpperCase()}
+        alignment="center"
+      />
+    </View>
+  );
+};
+```
+
+### 响应式表格
+
+```tsx
+import React, { useState, useEffect } from 'react';
+import { View, Dimensions, ScrollView } from 'react-native';
+import { TapasDataCell, DataType } from '@beppla/tapas-ui';
+
+const ResponsiveTableExample = () => {
+  const [screenWidth, setScreenWidth] = useState(Dimensions.get('window').width);
+  const [isNarrowScreen, setIsNarrowScreen] = useState(false);
+
+  useEffect(() => {
+    const updateLayout = () => {
+      const { width } = Dimensions.get('window');
+      setScreenWidth(width);
+      setIsNarrowScreen(width < 768);
+    };
+
+    updateLayout();
+    const subscription = Dimensions.addEventListener('change', updateLayout);
+    
+    return () => subscription?.remove();
+  }, []);
+
+  const columns = [
+    { 
+      title: 'Name', 
+      field: 'name', 
+      dataType: 'text' as DataType,
+      width: isNarrowScreen ? 120 : 200,
+      priority: 1
+    },
+    { 
+      title: 'Email', 
+      field: 'email', 
+      dataType: 'text' as DataType,
+      width: isNarrowScreen ? 0 : 250, // Hide on narrow screens
+      priority: 3
+    },
+    { 
+      title: 'Score', 
+      field: 'score', 
+      dataType: 'number' as DataType,
+      width: isNarrowScreen ? 80 : 100,
+      priority: 2
+    },
+    { 
+      title: 'Status', 
+      field: 'status', 
+      dataType: 'status' as DataType,
+      width: isNarrowScreen ? 80 : 120,
+      priority: 1
+    },
+  ];
+
+  const data = [
+    { name: 'Alice Johnson', email: 'alice@example.com', score: 95, status: 'active' },
+    { name: 'Bob Smith', email: 'bob@example.com', score: 87, status: 'pending' },
+    { name: 'Carol Brown', email: 'carol@example.com', score: 92, status: 'active' },
+  ];
+
+  const visibleColumns = columns.filter(col => col.width > 0);
+
+  return (
+    <View style={{ padding: 16 }}>
+      <Text style={{ fontSize: 16, marginBottom: 12 }}>
+        Screen Width: {screenWidth}px ({isNarrowScreen ? 'Narrow' : 'Wide'})
+      </Text>
+      
+      <ScrollView horizontal showsHorizontalScrollIndicator={false}>
+        <View>
+          {/* Header */}
+          <View style={{ flexDirection: 'row' }}>
+            {visibleColumns.map((column) => (
+              <View key={column.field} style={{ width: column.width, padding: 8, backgroundColor: '#f5f5f5' }}>
+                <Text style={{ fontWeight: 'bold', fontSize: isNarrowScreen ? 12 : 14 }}>
+                  {column.title}
+                </Text>
+              </View>
+            ))}
+          </View>
+          
+          {/* Data */}
+          {data.map((row, rowIndex) => (
+            <View key={rowIndex} style={{ flexDirection: 'row' }}>
+              {visibleColumns.map((column) => (
+                <View key={column.field} style={{ width: column.width }}>
+                  <TapasDataCell
+                    value={row[column.field as keyof typeof row]}
+                    dataType={column.dataType}
+                    alignment={column.dataType === 'number' ? 'right' : 'left'}
+                    minHeight={isNarrowScreen ? 32 : 40}
+                    padding={{
+                      horizontal: isNarrowScreen ? 8 : 12,
+                      vertical: isNarrowScreen ? 4 : 8
+                    }}
+                    textStyle={{
+                      fontSize: isNarrowScreen ? 12 : 14
+                    }}
+                    style={{ borderBottomWidth: 0 }}
+                  />
+                </View>
+              ))}
+            </View>
+          ))}
+        </View>
+      </ScrollView>
+    </View>
+  );
+};
+```
+
+### 空值和错误处理
+
+```tsx
+import React from 'react';
+import { TapasDataCell } from '@beppla/tapas-ui';
+
+const ErrorHandlingExample = () => {
+  return (
+    <View style={{ padding: 16, gap: 12 }}>
+      {/* null 值 */}
+      <TapasDataCell 
+        value={null}
+        emptyText="No Data"
+      />
+      
+      {/* undefined 值 */}
+      <TapasDataCell 
+        value={undefined}
+        emptyText="N/A"
+      />
+      
+      {/* 无效日期 */}
+      <TapasDataCell 
+        value="invalid-date"
+        dataType="date"
+        emptyText="Invalid Date"
+      />
+      
+      {/* 无效货币 */}
+      <TapasDataCell 
+        value="not-a-number"
+        dataType="currency"
+        emptyText="Invalid Amount"
+      />
+      
+      {/* 空字符串 */}
+      <TapasDataCell 
+        value=""
+        emptyText="Empty"
+      />
+      
+      {/* 0 值（数字） */}
+      <TapasDataCell 
+        value={0}
+        dataType="number"
+        alignment="right"
+      />
+      
+      {/* false 值（布尔） */}
+      <TapasDataCell 
+        value={false}
+        dataType="boolean"
+        booleanFalseText="Disabled"
+      />
+    </View>
+  );
+};
+```
+
+### 样式定制
+
+```tsx
+import React from 'react';
+import { TapasDataCell } from '@beppla/tapas-ui';
+
+const StylingExample = () => {
+  return (
+    <View style={{ padding: 16, gap: 12 }}>
+      {/* 自定义文本样式 */}
+      <TapasDataCell 
+        value="Custom Text Style"
+        textStyle={{
+          fontSize: 18,
+          fontWeight: 'bold',
+          color: '#FF6B6B',
+          fontStyle: 'italic'
+        }}
+      />
+      
+      {/* 自定义容器样式 */}
+      <TapasDataCell 
+        value="Custom Container"
+        style={{
+          backgroundColor: '#E8F4FF',
+          borderRadius: 8,
+          borderWidth: 2,
+          borderColor: '#007AFF'
+        }}
+      />
+      
+      {/* 自定义内边距 */}
+      <TapasDataCell 
+        value="Custom Padding"
+        padding={{ horizontal: 24, vertical: 16 }}
+        style={{ backgroundColor: '#F0F8E8' }}
+      />
+      
+      {/* 自定义高度 */}
+      <TapasDataCell 
+        value="Tall Cell"
+        minHeight={60}
+        style={{ backgroundColor: '#FFF4E8' }}
+      />
+      
+      {/* 多行文本 */}
+      <TapasDataCell 
+        value="This is a very long text that will span multiple lines when numberOfLines is set to more than 1"
+        numberOfLines={3}
+        ellipsizeMode="tail"
+        padding={{ horizontal: 16, vertical: 12 }}
+      />
+    </View>
+  );
+};
+```
+
+## 数据格式化
+
+### 内置格式化器
+
+组件提供了以下内置数据类型的格式化：
+
+#### 1. 文本 (text)
+```tsx
+<TapasDataCell value="Hello World" dataType="text" />
+// 输出: Hello World
+```
+
+#### 2. 数字 (number)
+```tsx
+<TapasDataCell value={1234567.89} dataType="number" />
+// 输出: 1,234,567.89
+```
+
+#### 3. 货币 (currency)
+```tsx
+<TapasDataCell 
+  value={99.99} 
+  dataType="currency" 
+  currencySymbol="$" 
+  currencyPrecision={2} 
+/>
+// 输出: $99.99
+```
+
+#### 4. 日期 (date)
+```tsx
+<TapasDataCell 
+  value="2023-12-25T10:30:00Z" 
+  dataType="date" 
+  dateFormat="YYYY-MM-DD" 
+/>
+// 输出: 2023-12-25
+
+<TapasDataCell 
+  value="2023-12-25T10:30:00Z" 
+  dataType="date" 
+  dateFormat="MM/DD/YYYY" 
+/>
+// 输出: 12/25/2023
+```
+
+#### 5. 布尔值 (boolean)
+```tsx
+<TapasDataCell 
+  value={true} 
+  dataType="boolean" 
+  booleanTrueText="Active" 
+  booleanFalseText="Inactive" 
+/>
+// 输出: Active
+```
+
+#### 6. 状态 (status)
+```tsx
+const statusConfig = {
+  'active': { color: '#00C851', backgroundColor: '#E8F5E8' }
+};
+
+<TapasDataCell 
+  value="active" 
+  dataType="status" 
+  statusConfig={statusConfig} 
+/>
+// 输出: 带样式的 "active"
+```
+
+### 自定义格式化器
+
+```tsx
+const customFormatter = (value: any, dataType: DataType) => {
+  switch (dataType) {
+    case 'custom':
+      return `🎯 ${String(value).toUpperCase()}`;
+    default:
+      return String(value);
+  }
+};
+
+<TapasDataCell 
+  value="custom_data" 
+  dataType="custom" 
+  formatter={customFormatter} 
+/>
+// 输出: 🎯 CUSTOM_DATA
+```
+
+## 状态配置
+
+状态配置允许为不同的状态值设置不同的视觉样式：
+
+```tsx
+const statusConfig: Record<string, StatusConfig> = {
+  'active': {
+    color: '#00C851',           // 文本颜色
+    backgroundColor: '#E8F5E8', // 背景颜色
+    borderColor: '#00C851'      // 边框颜色
+  },
+  'inactive': {
+    color: '#FF4444',
+    backgroundColor: '#FFE8E8',
+    borderColor: '#FF4444'
+  },
+  'pending': {
+    color: '#FF9500',
+    backgroundColor: '#FFF4E8',
+    borderColor: '#FF9500'
+  }
+};
+```
+
+## 交互操作
+
+### 单元格点击
+
+```tsx
+const handleCellPress = (value: any, rowIndex?: number, columnIndex?: number, fieldName?: string) => {
+  console.log(`Clicked cell: ${value} at row ${rowIndex}, column ${columnIndex}, field ${fieldName}`);
+};
+
+<TapasDataCell 
+  value="Clickable Cell"
+  clickable={true}
+  onCellPress={handleCellPress}
+  rowIndex={0}
+  columnIndex={1}
+  fieldName="name"
+/>
+```
+
+### 长按操作
+
+```tsx
+const handleLongPress = (value: any, rowIndex?: number, columnIndex?: number, fieldName?: string) => {
+  // 显示上下文菜单或其他操作
+  showContextMenu(value, rowIndex, columnIndex);
+};
+
+<TapasDataCell 
+  value="Long Press Me"
+  onLongPress={handleLongPress}
+/>
+```
+
+### 操作按钮
+
+```tsx
+const actions: ActionItem[] = [
+  { id: 'edit', label: 'Edit', icon: 'edit' },
+  { id: 'copy', label: 'Copy', icon: 'content_copy' },
+  { id: 'delete', label: 'Delete', icon: 'delete', disabled: false }
+];
+
+const handleActionPress = (action: ActionItem, value: any, rowIndex?: number, columnIndex?: number) => {
+  switch (action.id) {
+    case 'edit':
+      editItem(value, rowIndex);
+      break;
+    case 'copy':
+      copyToClipboard(value);
+      break;
+    case 'delete':
+      deleteItem(value, rowIndex);
+      break;
+  }
+};
+
+<TapasDataCell 
+  value="Item with actions"
+  showActions={true}
+  actions={actions}
+  onActionPress={handleActionPress}
+/>
+```
+
+## 主题集成
+
+组件会自动使用应用主题的以下属性：
+
+```tsx
+// 默认样式
+{
+  backgroundColor: theme?.colors?.grey5 || "#f8f9fa",
+  borderColor: theme?.colors?.grey4 || "#e0e0e0",
+  textColor: theme?.colors?.colorTextPrimary || theme?.colors?.grey1 || "#333",
+  actionIconColor: theme?.colors?.grey2 || "#999",
+}
+```
+
+### 主题定制
+
+```tsx
+const customTheme = {
+  colors: {
+    grey5: '#FFFFFF',
+    grey4: '#E0E7FF',
+    grey1: '#1E40AF',
+    grey2: '#94A3B8',
+    colorTextPrimary: '#1F2937',
+  }
+};
+
+<ThemeProvider theme={customTheme}>
+  <TapasDataCell 
+    value="Themed Cell"
+    dataType="text"
+  />
+</ThemeProvider>
+```
+
+## 可访问性支持
+
+组件继承了 `Pressable` 和 `View` 的所有可访问性属性：
+
+```tsx
+<TapasDataCell 
+  value="Accessible Cell"
+  clickable={true}
+  accessible={true}
+  accessibilityRole="button"
+  accessibilityLabel="Product name cell"
+  accessibilityHint="Double tap to view details"
+  accessibilityState={{ 
+    selected: isSelected,
+    disabled: isDisabled 
+  }}
+/>
+```
+
+## 性能优化
+
+### 使用 React.memo 优化重渲染
+
+```tsx
+import React, { memo } from 'react';
+
+const OptimizedDataCell = memo(TapasDataCell);
+
+// 在大型表格中使用
+const DataTable = memo(({ data, columns }) => {
+  return (
+    <View>
+      {data.map((row, rowIndex) => (
+        <View key={rowIndex} style={{ flexDirection: 'row' }}>
+          {columns.map((column, columnIndex) => (
+            <OptimizedDataCell
+              key={`${rowIndex}-${columnIndex}`}
+              value={row[column.field]}
+              dataType={column.dataType}
+              // ... other props
+            />
+          ))}
+        </View>
+      ))}
+    </View>
+  );
+});
+```
+
+### 缓存格式化函数
+
+```tsx
+const formatters = useMemo(() => ({
+  email: (value: string) => `${value.substring(0, 3)}***@${value.split('@')[1]}`,
+  phone: (value: string) => value.replace(/(\d{3})(\d{3})(\d{4})/, '($1) $2-$3'),
+  id: (value: string) => `ID-${value.padStart(6, '0')}`
+}), []);
+
+<TapasDataCell 
+  value="user@example.com"
+  formatter={formatters.email}
+/>
+```
+
+## 最佳实践
+
+1. **数据类型选择**
+   - 为不同类型的数据选择合适的 `dataType`
+   - 使用 `custom` 类型配合自定义格式化器处理特殊数据
+
+2. **性能考虑**
+   - 在大型表格中使用 `React.memo` 包装组件
+   - 缓存格式化函数和状态配置对象
+
+3. **用户体验**
+   - 为交互元素提供清晰的视觉反馈
+   - 使用合适的对齐方式（数字右对齐，文本左对齐）
+
+4. **可访问性**
+   - 为交互元素提供适当的可访问性标签
+   - 确保状态指示器有足够的颜色对比度
+
+5. **响应式设计**
+   - 在小屏幕上调整内边距和字体大小
+   - 考虑隐藏非重要列以适应窄屏
+
+## 向后兼容
+
+为了确保向后兼容，组件同时导出了以下别名：
+
+```tsx
+// 新的推荐用法
+import { TapasDataCell } from '@beppla/tapas-ui';
+
+// 向后兼容的用法
+import { DataCell } from '@beppla/tapas-ui';
+```
+
+## 使用场景
+
+- 数据表格单元格
+- 网格视图数据显示
+- 列表项数据格式化
+- 卡片内容显示
+- 仪表板数据展示
+- 报表数据格式化
+- 表单只读字段显示
+
+## 注意事项
+
+1. 组件会根据 `clickable` 属性或事件回调自动选择渲染为 `Pressable` 或 `View`
+2. 状态配置中的颜色会覆盖主题中的默认颜色
+3. 自定义格式化函数的优先级高于内置格式化
+4. 空值（null、undefined）会显示 `emptyText`
+5. 无效的日期和货币数据会回退到 `emptyText`
+6. 组件支持React Native和React Native Web环境