@beppla/tapas-ui 1.4.32 → 1.4.34

package/package/module/TabTitle/README.md

@@ -0,0 +1,399 @@
+# TapasTabTitle
+
+一个专用于Tab标题的组件，支持文本显示和可选的通知指示器，适用于标签导航、页面标题和需要状态提示的场景。
+
+## 功能特性
+
+- ✅ 清晰的文本显示，支持自动截断
+- ✅ 可选的通知指示器（红点提示）
+- ✅ 可自定义指示器颜色、大小和位置
+- ✅ 灵活的文本样式配置
+- ✅ 完整的可访问性支持
+- ✅ 向后兼容的导出别名
+- ✅ 主题集成，自动适配应用主题
+
+## 安装使用
+
+```tsx
+import { TapasTabTitle } from '@beppla/tapas-ui';
+
+// 基础用法
+<TapasTabTitle text="Home" />
+
+// 带通知指示器
+<TapasTabTitle 
+  text="Messages" 
+  showIndicator={true}
+  indicatorColor="#FF4444"
+/>
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `text` | `string` | - | 显示的文本内容 |
+| `showIndicator` | `boolean` | `false` | 是否显示通知指示器 |
+| `indicatorColor` | `string` | `"#FF4444"` | 指示器颜色 |
+| `indicatorSize` | `number` | `5` | 指示器大小（像素） |
+| `textStyle` | `StyleProp<TextStyle>` | - | 自定义文本样式 |
+| `textProps` | `Partial<TextProps>` | - | 传递给Text组件的属性 |
+| `indicatorOffset` | `{top?: number, right?: number}` | `{top: 0, right: -8}` | 指示器相对文本的偏移位置 |
+| `style` | `StyleProp<ViewStyle>` | - | 容器样式 |
+
+## 使用示例
+
+### 基础文本显示
+
+```tsx
+import React from 'react';
+import { TapasTabTitle } from '@beppla/tapas-ui';
+
+const BasicExample = () => {
+  return (
+    <TapasTabTitle text="Home" />
+  );
+};
+```
+
+### 带通知指示器
+
+```tsx
+import React from 'react';
+import { TapasTabTitle } from '@beppla/tapas-ui';
+
+const WithIndicatorExample = () => {
+  return (
+    <TapasTabTitle 
+      text="Messages" 
+      showIndicator={true}
+      indicatorColor="#FF4444"
+    />
+  );
+};
+```
+
+### Tab导航示例
+
+```tsx
+import React, { useState } from 'react';
+import { View, TouchableOpacity } from 'react-native';
+import { TapasTabTitle } from '@beppla/tapas-ui';
+
+const TabNavigationExample = () => {
+  const [activeTab, setActiveTab] = useState(0);
+  
+  const tabs = [
+    { title: 'Home', hasNotification: false },
+    { title: 'Messages', hasNotification: true },
+    { title: 'Notifications', hasNotification: true },
+    { title: 'Settings', hasNotification: false },
+  ];
+
+  return (
+    <View style={{ flexDirection: 'row' }}>
+      {tabs.map((tab, index) => (
+        <TouchableOpacity 
+          key={index}
+          style={{
+            flex: 1,
+            padding: 12,
+            backgroundColor: activeTab === index ? '#E3F2FD' : 'transparent',
+          }}
+          onPress={() => setActiveTab(index)}
+        >
+          <TapasTabTitle
+            text={tab.title}
+            showIndicator={tab.hasNotification}
+            textStyle={{
+              color: activeTab === index ? '#007AFF' : '#8E8E93',
+              fontWeight: activeTab === index ? 'bold' : 'normal',
+            }}
+          />
+        </TouchableOpacity>
+      ))}
+    </View>
+  );
+};
+```
+
+### 自定义指示器样式
+
+```tsx
+import React from 'react';
+import { TapasTabTitle } from '@beppla/tapas-ui';
+
+const CustomIndicatorExample = () => {
+  return (
+    <View style={{ gap: 16 }}>
+      {/* 不同颜色的指示器 */}
+      <TapasTabTitle 
+        text="Alerts" 
+        showIndicator={true}
+        indicatorColor="#FF9500"
+        indicatorSize={6}
+      />
+      
+      {/* 绿色指示器 */}
+      <TapasTabTitle 
+        text="Updates" 
+        showIndicator={true}
+        indicatorColor="#00C851"
+        indicatorSize={8}
+      />
+      
+      {/* 大尺寸指示器 */}
+      <TapasTabTitle 
+        text="Important" 
+        showIndicator={true}
+        indicatorColor="#FF4444"
+        indicatorSize={12}
+      />
+    </View>
+  );
+};
+```
+
+### 自定义指示器位置
+
+```tsx
+import React from 'react';
+import { TapasTabTitle } from '@beppla/tapas-ui';
+
+const CustomPositionExample = () => {
+  return (
+    <View style={{ gap: 16 }}>
+      {/* 默认位置 */}
+      <TapasTabTitle 
+        text="Default Position" 
+        showIndicator={true}
+        indicatorOffset={{ top: 0, right: -8 }}
+      />
+      
+      {/* 右上角 */}
+      <TapasTabTitle 
+        text="Top Right Corner" 
+        showIndicator={true}
+        indicatorOffset={{ top: -2, right: -2 }}
+      />
+      
+      {/* 远离文本 */}
+      <TapasTabTitle 
+        text="Far Right" 
+        showIndicator={true}
+        indicatorOffset={{ top: 0, right: -15 }}
+      />
+      
+      {/* 偏下位置 */}
+      <TapasTabTitle 
+        text="Lower Position" 
+        showIndicator={true}
+        indicatorOffset={{ top: 5, right: -8 }}
+      />
+    </View>
+  );
+};
+```
+
+### 自定义文本样式
+
+```tsx
+import React from 'react';
+import { TapasTabTitle } from '@beppla/tapas-ui';
+
+const CustomTextExample = () => {
+  return (
+    <View style={{ gap: 16 }}>
+      {/* 大号文字 */}
+      <TapasTabTitle 
+        text="Large Text" 
+        showIndicator={true}
+        textStyle={{
+          fontSize: 20,
+          fontWeight: 'bold',
+          color: '#0066CC',
+        }}
+      />
+      
+      {/* 自定义颜色和字体 */}
+      <TapasTabTitle 
+        text="Custom Style" 
+        showIndicator={true}
+        textStyle={{
+          fontSize: 16,
+          fontWeight: '500',
+          color: '#8B5CF6',
+          letterSpacing: 0.5,
+        }}
+        indicatorColor="#8B5CF6"
+      />
+    </View>
+  );
+};
+```
+
+### 长文本处理
+
+```tsx
+import React from 'react';
+import { TapasTabTitle } from '@beppla/tapas-ui';
+
+const LongTextExample = () => {
+  return (
+    <View style={{ width: 150 }}>
+      <TapasTabTitle 
+        text="Very Long Tab Title That Will Be Truncated"
+        showIndicator={true}
+        textProps={{
+          numberOfLines: 1,
+          ellipsizeMode: 'tail'
+        }}
+      />
+    </View>
+  );
+};
+```
+
+### 动态通知状态
+
+```tsx
+import React, { useState } from 'react';
+import { View } from 'react-native';
+import { TapasTabTitle } from '@beppla/tapas-ui';
+import { TapasButton } from '@beppla/tapas-ui';
+
+const DynamicNotificationExample = () => {
+  const [hasNotification, setHasNotification] = useState(false);
+
+  return (
+    <View style={{ alignItems: 'center', gap: 16 }}>
+      <TapasTabTitle 
+        text="Dynamic Notification" 
+        showIndicator={hasNotification}
+        indicatorColor="#FF4444"
+      />
+      
+      <TapasButton
+        title={hasNotification ? "Clear Notification" : "Add Notification"}
+        onPress={() => setHasNotification(!hasNotification)}
+      />
+    </View>
+  );
+};
+```
+
+### 可访问性支持
+
+```tsx
+import React from 'react';
+import { TapasTabTitle } from '@beppla/tapas-ui';
+
+const AccessibilityExample = () => {
+  return (
+    <TapasTabTitle 
+      text="Accessible Tab"
+      showIndicator={true}
+      accessible={true}
+      accessibilityRole="tab"
+      accessibilityState={{ selected: true }}
+      accessibilityLabel="Home tab with notifications"
+      accessibilityHint="Double tap to open home section"
+    />
+  );
+};
+```
+
+## 指示器配置详解
+
+### 颜色选择
+- **红色 (#FF4444)**: 用于重要通知、错误提示
+- **橙色 (#FF9500)**: 用于警告、待处理事项
+- **绿色 (#00C851)**: 用于成功状态、完成提示
+- **蓝色 (#007AFF)**: 用于信息提示、一般通知
+- **紫色 (#AF52DE)**: 用于特殊状态、VIP提示
+
+### 尺寸建议
+- **小尺寸 (3-4px)**: 适用于密集布局、小字体
+- **标准尺寸 (5-6px)**: 适用于大多数场景
+- **中等尺寸 (8-10px)**: 适用于需要突出显示的场景
+- **大尺寸 (12px+)**: 适用于重要提示、显著标记
+
+### 位置配置
+```tsx
+// 默认位置（文本右上角稍微偏右）
+indicatorOffset={{ top: 0, right: -8 }}
+
+// 紧贴右上角
+indicatorOffset={{ top: -2, right: -2 }}
+
+// 远离文本
+indicatorOffset={{ top: 0, right: -15 }}
+
+// 垂直居中
+indicatorOffset={{ top: 8, right: -8 }}
+```
+
+## 主题集成
+
+组件会自动使用应用主题的以下属性：
+
+```tsx
+// 文本样式
+fontSize: theme.fonts?.sizeM || 16
+fontWeight: "600"
+color: theme.colors.colorTextPrimary || theme.colors.primary
+
+// 容器样式
+alignItems: "flex-start"
+justifyContent: "center"
+```
+
+可以通过 `textStyle` 覆盖默认主题样式：
+
+```tsx
+<TapasTabTitle 
+  text="Custom Theme"
+  textStyle={{
+    fontSize: 18,
+    color: '#custom-color',
+    fontFamily: 'custom-font'
+  }}
+/>
+```
+
+## 最佳实践
+
+1. **文本长度控制**: 保持Tab标题简洁，一般不超过10个字符
+2. **指示器颜色**: 在应用中保持一致的颜色语义
+3. **通知及时清除**: 提供清除通知的机制，避免永久显示
+4. **可访问性**: 为指示器提供合适的可访问性描述
+5. **响应式设计**: 在不同屏幕尺寸下测试显示效果
+
+## 向后兼容
+
+为了确保向后兼容，组件同时导出了以下别名：
+
+```tsx
+// 新的推荐用法
+import { TapasTabTitle } from '@beppla/tapas-ui';
+
+// 向后兼容的用法
+import { TabTitle } from '@beppla/tapas-ui';
+```
+
+## 使用场景
+
+- Tab导航栏标题
+- 页面section标题
+- 菜单项标签
+- 状态指示标签
+- 通知提示文本
+- 分类标签
+
+## 注意事项
+
+1. 指示器位置基于文本元素的相对定位，确保父容器有足够空间
+2. 长文本会自动截断，建议设置合适的容器宽度
+3. 指示器颜色应该与应用整体色彩方案保持一致
+4. 在深色主题下，注意指示器颜色的对比度
+5. 组件支持React Native和React Native Web环境