NavBar 导航栏
页面顶部导航栏,提供标准标题与左右操作区域,也可通过 children 提供整条自定义内容。默认透明且无底边线,背景由所在页面或容器承担。需要玻璃表面时显式设置 variant="default";该表面在 Android、旧 iOS 或减少透明度时使用主题 surface 实色。Web 保留 CSS 近似材质;无 CSS 模糊能力且未启用减少透明度时使用主题渐变。品牌态保持品牌色。
代码演示
用法
import {
ArrowLeftOutlined,
MenuOutlined,
MoreHOutlined,
} from '@unif/react-native-icons';
import { NavBar } from '@unif/react-native-design';
<NavBar
title="AI 助手"
subtitle="在线 · 已同步"
left={{
icon: MenuOutlined,
onPress: openDrawer,
accessibilityLabel: '打开抽屉',
}}
right={{
icon: MoreHOutlined,
onPress: openMenu,
accessibilityLabel: '打开更多菜单',
}}
/>;
{
/* 品牌橙底 */
}
<NavBar title="登录" variant="brand" />;
{
/* 透明浮层(深字)—— 浮在浅色 hero 渐变之上的子页 */
}
<NavBar
title="我的名片"
variant="transparent"
left={{
icon: ArrowLeftOutlined,
onPress: goBack,
accessibilityLabel: '返回',
}}
/>;
标准标题统一使用 type.h2(基础 17)与 fw.semi(600),并跟随 ThemeProvider 字号缩放。从旧版本升级后,需要保留玻璃背景的消费者应显式设置 variant="default"。
自定义整条内容
工作台问候、日期与操作组,或搜索输入与取消按钮,可直接作为 children。自定义模式不创建左右槽位、居中标题或空的标题读屏节点;已有控件的事件、ref、焦点和无障碍语义由原节点保留。children 与 title、subtitle、left、right 在类型上互斥。
import { useRef, useState } from 'react';
import { View } from 'react-native';
import { Button, NavBar, Search } from '@unif/react-native-design';
function SearchHeader({ onCancel }: { onCancel: () => void }) {
const [keyword, setKeyword] = useState('');
const input = useRef<React.ComponentRef<typeof Search>>(null);
return (
<NavBar style={{ height: 'auto', paddingVertical: 12, gap: 8 }}>
<View style={{ flex: 1, minWidth: 0 }}>
<Search
ref={input}
value={keyword}
onChangeText={setKeyword}
placeholder="搜索会话"
/>
</View>
<Button label="取消" variant="text" onPress={onCancel} />
</NavBar>
);
}
根容器保留横向布局与默认 44pt 高度;内容需要更高空间时使用 style={{ height: 'auto' }},并按实际场景设置间距。NavBar 不替业务决定输入聚焦、取消或返回行为;更换 variant 不重挂载自定义内容。
API
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
title | string | — | 标准模式必填的居中标题,与 children 互斥 |
subtitle | string? | — | 副标题(小字号,主标题下方) |
left | NavBarSlot | — | 左槽:严格 NavBarAction { icon, onPress, accessibilityLabel } 或展示用 ReactNode |
right | NavBarSlot | — | 右槽,同 left |
children | ReactNode(不含 undefined) | — | 自定义整条内容,与标准标题、副标题及左右槽位互斥;可传 null,不生成占位标题 |
variant | 'default' | 'brand' | 'transparent' | 'transparent' | transparent 无背景与边框;显式 default 为系统玻璃与 hairline;brand 为品牌橙底。标准模式文字跟随主题与变体,自定义内容自行选择文字样式 |
style | StyleProp<ViewStyle>? | — | 根容器附加样式(margin / position 等布局微调) |
testID | string? | — | E2E 定位 |
left/right传完整NavBarAction时渲染为内部IconButton(variant='ghost',icon 使用从 Icons 导入的ComponentType<IconProps>)。展示节点中的string/number/bigint(包括 Fragment、nested collection 与 thenable resolved value 内的 primitive)会递归包装为本地Text;非 Fragment element / portal 保持原有语义。thenable 映射按稳定源对象缓存,拒绝原因保持不变,非法 resolved value 失败关闭。缺字段、非法 icon 或 malformed node 会在 effect 中诊断并渲染为空。
安全区(Safe Area)
NavBar 不内置 top safe-area inset,由宿主页面负责。推荐做法:
import { SafeAreaView } from 'react-native-safe-area-context';
// 页面或自定义导航 header 中均由宿主包裹
<SafeAreaView edges={['top']}>
<NavBar title="首页" />
</SafeAreaView>;
这样 NavBar 本体可在任何场景复用(modal、底部抽屉 header、全屏画中画等不需要 top inset 的场景)。
无障碍(a11y)
来源:src/components/ui/NavBar/NavBar.tsx、isSlot.ts、types.ts。
- 主标题
title的<Text>使用accessibilityRole="header",可由屏幕阅读器按标题定位;根<View>不合并左右动作,subtitle保留普通文本语义。 - 自定义
children不附加标题或合并语义,调用方保留原控件的名称、角色、提示与焦点行为。 - a11y props:
left/right槽的NavBarAction.accessibilityLabel必填且非空;action 同时必须有函数onPress。若传展示用ReactNode,React element 自行负责 a11y,primitive 文本由库内本地Text自然朗读。 - 状态语义:NavBar 自身无可切换状态,不附加
accessibilityState。
import { ArrowLeftOutlined, MoreHOutlined } from '@unif/react-native-icons';
// action 的 icon、onPress、accessibilityLabel 都必填
<NavBar
title="登录"
left={{
icon: ArrowLeftOutlined,
onPress: goBack,
accessibilityLabel: '返回',
}}
right={{ icon: MoreHOutlined, onPress: openMenu, accessibilityLabel: '更多' }}
/>;
关联组件
- DrawerHeader ——
@react-navigation/drawer顶部的品牌面板 - TabBar —— 固定底部主导航