IconButton 图标按钮
默认自动适配系统材质,无需传玻璃参数或判断平台。Android、旧 iOS 或减少透明度时,默认图标按钮及确认状态统一采用轻中性主题 surfaceContainerHigh;原生 Liquid Glass 的透明度与材质保持系统呈现,Web 保留既有表面。
用于工具栏或紧凑操作区,默认单击执行。需要提供 accessibilityLabel。
需要二次确认时传 confirmation={{ label: '确认删除' }},并用 InlineConfirmScope 包住可取消区域;图标在原位平滑切换为确认文字。未传配置不增加确认步骤,详见原位确认。color 同时应用于图标和确认文字,删除操作可传错误色。
size 走 ButtonSize(sm/md/lg = 28/36/44)。variant 复用 Button palette,但
IconButton 精确排除会撕掉方形高度的 'text',默认是自动适配的 'glass'。
升级注意:此前省略 variant 时默认为透明底 ghost,现在默认自动适配材质。原场景需要继续保持透明时,显式传 variant="ghost" 或 variant="neutral";已经明确选择实色或透明变体的调用不受默认值调整影响。
浮动返回、删除或导航圆按钮直接使用默认值,可组合 surfaceSize={36}、iconSize={21}。默认胶囊圆角;保留至少 44pt 命中补偿、可访问名称、disabled 和 loading。
明确需要实色时使用 primary、danger 或 outline,它们不会因系统支持玻璃而变透明;嵌在已有导航/输入表面中的按钮可用 ghost 或 neutral 保持透明。color 只控制图标和确认文字,不能用它判断背景材质。自定义实色背景通过对应实色变体的 style.backgroundColor 设置。
secondary 与 glass 都使用共享系统玻璃,前者保留尺寸对应圆角,后者为圆形。支持 Liquid Glass 的 iOS 默认启用按压高光、缩放和回弹,图标与材质一起响应;原位确认沿用相同能力。禁用或加载时关闭交互并淡化前景,减少动态效果时保留普通前景按压反馈。Android、旧 iOS、Web 与减少透明度的材质回退保持原规则。
代码演示
下方渲染的就是 src/components/ui/IconButton/IconButton.tsx 本体。
用法
import { CloseOutlined, ScanOutlined } from '@unif/react-native-icons';
import { IconButton } from '@unif/react-native-design';
{
/* NavBar 右侧扫码按钮 */
}
<IconButton
icon={ScanOutlined}
size="md"
variant="neutral"
accessibilityLabel="扫码"
accessibilityHint="打开二维码扫描"
onPress={() => navigation.navigate('Scanner')}
/>;
{
/* 卡片右上关闭 */
}
<IconButton
icon={CloseOutlined}
size="sm"
variant="ghost"
accessibilityLabel="关闭"
onPress={onClose}
/>;
自定义不透明底色与图标色,各平台都保留传入的配色。两者可以使用任意有效颜色;仅传背景样式不会关闭玻璃,应同时选择实色变体:
<IconButton
icon={ScanOutlined}
variant="primary"
color={iconColor}
style={{ backgroundColor }}
accessibilityLabel="扫码"
onPress={onScan}
/>
API
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
icon | ComponentType<IconProps> | — | 从 Icons 导入的图标组件 |
onPress | () => void | — | 必填点击回调;disabled / loading 时组件移除有效 handler |
size | ('sm' | 'md' | 'lg')? | 'md' | 方形边长 28 / 36 / 44 |
iconSize | number? | 随 size | 图标与加载指示的独立尺寸 |
surfaceSize | number? | 随 size | 方形表面边长,并据此计算命中补偿 |
variant | ('primary' | 'secondary' | 'ghost' | 'neutral' | 'outline' | 'glass' | 'danger')? | 'glass' | 默认自动适配;实色与透明变体保留场景指定外观,排除 'text' |
color | string? | variant fg | 图标与确认文字颜色;背景和边框仍由 variant 决定 |
confirmation | IconButtonConfirmation? | — | 按需启用原位确认;字段与作用域要求见原位确认 |
disabled | boolean? | false | 不响应 + opacity 0.5 |
loading | boolean? | false | 以 ActivityIndicator 替代 icon,自动 disabled + busy |
accessibilityLabel | string | — | 必填且运行时必须非空 —— icon-only 按钮 SR 用户唯一信息源;空白值失败关闭并在 effect 诊断 |
accessibilityHint | string? | — | 行为不显然时填(如"打开扫描器") |
accessibilityState | Omit<AccessibilityState, 'disabled' | 'busy'>? | — | caller 可补充 selected / expanded 等状态;disabled / busy 由组件接管,类型上禁止覆盖 |
style | StyleProp<ViewStyle>? | — | 容器附加样式 |
testID | string? | — | E2E / 测试定位 |
iconSize 可独立设置图标和加载指示的尺寸;surfaceSize 可指定方形表面边长,同时按该值补足 44pt 命中区。缺省仍使用 size 对应的设备缩放尺寸。
import { ChevronLeftOutlined, CrosshairOutlined } from '@unif/react-native-icons';
<IconButton icon={ChevronLeftOutlined} surfaceSize={36} iconSize={21} style={{ borderRadius: 18 }} accessibilityLabel="返回" onPress={onBack} />
<IconButton icon={CrosshairOutlined} surfaceSize={36} iconSize={22} accessibilityLabel="定位" loading={locating} onPress={locate} />
无障碍(a11y)
来源:src/components/ui/IconButton/types.ts、IconButton.tsx、Button/ButtonBase.tsx。
- 默认
accessibilityRole:'button'(IconButton 透传给共享的ButtonBase,其accessibilityRole = 'button'为默认参数)。 - a11y props:
accessibilityLabel是 TS 强制必填,运行时还会 trim;空白值会移除 handler/action 语义并在 effect 诊断,不会形成 unnamed button。accessibilityHint可选,仅在「行为不显然」时补。 - 状态语义:disabled 或 loading 时自动上报
accessibilityState.disabled: true并移除有效 handler;loading 还上报busy: true。调用方不能覆盖这两个字段。
import { ScanOutlined } from '@unif/react-native-icons';
// label 必填(SR 唯一信息源);hint 仅在行为不显然时补
<IconButton icon={ScanOutlined} accessibilityLabel="扫码" accessibilityHint="打开二维码扫描" onPress={...} />
使用注意
- 不要把 icon 当装饰用 IconButton —— 装饰直接使用 Icons 组件即可,没 hit area 浪费
- 不要在 IconButton 内文字 + icon 混搭 —— 用 Button 的
rightIcon/leftIconprop