@hxa-rn/react-native-modal-dropdown

本项目基于 react-native-modal-dropdown 开发，并适配 React Native for OpenHarmony。 如果在使用过程中有任何问题，可以在 GitCode 提交 Issue，我们会及时跟进。

项目介绍

@hxa-rn/react-native-modal-dropdown 是一个纯 JavaScript 的 React Native 模态下拉选择组件，可使用默认按钮或自定义子元素触发下拉列表，并保持与上游公开 API 兼容。

• 支持字符串或对象选项、默认选中项、禁用状态和加载状态。
• 支持淡入动画、自动边缘定位、全宽弹层、滚动控制和选中项定位。
• 支持自定义按钮、右侧内容、选项行、分隔线、搜索区域及组件样式。
• 支持字符串与对象选项搜索，筛选后的 onSelect 仍返回源选项索引。
• 支持展示、隐藏和选择回调，以及 show()、hide()、select(index) 实例方法。

集成指南

安装

在 React Native 工程根目录执行：

npm install @hxa-rn/react-native-modal-dropdown

宿主工程需使用 React Native >=0.72。

Autolinking

本库为纯 JavaScript 包，安装依赖后由宿主工程自动接入，无需手动注册。

导入

import ModalDropdown, {
  ModalDropdown as NamedModalDropdown,
  type ModalDropdownProps,
} from '@hxa-rn/react-native-modal-dropdown';

ModalDropdown 同时提供默认导出和命名导出；ModalDropdownProps 提供组件属性类型。

使用说明

基础用法

import React, { useRef } from 'react';
import { Text, View } from 'react-native';
import ModalDropdown from '@hxa-rn/react-native-modal-dropdown';

const options = [
  { name: 'Rex', role: 'Developer' },
  { name: 'Mary', role: 'Designer' },
];

export default function Example() {
  const dropdownRef = useRef<ModalDropdown | null>(null);

  return (
    <View>
      <ModalDropdown
        ref={dropdownRef}
        options={options}
        defaultValue="选择团队成员"
        showSearch
        keySearchObject="name"
        renderButtonText={item => `${item.name} · ${item.role}`}
        renderRowText={item => `${item.name} · ${item.role}`}
        onSelect={(index, item) => {
          console.info(index, item.name);
        }}
      />
      <Text onPress={() => dropdownRef.current?.show()}>打开下拉列表</Text>
    </View>
  );
}

当 options 为 null 或 undefined 时，组件显示加载状态。启用 showSearch 后，字符串选项可直接搜索；对象选项需通过 keySearchObject 指定匹配字段，并可使用 renderButtonText 或 renderRowText 指定显示文本。

自定义选项行

<ModalDropdown
  options={['HarmonyOS', 'Android', 'iOS']}
  defaultValue="选择运行平台"
  dropdownStyle={{ width: 220, height: 180 }}
  renderRightComponent={() => <Text>⌄</Text>}
  renderRow={(option, index, isSelected) => (
    <Text style={{ fontWeight: isSelected ? '700' : '400', padding: 12 }}>
      {index + 1}. {option}
    </Text>
  )}
  renderSeparator={() => <View style={{ height: 1, backgroundColor: '#ddd' }} />}
/>

renderRow 接收选项值、源选项索引和选中状态。renderSeparator 可替换默认分隔线，renderRightComponent 可提供按钮右侧内容。

接口文档

以下 API 依据 src/index.js、src/index.d.ts 和 src/ModalDropdown.js 整理。组件提供默认导出和命名导出 ModalDropdown，并导出 ModalDropdownProps 类型。

ModalDropdown

模态下拉选择组件。除下表属性外，组件还接受 React Native ViewProps，并支持使用 children 作为自定义触发器内容。

| 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | disabled | boolean | false | 是否禁用触发器。 | | multipleSelect | boolean | false | 选择选项后是否保持下拉层展开。 | | scrollEnabled | boolean | true | 是否允许选项列表滚动。 | | saveScrollPosition | boolean | true | 打开时是否将已选项滚动到可视区域。 | | defaultIndex | number | -1 | 初始选中索引；负数表示未选中。 | | defaultValue | string | 'Please select...' | 未选中时显示的默认文本。 | | options | any[] \| null | null | 选项数组；为 null 或 undefined 时显示加载状态。 | | accessible | boolean | true | 是否向无障碍服务暴露触发器、弹层和选项行。 | | animated | boolean | true | 是否使用淡入动画显示下拉层。 | | isFullWidth | boolean | false | 是否使下拉层与触发器左右边界对齐。 | | showsVerticalScrollIndicator | boolean | true | 是否显示列表纵向滚动条。 | | keyboardShouldPersistTaps | 'always' \| 'never' \| 'handled' | 'never' | 传递给 FlatList 的键盘点击行为。 | | showSearch | boolean | false | 是否显示搜索区域。 | | keySearchObject | string | 'label' | 对象选项搜索使用的字段名。 | | searchPlaceholder | string | 'Search' | 内置搜索输入框的占位文本。 | | searchInputStyle | StyleProp<ViewStyle> | 未声明 | 内置搜索输入框样式。 | | renderSearch | ComponentType<any> \| ReactElement | 未声明 | 自定义搜索组件或元素；组件接收 value、onChangeText、placeholder、options 和 keySearchObject。 | | style | StyleProp<ViewStyle> | 未声明 | 根容器样式。 | | textStyle | StyleProp<TextStyle> | 未声明 | 默认按钮文本样式。 | | defaultTextStyle | StyleProp<TextStyle> | 未声明 | 默认值文本样式。 | | dropdownStyle | StyleProp<ViewStyle> | 未声明 | 下拉层容器样式。 | | dropdownTextStyle | StyleProp<TextStyle> | 未声明 | 默认选项文本样式。 | | dropdownTextHighlightStyle | StyleProp<TextStyle> | 未声明 | 当前选中选项的文本样式。 | | dropdownListProps | Partial<FlatListProps<any>> | {} | 传递给选项 FlatList 的属性。 | | dropdownTextProps | Record<string, any> | {} | 传递给默认选项 Text 的属性。 | | adjustFrame | (style) => style | 未声明 | 下拉层显示前接收定位样式并返回修正后的样式。 | | renderRow | (option, index, isSelected) => ReactNode | 未声明 | 自定义选项行；未提供时渲染默认文本行。 | | renderRowComponent | ComponentType<any> | TouchableHighlight | 自定义选项行触摸组件。 | | renderRowProps | Record<string, any> | {} | 传递给选项行触摸组件的属性。 | | renderSeparator | (sectionID, rowID, adjacentRowHighlighted) => ReactNode | 未声明 | 自定义选项分隔线。 | | renderButtonText | (option) => string | 未声明 | 从选项中生成按钮显示文本。 | | renderRowText | (option) => string | 未声明 | 从选项中生成默认选项行文本。 | | renderButtonComponent | ComponentType<any> | TouchableOpacity | 自定义按钮触摸组件。 | | renderRightComponent | ComponentType<any> \| ReactElement | View | 自定义按钮右侧内容。 | | renderButtonProps | Record<string, any> | {} | 传递给按钮触摸组件的属性。 | | buttonAndRightComponentContainerStyle | StyleProp<ViewStyle> | 未声明 | 按钮文本与右侧内容容器的样式。 | | onDropdownWillShow | () => boolean \| void | 未声明 | 用户触发展示前调用；返回 false 可取消展示。 | | onDropdownWillHide | () => boolean \| void | 未声明 | 用户触发隐藏前调用；返回 false 可取消隐藏。 | | onSelect | (index, value) => boolean \| void | 未声明 | 用户选择选项时调用；返回 false 可取消选中结果更新。 | | numberOfLines | number | 1 | 默认按钮文本最大显示行数。 |

实例方法

| 方法 | 参数 | 说明 | | --- | --- | --- | | show() | 无 | 程序化显示下拉层，不触发 onDropdownWillShow。 | | hide() | 无 | 程序化隐藏下拉层，不触发 onDropdownWillHide。 | | select(index) | index?: number \| null | 程序化选中指定项，不触发 onSelect；未提供索引、选项不存在或索引超出数组上界时回退到 defaultIndex。 |

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | | :-- | --- | | Node.js | >=20 | | React Native for OpenHarmony | 0.72.139 | | HarmonyOS SDK | API 21+ |

运行步骤

1. 获取开发分支源码。

   git clone -b react-native-modal-dropdown_dev https://gitcode.com/hxa-rn/react-native-modal-dropdown.git

2. 进入仓库根目录。

   cd react-native-modal-dropdown

3. 进入 example 目录。

   cd example

4. 安装示例工程依赖。

   npm install --legacy-peer-deps

5. 使用 DevEco Studio 打开 example/harmony，同步依赖并完成签名配置后构建运行。

约束与限制

兼容性

| 依赖 | 要求 | | --- | --- | | React Native for OpenHarmony | 0.72.139 | | HarmonyOS SDK | API 21+ | | Example 工程 compatibleSdkVersion | 6.0.1(21) | | Example 工程 targetSdkVersion | 6.1.1(24) | | Node.js | >=18；运行 Example 需 >=20 |

使用限制

• 本库为纯 JavaScript 适配，不包含 HarmonyOS 原生组件或原生模块。
• options 为 null 或 undefined 时显示加载状态；传入数组后才会渲染选项。
• 用户触发的 onDropdownWillShow、onDropdownWillHide 或 onSelect 返回 false 时，会取消对应操作。
• show()、hide() 和 select(index) 为程序化调用，不触发展示、隐藏或选择回调。
• 对对象数组启用搜索时，应设置 keySearchObject，并按需使用 renderButtonText 或 renderRowText 指定显示文本。

系统权限

本库不依赖额外的 HarmonyOS 系统权限。

开源 License

本项目采用 MIT License，与上游项目保持一致。

问题反馈渠道

如在使用过程中遇到问题，请在 GitCode 提交Issue，我们会及时跟进。

• 提交问题时建议附上项目版本、RN 版本、OpenHarmony SDK/API 版本、DevEco Studio 版本、设备信息、复现步骤及相关日志。
• 涉及签名、账号、密钥或用户数据时，请勿在 Issue 中上传敏感信息；可按组织安全流程提交脱敏日志。