HeroUI Native 的动画基于 react-native-reanimated，手势由 react-native-gesture-handler 处理。若需更细粒度控制，建议先熟悉二者。

`animation` 属性

每个带动画的组件都暴露统一的 animation 属性，用于控制该组件上的全部动画：可调整数值、时间配置、布局动画，或完全关闭动画。

做法： 处理动画时，先查看目标组件是否提供 animation 属性。

修改动画

向 animation 传入对象即可定制。不同组件暴露的可调属性不同。若只想微调内置动画，可使用我们提供的各项配置；若要完全自定义动画逻辑，通常需要自行编写带动画的自定义组件。

示例 1：简单数值调整

调整缩放、透明度或颜色等数值：

import {Switch} from 'heroui-native';

<Switch
  animation={{
    scale: {
      value: [1, 0.9], // [unpressed, pressed]
    },
    backgroundColor: {
      value: ['#172554', '#eab308'], // [unselected, selected]
    },
  }}>
  <Switch.Thumb />
</Switch>;

示例 2：时间曲线配置

自定义时长与缓动：

import {Accordion} from 'heroui-native';

<Accordion>
  <Accordion.Item value="1">
    <Accordion.Trigger>
      <Accordion.Indicator
        animation={{
          rotation: {
            value: [0, -180],
            springConfig: {
              damping: 60,
              stiffness: 900,
              mass: 3,
            },
          },
        }}
      />
    </Accordion.Trigger>
  </Accordion.Item>
</Accordion>;

示例 3：布局动画（进入 / 退出）

使用 Reanimated 的布局动画 API：

import {Accordion} from 'heroui-native';
import {FadeInRight, FadeInLeft, ZoomIn} from 'react-native-reanimated';
import {Easing} from 'react-native-reanimated';

<Accordion>
  <Accordion.Item value="1">
    <Accordion.Content
      animation={{
        entering: {
          value: FadeInRight.delay(50).easing(Easing.inOut(Easing.ease)),
        },
      }}>
      Content here
    </Accordion.Content>
  </Accordion.Item>
</Accordion>;

示例 4：使用 `state` 精细控制

state 可在关闭动画的同时仍保留属性配置，便于微调而不真正播放动画：

import {Switch} from 'heroui-native';

<Switch
  animation={{
    state: 'disabled', // Disable animations but allow property customization
    scale: {
      value: 0.95, // This value is still respected even though animations are disabled
    },
    backgroundColor: {
      value: ['#172554', '#eab308'],
    },
  }}>
  <Switch.Thumb />
</Switch>

state 可取：

'disabled'：关闭动画，但仍可配置属性值
'disable-all'：关闭自身及子级全部动画（仅在根级可用）
boolean：简单开关（true 启用，false 禁用）

这样既能精细控制动画行为，又能在不启用动画的情况下自定义属性值。

关闭动画

可通过 animation 在不同层级关闭动画。

关闭选项

animation={false} 或 animation="disabled"：仅关闭当前组件动画
animation="disable-all"：关闭根级及其子级全部动画（仅根级可用）
animation={true} 或 animation={undefined}：使用默认动画

组件级关闭

仅关闭某个子部件的动画：

<Switch>
  <Switch.Thumb animation={false} />
</Switch>

根级 `disable-all`

"disable-all" 仅在复合组件根级可用，会向下级联，包括树中的独立组件（如 Button、Spinner 等），不仅限于复合子部件：

// Disables all animations including Button components inside Card
<Card animation="disable-all">
  <Card.Body>
    <Card.Title>$450</Card.Title>
    <Card.Description>Living room Sofa</Card.Description>
  </Card.Body>
  <Card.Footer className="gap-3">
    <Button variant="primary">Buy now</Button>
    <Button variant="ghost">Add to cart</Button>
  </Card.Footer>
</Card>

注意： "disable-all" 会级联到所有子组件，包括独立的 Button、Spinner 等。

全局动画配置

在 HeroUINativeProvider 上统一关闭应用内全部 HeroUI Native 动画：

import {HeroUINativeProvider} from 'heroui-native';

<HeroUINativeProvider
  config={{
    animation: 'disable-all',
  }}>
  <App />
</HeroUINativeProvider>;

这会覆盖各组件自身的 animation 设置，全局禁用动画。

无障碍

系统「减少动态效果」会在底层自动处理：当用户开启该无障碍选项时，库会通过 GlobalAnimationSettingsProvider 与 Reanimated 的 useReducedMotion() 全局关闭动画。

你通常无需额外编码，库会尊重系统无障碍偏好。

动画状态管理

内部会统一管理禁用态，避免关闭动画后出现卡顿或跳变：禁用时组件会直接落到终态，而不是播放到一半。

子级渲染函数

许多组件支持将 children 设为函数，便于根据 isSelected 等状态渲染：

import {Switch} from 'heroui-native';

<Switch
  isSelected={isSelected}
  onSelectedChange={setIsSelected}>
  {({isSelected, isDisabled}) => (
    <Switch.Thumb>{isSelected ? <CheckIcon /> : <XIcon />}</Switch.Thumb>
  )}
</Switch>;

该模式便于根据选中、禁用等状态构建动态界面。

动画