跳到主要内容

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 本体。

size · sm 28 / md 36 / lg 44
variant · neutral 中性 / primary 橙底 / ghost 透明
disabled · opacity 0.5 + 不响应
已触发 0 次

用法​

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​

参数类型默认值说明
iconComponentType<IconProps>—从 Icons 导入的图标组件
onPress() => void—必填点击回调;disabled / loading 时组件移除有效 handler
size('sm' | 'md' | 'lg')?'md'方形边长 28 / 36 / 44
iconSizenumber?随 size图标与加载指示的独立尺寸
surfaceSizenumber?随 size方形表面边长,并据此计算命中补偿
variant('primary' | 'secondary' | 'ghost' | 'neutral' | 'outline' | 'glass' | 'danger')?'glass'默认自动适配;实色与透明变体保留场景指定外观,排除 'text'
colorstring?variant fg图标与确认文字颜色;背景和边框仍由 variant 决定
confirmationIconButtonConfirmation?—按需启用原位确认;字段与作用域要求见原位确认
disabledboolean?false不响应 + opacity 0.5
loadingboolean?false以 ActivityIndicator 替代 icon,自动 disabled + busy
accessibilityLabelstring—必填且运行时必须非空 —— icon-only 按钮 SR 用户唯一信息源;空白值失败关闭并在 effect 诊断
accessibilityHintstring?—行为不显然时填(如"打开扫描器")
accessibilityStateOmit<AccessibilityState, 'disabled' | 'busy'>?—caller 可补充 selected / expanded 等状态;disabled / busy 由组件接管,类型上禁止覆盖
styleStyleProp<ViewStyle>?—容器附加样式
testIDstring?—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 / leftIcon prop