react-native-modal-dropdown:基于 React Native for OpenHarmony 的模态下拉选择组件项目

同时下拉组件，支持内容配置、交互控制和样式调整，满足提示、确认及信息展示等场景需求。

分支3 Tags2

本项目基于 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+

运行步骤

获取开发分支源码。

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

进入仓库根目录。
```
cd react-native-modal-dropdown
```
进入 example 目录。
```
cd example
```
安装示例工程依赖。
```
npm install --legacy-peer-deps
```
使用 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 中上传敏感信息；可按组织安全流程提交脱敏日志。

项目介绍

同时下拉组件，支持内容配置、交互控制和样式调整，满足提示、确认及信息展示等场景需求。