react-native-app-common-components

一套基于 React Native 的通用组件库，包含按钮、弹窗、遮罩层、轻提示等常用 UI 组件，支持 Android 和 iOS 平台，提供简洁易用的 API 和良好的交互体验。

📦 安装

npm install react-native-app-common-components
# 或者使用 yarn
yarn add react-native-app-common-components

ConfigProvider 配置提供器

import {ConfigProvider} from 'react-native-app-common-components';

<ConfigProvider value={{themeColor: "red"}}>
  <App/>
</ConfigProvider>

value

| 参数 | 类型 | 默认值 | 说明 | |--------------|----------|-------------|------| | themeColor | string | '#007AFF' | 主题颜色 |

Button 按钮组件:

import {Button} from 'react-native-app-common-components';

<Button onPress={() => {
  console.log('点击按钮')
}}>
  <Text>点击</Text>
</Button>

| 参数 | 类型 | 默认值 | 说明 | |------------------|--------------|---------------------|--------| | onPress | () => void | — | 点击事件 | | children | ReactNode | — | 按钮内部内容 | | disabled | boolean | false | 是否禁用 | | containerStyle | ViewStyle | — | 外部样式 | | loadingColor | string | 'rgb(15, 15, 15)' | 加载动画颜色 | | openDebounce | boolean | false | 是否开启防抖 |

Modal 弹窗组件:

import {Modal} from 'react-native-app-common-components';

<Modal
    title="提示"
    visible={visible}
    onCancel={() => setVisible(false)}
>
  <View>
    <Text>弹窗内容</Text>
  </View>
</Modal>

| 参数 | 类型 | 默认值 | 说明 | |---------------------|---------------------------------------------|--------------------|-------------| | visible | boolean | — | 是否可见 | | title | string | — | 弹窗标题 | | onCancel | () => void | — | 点击取消按钮或关闭按钮 | | onConfirm | () => void | — | 点击确认按钮 | | onShow | () => void | — | 弹窗展示时触发 | | onDismiss | () => void | — | 弹窗隐藏时触发 | | onRequestClose | () => void | — | 安卓物理返回键关闭事件 | | animationType | "none" \| "fade" \| "slide" | 'fade' | 动画类型 | | buttonType | 'cancel' \| 'confirm' \| 'both' \| 'none' | 'both' | 显示的按钮类型 | | presentationStyle | 'fullScreen' \| 'overFullScreen' | 'overFullScreen' | 展示模式（iOS） | | showCloseIcon | boolean | true | 是否显示右上角关闭按钮 |

ViewModal 滚动弹窗组件:

import {ViewModal} from 'react-native-app-common-components';

<ViewModal
    title="提示"
    visible={visible}
    onCancel={() => setVisible(false)}
>
  <View style={{height: 800}}>
    <Text>滚动弹窗内容</Text>
  </View>
</ViewModal>

| 参数 | 类型 | 默认值 | 说明 | |-------------------|---------------------------------------------|----------|---------------| | visible | boolean | — | 是否可见 | | title | string | — | 弹窗标题 | | onCancel | () => void | — | 点击取消按钮或关闭按钮 | | onConfirm | () => void | — | 点击确认按钮 | | buttonType | 'cancel' \| 'confirm' \| 'both' \| 'none' | 'both' | 显示的按钮类型 | | showCloseIcon | boolean | true | 是否显示右上角关闭按钮 | | containerStyle | ViewStyle | — | 容器自定义样式 | | children | ReactElement | — | 弹窗内容 | | onClose | () => void | — | 点击取消按钮或关闭按钮 | | maskCloseEnable | boolean | true | 是否开启点击遮罩层关闭弹窗 |

MaskModal 遮罩弹窗组件:

import {MaskModal} from 'react-native-app-common-components';

<MaskModal visible={visible}>
  <Text>我是内容</Text>
</MaskModal>

| 参数 | 类型 | 默认值 | 说明 | |-------------------|--------------|--------|---------------| | visible | boolean | — | 是否展示 | | children | ReactNode | — | 内容 |
| onClose | () => void | — | 点击取消按钮或关闭按钮 | | maskCloseEnable | boolean | true | 是否开启点击遮罩层关闭弹窗 |

Toast 轻提示组件:

import {ToastProvider} from 'react-native-app-common-components';

// 全局注册 ToastProvider（在 App 顶层）:    
export default function App() {
  return (
      <ToastProvider value={{}}>
        {/* 你的应用其他组件 */}
      </ToastProvider>
  );
}

// 调用 Toast
import {Toast} from 'react-native-app-common-components';

function OtherPage() {

  return (
      <Button onPress={() => {
        Toast.show({
          type: 'success',
          text: '操作成功',
          duration: 2000,
          position: 'center'
        });
        // 关闭提示
        Toast.close();
      }}>
        显示提示
      </Button>
  );
}

show：

| 参数 | 类型 | 默认值 | 说明 | |------------|-------------------------------------------------------------------|-------------|-------------| | type | 'loading' \| 'success' \| 'fail' \| 'warning' \| 'loading_only' | 'loading' | 提示类型 | | text | string | — | 显示文本 | | duration | number | 2000 | 显示时长（0 为常驻） | | position | 'top' \| 'center' \| 'bottom' | 'center' | 弹窗位置 | | icon | ReactNode | — | 自定义图标 |

close：

| 参数 | 类型 | 默认值 | 说明 | |---------|----------|-----|------------| | delay | number | 0 | 延迟关闭时间（ms） |

CountDown 倒计时组件

import {CountDown} from 'react-native-app-common-components';

const [startCount, setStartCount] = useState(false);
const [count, setCount] = useState(100);

// 你的页面中
function App() {
  return (
      <CountDown
          start={startCount} reSendText={'retry'} noSendText={'getCode'}
          duration={100} sendText={count + 's'}
          onChange={(count) => {
            setCount(count)
          }}
          onClick={() => {
            //发送验证码逻辑
            setStartCount(true);
          }
          }/>
  )
}

| 参数 | 类型 | 默认值 | 说明 | |------------------|---------------------------|---------|-------------| | onClick | () => void | — | 点击事件 | | start | boolean | false | 是否开始倒计时 | | initText | string | '' | 初始文本 | | startText | string | '' | 开启倒计时时的文本 | | endText | string | '' | 倒计时结束文本 | | textStyle | TextStyle | — | 文本样式 | | containerStyle | ViewStyle | — | 容器样式 | | duration | number | 60 | 倒计时时间（秒） | | onChange | (count: number) => void | — | 倒计时变化时的回调函数 |

Tabs标签页组件

import {Tabs} from 'react-native-app-common-components';

function App() {
  const [itemName, setItemName] = useState('');
  return (
      <Tabs defaultValue={'最新'} onChange={(itemName: string) => {
        setItemName(itemName)
      }} items={['热播', '最新', '好评']}>
        <Tab title={'热播'}>
          <Text>热播</Text>
        </Tab>
        <Tab title={'最新'}>
          <Text>最新</Text>
        </Tab>
        <Tab title={'好评'}>
          <ScrollView style={{height: "100%", width: "100%", backgroundColor: "red"}}>
            {[1, 2, 3, 4, 5, 6, 7, 8, 9, 10].map((item, index) => {
              return (
                  <View key={index} style={{height: 200, backgroundColor: "#FFFFFF"}}>
                    <Text>{item}</Text>
                  </View>
              )
            })}
          </ScrollView>
        </Tab>
      </Tabs>
  )
}

Tabs参数

| 参数 | 类型 | 默认值 | 说明 | |-------------------|-----------------------------|-----------|-------------| | onChange | (itemName:string) => void | — | 标签页切换时的回调函数 | | defaultValue | string | '' | 默认选中的标签页 | | items | string[] | [] | 标签页名称数组,必传 | | backgroundColor | string | '#FFFFFF' | 标签页背景颜色 | | activeColor | string | '#1677ff' | 选中标签页的颜色 |

tab参数

| 参数 | 类型 | 默认值 | 说明 | |---------|----------|------|-----------------------| | title | string | '' | 标签页名称,必须与items数组中的值一致 |

CheckBox复选框组件

import {CheckBox} from 'react-native-app-common-components';

function DemoPage() {
  const [checked, setChecked] = useState(false);
  return (
      <View>
        <CheckBox checked={checked} onChange={setChecked}/>
      </View>
  )
}

CheckBox Props 参数

| 参数 | 类型 | 默认值 | 说明 | |------------------|----------------------------|-----------|----------| | checkedBgColor | string | #1677ff | 选中背景颜色 | | checked | boolean | false | 是否选中 | | onChange | (value: boolean) => void | — | 选中状态改变回调 | | defaultChecked | boolean | false | 默认选中 | | disabled | boolean | false | 是否禁用 |

对话框组件

import {DialogProvider} from "react-native-app-common-components";
import {Dialog} from "react-native-app-common-components";
import {Button} from "react-native-app-common-components";

function App() {
  return (
      <DialogProvider value={{}}>
        <DemoPage/>
      </DialogProvider>
  )
}

function DemoPage() {
  return (
      <View>
        <Button onPress={() => {
          Dialog.confirm({
            content: '确定删除吗？',
            confirmText: '确定',
            cancelText: '取消',
            onConfirm: () => {
              Toast.show({text: '删除成功'})
            },
            onCancel: () => {
              Toast.show({text: '取消删除'})
            },
          })
        }}>
          测试button
        </Button>
      </View>
  )
}

DialogProvider参数:

| 参数 | 类型 | 默认值 | 说明 | |------------------|-------------|-----|------| | textStyle | TextStyle | — | 文本样式 | | maskStyle | ViewStyle | — | 蒙层样式 | | containerStyle | ViewStyle | — | 容器样式 |

Dialog.confirm参数:

| 参数 | 类型 | 默认值 | 说明 | |---------------|--------------|--------|--------| | content | string | '' | 对话框内容 | | cancelText | string | '取消' | 取消按钮文本 | | confirmText | string | '确定' | 确定按钮文本 | | onConfirm | () => void | — | 确定按钮回调 | | onCancel | () => void | — | 取消按钮回调 |

Dialog.alert参数:

| 参数 | 类型 | 默认值 | 说明 | |---------------|--------------|--------|--------| | content | string | '' | 对话框内容 | | confirmText | string | '确定' | 确定按钮文本 | | onConfirm | () => void | — | 确定按钮回调 |

Dialog.clear参数:

| 参数 | 类型 | 默认值 | 说明 | |-----------|----------|--------|------------| | timeout | number | 2000 | 清除对话框的超时时间 |

Empty组件:

import {Empty} from "react-native-app-common-components";

function DemoPage() {
  return (
      <View>
        <Empty description={'暂无数据'}/>
      </View>
  )
}

Empty组件参数:

| 参数 | 类型 | 默认值 | 说明 | |------------------|-------------|------|--------| | description | string | '' | 暂无数据描述 | | containerStyle | ViewStyle | — | 容器样式 | | textStyle | TextStyle | — | 文本样式 |

Select组件

import {Select} from "react-native-app-common-components";

function DemoPage() {
  return (
      <View>
        <Select options={[{label: '男', value: '男'}, {label: '女', value: '女'}]}/>
      </View>
  )
}

Select组件参数:

| 参数 | 类型 | 默认值 | 说明 | |---------------------|---------------------------------|------|----------| | options | {label:string,value:string}[] | [] | 选项数组 | | placeholder | string | '' | 未选择时的占位符 | | title | string | '' | 弹窗标题 | | onSelect | (itemName:string) => void | — | 选择回调 | | containerStyle | ViewStyle | — | 弹窗容器样式 | | selectStyle | ViewStyle | — | 选择器样式 | | selectTextStyle | TextStyle | — | 选择器文本样式 | | itemStyle | ViewStyle | — | 选项样式 | | selectedItemStyle | ViewStyle | — | 选中选项样式 |

SearchBar组件:

import {SearchBar} from "react-native-app-common-components";

function DemoPage() {
  return (
      <View>
        <SearchBar
            containerStyle={{backgroundColor: "#666666"}}
            selectionColor={"#FFFFFF"}
            onSearch={(value) => {
            }}
        />
      </View>
  )
}

SearchBar组件参数:

| 参数 | 类型 | 默认值 | 说明 | |------------------------|---------------------------|-------------|----------| | onSearch | (value: string) => void | — | 搜索回调 | | defaultValue | string | '' | 默认值 | | clearEnable | boolean | true | 是否显示清除按钮 | | searchTextEnable | boolean | true | 是否显示搜索按钮 | | placeholder | string | '' | 占位符 | | placeholderTextColor | string | '#b3b3b3' | 占位符文本颜色 | | selectionColor | string | '#000000' | 光标颜色 | | containerStyle | ViewStyle | — | 容器的样式 | | inputStyle | ViewStyle | — | 输入框的样式 | | searchTextStyle | TextStyle | — | 搜索文本的样式 | | searchIcon | ReactNode | — | 搜索图标 | | clearIcon | ReactNode | — | 清除图标 |

Avatar组件:

import {Avatar} from "react-native-app-common-components";

function DemoPage() {
  return (
      <View>
        <Avatar
            source={{uri: 'https://example.com/avatar.jpg'}}
        />
      </View>
  )
}

Avatar组件参数:

| 参数 | 类型 | 默认值 | 说明 | |-----------------|-----------------------|-----|--------| | source | ImageSourcePropType | — | 头像图片 | | onPress | () => void | — | 点击回调 | | avatarStyle | ImageStyle | — | 头像样式 | | defaultSource | ImageSourcePropType | — | 默认头像图片 |

Switch开关组件

import {Switch} from 'react-native-app-common-components';

function DemoPage() {
  const [checked, setChecked] = useState(false);
  return (
      <View>
        <Switch checked={checked} onChange={setChecked}/>
      </View>
  )
}

Switch Props 参数

| 参数 | 类型 | 默认值 | 说明 | |------------------|----------------------------|-----------|----------| | checkedBgColor | string | #1677ff | 选中背景颜色 | | checked | boolean | false | 是否选中 | | onChange | (value: boolean) => void | — | 选中状态改变回调 | | defaultChecked | boolean | false | 默认选中 | | disabled | boolean | false | 是否禁用 |

PasswordInput 密码输入框组件

import {PasswordInput, Toast} from 'react-native-app-common-components';
import {useState, useRef} from 'react';

function Demo() {
  const [value, setValue] = useState('');
  const passwordInputRef = useRef < PasswordInput > (null);
  return (
      <PasswordInput ref={passwordInputRef} value={value} onChange={(value) => {
        setValue(value)
      }}/>
  )
}

PasswordInput 密码输入框组件参数:

| 参数 | 类型 | 默认值 | 说明 | |------------------|----------------------------|--------|-------------------------------| | value | string | '' | 输入的值 | | ref | RefObject<PasswordInput> | — | 输入框的 ref 用于获取输入框的textInputRef | | maxLength | number | 6 | 最大长度 | | inputItemStyle | ViewStyle | — | 小方框的样式 | | circleStyle | ViewStyle | — | 圆的样式 | | onChange | (value: string) => void | — | 输入框的值改变时的回调 | | onSubmit | (value: string) => void | — | 输入框的值提交时的回调 当输入框的值长度达到最大长度时触发 | | autoFocus | boolean | true | 是否自动获取焦点 | | selectionColor | string | — | 选中的颜色 |

TextArea 文本域组件:

import {TextArea, Toast} from 'react-native-app-common-components';

function Demo() {
  return (
      <TextArea
          containerStyle={{height: 120, width: 200}}
          numberOfLines={10}
          maxLength={300}
          onChange={(content) => {
            Toast.show({text: content})
          }}
      />
  )
}

TextArea 文本域组件参数:

| 参数 | 类型 | 默认值 | 说明 | |------------------------|---------------------------|-------------|-------------| | onChange | (value: string) => void | — | 输入框的值改变时的回调 | | defaultValue | string | '' | 默认值 | | numberOfLines | number | 1 | 行数 | | maxLength | number | 100 | 最大长度 | | showCount | boolean | false | 是否显示字数统计 | | containerStyle | ViewStyle | — | 容器的样式 | | inputStyle | TextStyle | — | 输入框的样式 | | placeholder | string | '' | 占位符 | | placeholderTextColor | string | '#b3b3b3' | 占位符文本颜色 | | selectionColor | string | '#000000' | 光标颜色 | | autoFocus | boolean | false | 是否自动获取焦点 |

CopyText复制文本组件:

📌注意：使用此组件需要引入依赖@react-native-clipboard/clipboard

npm install @react-native-clipboard/clipboard
或
yarn add @react-native-clipboard/clipboard

import {CopyText} from 'react-native-app-common-components';
 function Demo() {
  return (
      <CopyText style={{width: 120}}>1234567891011121314151617181920</CopyText>
  )
}

复制文本组件参数:

| 参数 | 类型 | 默认值 | 说明 | |--------------|----------|-------------|-------------------------| | text | string | — | 文本 | | children | string | — | 子元素,此处children必须为string | | style | ViewStyle | — | 样式 | | textStyle | TextStyle | — | 文本样式 | | icon | ReactNode | — | 图标 |

FlexBox组件:

import {FlexBox} from 'react-native-app-common-components';
function Demo() {
  return (
      <FlexBox>
        <Text>123</Text>
      </FlexBox>
  )
}

FlexBox组件参数:

| 参数 | 类型 | 默认值 | 说明 | |--------------|----------|-------------|-------------------------| | children | ReactNode | — | 子元素 | | onPress | () => void | — | 点击事件 | | style | ViewStyle | — | 样式 |

Ellipsis 文本省略组件

import {Ellipsis} from 'react-native-app-common-components';
function Demo() {
  return (
      <Ellipsis content="example text" />
  )
}

Ellipsis 文本省略组件参数:

| 参数 | 类型 | 默认值 | 说明 | |--------------|----------|-------------|-------------------------| | content | string | — | 文本内容 | | numberOfLines | number | 1 | 行数 默认1行 当行数为0时，不省略 | | ellipsizeMode | TextProps["ellipsizeMode"] | tail | 省略模式，默认tail 当行数为1时，head、middle属性才会生效 | | collapseNode | ReactNode | — | 收起节点 自定义收起节点 | | expandNode | ReactNode | — | 展开节点 自定义展开节点 | | containerStyle | ViewStyle | — | 容器样式 | | textStyle | TextStyle | — | 文本样式 |

TabBar 底部导航组件:

📌结合react-navigation使用此组件

npm install @react-navigation/bottom-tabs
或
yarn add @react-navigation/bottom-tabs

//在App.tsx中引入
import {TabBar} from 'react-native-app-common-components';
import {createBottomTabNavigator} from '@react-navigation/bottom-tabs';
const Tab = createBottomTabNavigator();
function TabNavigator() {
  const tabOptions = [
    {
      title: '首页',
      icon: require('../src/assets/copy.png'),
      activeIcon: require('../src/assets/success.png'),
      activeTextColor: '#007AFF',
      textColor: '#000000',
      badge: '',
      key: 'Home',
    }, {
      title: '我的',
      icon: require('../src/assets/default_avatar.png'),
      activeIcon: require('../src/assets/waring.png'),
      activeTextColor: '#007AFF',
      textColor: '#000000',
      key: 'Profile',
      badge: 'new',
    }
  ]
  return (
      <Tab.Navigator tabBar={({navigation}) => {
        return (
            // 使用tabBar替换默认tab
            <TabBar defaultActiveKey={'Profile'}
                    options={tabOptions}
                    onSwitch={(key: string) => navigation.navigate(key)}/>
        )
      }}>
        <Tab.Screen name="Home" component={HomeScreen} options={{title: "首页", headerShown: false}}/>
        <Tab.Screen name="Profile" component={ProfileScreen} options={{title: "我的", headerShown: false}}/>
      </Tab.Navigator>
  );
}

TabBar 底部导航组件参数:

| 参数 | 类型 | 默认值 | 说明 | |--------------|----------|-------------|-------------------------| | options | OptionType[] | — | 标签栏配置项 | | onSwitch | (key: string) => void | — | 切换回调 | | defaultActiveKey | string | — | 默认选中项 | | backgroundColor | string | #FFFFFF | 背景颜色 | | borderTopColor | string | #f3f3f3 | 顶部边框颜色 | | borderTopWidth | number | 1 | 顶部边框宽度 |

OptionType配置项类型：

| 参数 | 类型 | 默认值 | 说明 | |--------------|---------------------|---------------------|---------| | title | string | — | 选项标题 | | key | string | — | 选项键值 | | icon | ImageSourcePropType | — | 选项图标 | | activeIcon | ImageSourcePropType | — | 选项选中图标 | | activeTextColor | string | config.themeColor | 选项选中文字颜色 | | textColor | string | #000000 | 选项文字颜色 | | badge | string dot | — | 选项角标 |

NavBar顶部导航组件:

📌结合react-navigation使用此组件

npm install @react-navigation/native-stack @react-navigation/native
或
yarn add @react-navigation/native-stack @react-navigation/native

import {NavBar} from 'react-native-app-common-components';
import {createNativeStackNavigator} from '@react-navigation/native-stack';
import {NavigationContainer} from "@react-navigation/native";

const Stack = createNativeStackNavigator();

function RootStack() {
  return (
      <Stack.Navigator
          screenOptions={{
            header: ({navigation, options, route}) =>
                // 使用NavBar替换默认导航栏
                <NavBar
                    title={options.title}
                    showBack={route.name !== 'Main'}
                    onBack={() => navigation.goBack()}
                />,
          }}>
        {/*在Stack.Navigator中注册TabNavigator*/}
        <Stack.Screen name="Main" component={TabNavigator} options={{title: "首页", headerShown: false}}/>
        <Stack.Screen name="Detail" component={DetailScreen} options={{title: "详情"}}/>
      </Stack.Navigator>
  );
}
function App() {
  return (
      <NavigationContainer>
        <ConfigProvider value={{themeColor: "#007AFF", locale: "zh-TW"}}>
          <DialogProvider>
            <ToastProvider>
              {/*在NavigationContainer中引入RootStack*/}
              <RootStack/>
            </ToastProvider>
          </DialogProvider>
        </ConfigProvider>
      </NavigationContainer>
  );
}

📌 注意事项 注意react-native版本不低于0.72 使用 Toast 时务必用 ToastProvider 包裹顶层。

所有组件均为函数式组件，支持 React 18。

这个 README.md 是标准 npm 项目格式，包含：

• 安装方式
• 使用示例
• 每个组件的详细参数表
• 注意事项和结构说明