企业官网建设流程全解析

• UI组件
• 移动开发
• 前端

导读

SearchBar 是 React Native Elements 提供的用于搜索或过滤列表的输入组件，当列表项数量直接影响用户查找目标的效率时，它是最合适的交互入口。本文以version-3.4.2版本的 SearchBar 文档为骨架，结合当前仓库packages/base/src/SearchBar的完整源码实现，系统讲解三种平台风格（default / iOS / Android）的切换原理、全部 Props 的默认值与作用、以及通过 ref 调用focus / blur / clear / cancel交互方法的具体方式，帮助你写出可复制、可运行、可定制的搜索栏。

SearchBar 能解决什么问题

原文档开篇即明确了组件的适用场景：

SearchBars are used to search or filter items. Use a SearchBar when the number of items directly impacts a user's ability to find one of them.

也就是说，SearchBar 适合"列表数据量大、需要实时过滤"的场景，例如联系人列表、商品列表、设置项搜索等。它是一个受控组件：搜索文本由外层组件持有（value），用户输入通过onChangeText回调同步回状态，再驱动列表过滤逻辑。

在 React Native Elements 中，SearchBar 并非单一实现，而是根据platform属性在三种视觉与交互风格之间切换，这是它区别于普通 TextInput 的核心设计。

三种平台风格：default / ios / android

SearchBar 组件本身是一个分发器。从 SearchBar.tsx 的源码可以看到，它维护了一张平台映射表，并通过forwardRef与useImperativeHandle将方法透传给具体的实现组件：

const SEARCH_BAR_COMPONENTS = { ios: SearchBarIOS, android: SearchBarAndroid, default: SearchBarDefault, };

platform属性默认值为"default"；当传入无法识别的值时，会回退到SearchBarDefault。这意味着：

三个实现虽然共享同一套 Props 类型基础（types.tsx），但各自拥有平台专属的默认图标与行为：

• default：搜索图标使用material字体的search，尺寸 18，颜色取主题grey3；
• ios：搜索图标使用ionicon字体的search，尺寸 20，颜色取theme.colors.platform.ios.grey；清除图标为close-circle；
• android：搜索图标使用material字体的search，尺寸 25，聚焦后左侧切换为arrow-back返回箭头，清除图标为clear。

这些默认值都可以通过searchIcon、clearIcon、cancelIcon覆盖或完全隐藏（传null/false）。

基础用法：受控搜索栏

原文档给出的用法是一个标准的类组件受控示例。以@rneui/base包的形式在当前仓库中同样可用（见 website/playground/SearchBar/searchbar.playground.tsx 的导入方式import { SearchBar } from '@rneui/base'，以及 themed 包的 SearchBar/index.tsx 导出）：

import { SearchBar } from 'react-native-elements'; export default class App extends React.Component { state = { search: '', }; updateSearch = (search) => { this.setState({ search }); }; render() { const { search } = this.state; return ( <SearchBar placeholder="Type Here..." onChangeText={this.updateSearch} value={search} /> ); } }

关键点在于value与onChangeText必须成对出现：value决定输入框当前显示的内容，onChangeText负责把新输入同步回组件状态。如果只传value不更新状态，输入框将无法正常编辑。拿到search状态后，即可对列表数据做过滤，例如items.filter(item => item.name.includes(search))。

配合platform即可切换为 iOS / Android 原生观感：

<SearchBar platform="ios" placeholder="Type Here..." onChangeText={this.updateSearch} value={search} />

全部 Props 详解

SearchBar 继承 Input 组件 的全部 Props，因此也继承了标准 React NativeTextInput的所有原生属性（如autoFocus、maxLength、keyboardType、onSubmitEditing等）。在此基础上，SearchBar 增加了以下专属 Props，原文档的 props/searchbar.md 对每个参数都给出了类型与默认值，下面按用途分组展开。

平台切换与主题

从 SearchBar-default.tsx 的实现看，default 风格的容器默认带上下黑色边框与grey0背景；开启lightTheme后，边框变为#e1e1e1，背景切为grey5，输入框背景从searchBg变为grey4。round则直接在inputContainerStyle上追加styles.round。

图标定制

这三个图标都接受两种形式：一是 Icon 组件 的属性对象（{ type, name, size, color, onPress }），二是任意 React 组件。源码中使用renderNode(Icon, searchIcon, defaultSearchIcon(theme))实现"默认值 → 属性对象 → 自定义组件"的逐级降级渲染（见 helpers）。

例如放大 iOS 的清除图标：

<SearchBar platform="ios" searchIcon={{ name: 'search', size: 24, color: '#333' }} clearIcon={{ name: 'close-circle', size: 24, color: '#999' }} />

样式定制

以 iOS 实现为例（SearchBar-ios.tsx），containerStyle作用于外层View（背景色取theme.colors.background），inputContainerStyle作用于圆角输入框（默认borderRadius: 9、minHeight: 36），且聚焦时会通过LayoutAnimation动画腾出 Cancel 按钮的宽度空间。所有样式均通过StyleSheet.flatten([...])与内置样式合并，传值会覆盖而非替换默认样式。

行为与文本

注意onChangeText与onClear的区别：用户逐字输入时只触发onChangeText；只有点击清除图标、或程序化调用clear()时才会触发onClear。

加载状态

典型场景是发起异步搜索请求时展示 loading。三个实现均在rightIcon区域中按{ showLoading && <ActivityIndicator ... /> }的方式渲染（见 common.tsx 的测试用例：传入loadingProps={{ style: { flex: 1 } }}后断言ActivityIndicator的 style 生效）。

iOS 专属：Cancel 按钮

cancelButtonProps内部还包含六个子属性（全部可选）：

从 SearchBar-ios.tsx 的实现看，Cancel 按钮由Pressable包裹View + Text构成，默认文字样式color: '#007aff'、fontSize: 18；按钮宽度通过onLayout动态测量，聚焦时以LayoutAnimation.Presets.easeInEaseOut动画滑入。测试用例（common.tsx）验证了cancelButtonTitle="Annuler"会渲染为按钮文字，以及color、buttonStyle、buttonTextStyle、禁用态样式等均正确生效。

交互方法：focus / blur / clear / cancel

SearchBar 通过 ref 暴露四个命令式方法，原文档以表格形式给出：

注意：cancel方法在platform="default"下是空实现（SearchBar-default.tsx 中cancel: () => {}），因为 default 风格没有取消按钮的交互概念，这与文档"(Android and iOS SearchBars only)"的说明完全一致。

通过 ref 调用方法

原文档的调用方式：利用 React 的 ref 属性保存组件引用，随后即可命令式调用：

<SearchBar ref={(search) => (this.search = search)} placeholder="Type Here..." onChangeText={this.updateSearch} value={this.state.search} />

this.search.focus(); this.search.blur(); this.search.clear(); this.search.cancel(); // 仅当 platform 为 "ios" 或 "android" 时可用

在函数组件中，对应的写法是useRef：

const searchRef = useRef(null); <SearchBar ref={searchRef} platform="ios" />; searchRef.current.focus(); searchRef.current.clear();

从实现层面看，SearchBar使用forwardRef接收外层 ref，再用useImperativeHandle把四个方法转发给内部平台组件的 ref（SearchBar.tsx），内部组件再转发到真正的TextInput。因此无论platform切换成哪一种实现，外层拿到的都是统一的{ focus, blur, clear, cancel }接口。各平台cancel的具体行为略有差异：

• iOS（SearchBar-ios.tsx）：先清空文本；若showCancel为真则通过LayoutAnimation收起 Cancel 按钮，并在下一帧 blur 输入框、触发onCancel；
• Android（SearchBar-android.tsx）：直接 blur 输入框并触发onCancel。

与主题系统的集成

在@rneui/themed包中，SearchBar 通过withTheme包装后默认注入主题（packages/themed/src/SearchBar/index.tsx）。三个平台实现的默认图标与颜色均从主题取值：如 iOS 的theme.colors.platform.ios.grey、Android 的theme.colors.platform.android.grey、default 的theme.colors.grey3/grey5/searchBg，因此定制全局主题即可统一影响所有 SearchBar 的外观，无需逐处覆盖样式。

交互演示与测试验证

仓库为三种平台实现分别提供了完整的测试与快照：packages/base/src/SearchBar/__tests__/下的 SearchBar.test.tsx、SearchBar-ios.test.tsx、SearchBar-android.test.tsx、SearchBar-default.test.tsx 共用 common.tsx 中的通用用例。这些用例覆盖了：

• 事件回调：onClear、onFocus、onBlur、onCancel是否被正确触发；
• 图标定制：自定义searchIcon/clearIcon组件可渲染，传false则隐藏图标；
• 加载态：showLoading与loadingProps的样式传递；
• iOS Cancel 按钮：标题、颜色、样式、禁用态样式的完整断言。

此外，searchbar.playground.tsx 提供了一个可直接交互的 Playground，将platform、lightTheme、round、showLoading、showCancel、cancelButtonTitle等核心属性暴露为可视化控件，是快速验证配置效果的便捷入口。

快速上手清单

1. 受控输入：始终同时提供value与onChangeText，把搜索词提升到组件状态；
2. 选对平台：按目标平台设置platform="ios"/"android"，或保留默认跨平台观感；如需圆角/浅色，在 default 下使用round/lightTheme；
3. 定制图标与样式：用searchIcon、clearIcon、cancelIcon（Android）覆盖图标，用四个*Style属性叠加样式；
4. 异步搜索：请求期间开启showLoading，并用loadingProps调整指示器细节；
5. 命令式控制：通过 ref 调用focus()、clear()等；涉及"取消"语义时记得platform必须是ios或android，否则cancel()不生效；
6. 记住回调分工：onChangeText处理逐字输入，onClear处理点击清除图标，onCancel处理点击取消（iOS Cancel / Android 返回箭头）。

• UI组件
• 移动开发
• 前端