# 过渡动画

- 页面: https://jiguang132.com/zh/resources/mantine/docs/transition
- 资源: Mantine Core (https://jiguang132.com/zh/resources/mantine.md)
- 全部指南: https://jiguang132.com/zh/resources/mantine/docs.md

Mantine Core 的独立组件，请不要替换为 JGuang UI/Base UI 的同名 API。

## 安装

```bash
npm install @mantine/core@9.7.1 @mantine/hooks@9.7.1
```

入口引入 `@mantine/core/styles.css`，并在根组件使用 `MantineProvider`；通过 `forceColorScheme` 同步深浅色主题。

## 使用与验证

在左侧选择组件，在预览中操作它的状态；使用“查看代码”检查真实源码。安装后执行类型检查和构建，再验证键盘焦点、手机布局与深浅色主题。

## 来源

https://github.com/mantinedev/mantine/tree/f0e2bc6d28b0f0b8aaefb5b859937bf77f539df7
MIT 许可证；不包括付费内容。下方提供上游英文参考内容，中文使用指南已适配；上游详细参考暂保留英文。

---


## 版本与兼容性

固定的 Mantine Core 9.7.1 要求 React 和 React DOM 满足 `^19.2.0`，并配套 `@mantine/hooks@9.7.1`。此条件来自实际 npm 包的 peerDependencies。React 18 或其他不兼容版本不能强行安装；先向项目负责人说明升级影响并确认方案，不使用 --force/--legacy-peer-deps 掩盖冲突。入口的原生 Provider 开启 `theme.respectReducedMotion`，并用 `forceColorScheme` 控制深浅色。

## 适用场景

为挂载内容应用过渡样式。

## 本地示例使用的原生参数

以下参数由本地、经过类型检查的 JSX 示例提取，按所属组件区分。不是全部属性清单；完整签名和继承关系见下方固定源码参考。

| 组件参数 | 说明 |
| --- | --- |
| `Button.onClick` | 本地点击处理，应按需替换为明确的业务操作。 |
| `Transition.mounted` | 过渡内容是否应该存在。 |
| `Transition.transition` | 原生过渡名称或配置。 |

## 交互与状态检查

当前场景：默认。切换支持的禁用、错误或只读场景后检查真实行为；无此原生状态的组件不会被强行添加统一属性。验证键盘焦点和退出方式，修改值后按原生回调签名连接业务状态。

## 业务接入边界

将渲染函数提供的 style 应用到动画元素。mounted 决定内容存在与否，过渡不会执行业务逻辑。

## 宿主配置

先安装固定版本 @mantine/core 和 @mantine/hooks，在入口引入 @mantine/core/styles.css，并使用 MantineProvider。示例的 theme 和 variant 是 JGuang 编写的宿主参数，不是所有原生组件都接受的统一 API；通过 forceColorScheme 同步应用主题。源码面板中的原生实现仅供阅读，使用 npm 导出，不要单独复制内部实现。此批只覆盖 Core，不包括日期、图表和表单扩展包。上游详细说明保留英文，不宣称全文中文化。


## 可运行用法

以下代码使用资源原生 API；不是把其他设计系统的同名组件替换进来。

```tsx
import { useState } from 'react';
import * as M from '@mantine/core';
import '@mantine/core/styles.css';


function ComponentPreview({ variant = 'Default' }: { variant?: string }) {
const [open, setOpen] = useState(false);
const content = <M.Text>Build something beautiful / 构建美好的界面</M.Text>;
return <div><M.Button onClick={() => setOpen(!open)}>Toggle transition</M.Button><M.Transition mounted={open} transition="fade">{(styles) => <div style={styles}>{content}</div>}</M.Transition></div>;
}
export default function Example({ variant = 'Default', theme = 'light' }: { variant?: string; theme?: 'light' | 'dark' }) {
return <M.MantineProvider forceColorScheme={theme} theme={{ respectReducedMotion: true }}><ComponentPreview variant={variant} /></M.MantineProvider>;
}

```


## 可用状态与示例

默认

示例遵循 Mantine 原生 API。支持多状态的输入组件可将示例中的 variant 改为 Disabled、Invalid 或 Read only；这些只是示例标签，不是新增的组件属性。改造时保留组件要求的数据、受控值、store 和复合子组件结构。


## Usage

The Transition component is designed to animate the presence of elements with
fixed or absolute positioning, such as dropdowns, modals, or tooltips. Other Mantine
components (like [Modal](/core/modal) and [Tooltip](/core/tooltip)) use Transition internally
for their animations.

Note that the Transition component is not intended to be a comprehensive solution for all
animations. It is a simple utility for animating the presence of elements
with fixed or absolute positioning. If you need to implement more complex animations,
consider using [Motion](https://motion.dev/), [React Spring](https://www.react-spring.dev/),
or other dedicated animation libraries.

Example usage of the Transition component:

```tsx
import { Transition } from '@mantine/core';

function Demo({ opened }: { opened: boolean }) {
  return (
    <Transition mounted={opened} transition="fade">
      {(styles) => <div style={styles}>Your modal</div>}
    </Transition>
  );
}
```

## Premade transitions

Mantine includes several premade transitions:



To use one of them, set the `transition` property to one of these values:

```tsx
import { Transition } from '@mantine/core';

function Demo({ opened }: { opened: boolean }) {
  return (
    <Transition
      mounted={opened}
      transition="fade"
      duration={400}
      timingFunction="ease"
    >
      {(styles) => <div style={styles}>Your modal</div>}
    </Transition>
  );
}
```

## Custom transitions

You can create your own transition. `transition` is an object with 4 properties:

- `in` – styles for mounted state
- `out` – styles for unmounted state
- `common` (optional) – styles for both mounted and unmounted states
- `transitionProperty` – properties which participate in the transition



## Enter and exit delay

Use the `enterDelay` and `exitDelay` props to delay the transition start. Values are in milliseconds:



## Reduced motion

Transition respects the `prefers-reduced-motion` media query and your theme's
`respectReducedMotion` setting. When reduced motion is preferred, all
transitions complete instantly:

```tsx
import { createTheme, MantineProvider, Transition } from '@mantine/core';

const theme = createTheme({
  respectReducedMotion: true, // default
});

function Demo() {
  return (
    <MantineProvider theme={theme}>
      <Transition mounted transition="fade" duration={400}>
        {(styles) => <div style={styles}>Content</div>}
      </Transition>
    </MantineProvider>
  );
}
```

This improves accessibility for users with vestibular disorders who may
experience motion sickness from animations.

## Lifecycle callbacks

Use lifecycle callbacks to perform actions at different stages of the transition:

- `onEnter` - Called when enter transition starts
- `onEntered` - Called when enter transition completes
- `onExit` - Called when exit transition starts
- `onExited` - Called when exit transition completes

```tsx
import { Transition } from '@mantine/core';

function Demo() {
  return (
    <Transition
      mounted
      transition="fade"
      duration={200}
      onEnter={() => console.log('Enter started')}
      onEntered={() => console.log('Enter completed')}
      onExit={() => console.log('Exit started')}
      onExited={() => console.log('Exit completed')}
    >
      {(styles) => <div style={styles}>Content</div>}
    </Transition>
  );
}
```

## Keep mounted

By default, the element is unmounted from the DOM when the transition is
complete. Use `keepMounted` to keep the element mounted with `display: none`:

```tsx
import { Transition } from '@mantine/core';

function Demo() {
  return (
    <Transition mounted={false} keepMounted transition="fade">
      {(styles) => <div style={styles}>Content</div>}
    </Transition>
  );
}
```

This is useful when you want to:
- Preserve element state during hide/show
- Avoid remounting overhead
- Maintain focus/scroll position


## 源码参数参考

以下实现签名和类型从本地固定版本源码生成。保留可选属性、原生继承类型、联合分支和 never 限制；不会将其他设计系统的 API 混入。forwardRef 实现中的 ref 属于 React 引用，不是新增业务属性。此区域是原始类型参考，不是上游说明的全文翻译。


```ts
Transition({
  keepMounted,
  keepMountedMode = 'activity',
  transition = 'fade',
  duration = 250,
  exitDuration = duration,
  mounted,
  children,
  timingFunction = 'ease',
  onExit,
  onEntered,
  onEnter,
  onExited,
  enterDelay,
  exitDelay,
}: TransitionProps)
```



```ts
export interface TransitionProps {
  /** If set, the element is kept in the DOM when hidden. React 19 `Activity` is used to preserve state while the element is not visible. */
  keepMounted?: boolean;

  /**
   * Controls how the element is hidden when `keepMounted` is set:
   * `'activity'` - hidden with React 19 `Activity` component,
   * `'display-none'` - hidden with `display: none` styles
   * @default 'activity'
   */
  keepMountedMode?: 'activity' | 'display-none';

  /** Transition name or object */
  transition?: MantineTransition;

  /** Transition duration in ms @default 250 */
  duration?: number;

  /** Exit transition duration in ms @default 250 */
  exitDuration?: number;

  /** Transition timing function @default theme.transitionTimingFunction */
  timingFunction?: string;

  /** Determines whether component should be mounted to the DOM */
  mounted: boolean;

  /** Render function with transition styles argument */
  children: (styles: React.CSSProperties) => React.JSX.Element;

  /** Called when exit transition ends */
  onExited?: () => void;

  /** Called when exit transition starts */
  onExit?: () => void;

  /** Called when enter transition starts */
  onEnter?: () => void;

  /** Called when enter transition ends */
  onEntered?: () => void;

  /** Delay in ms before enter transition starts */
  enterDelay?: number;

  /** Delay in ms before exit transition starts */
  exitDelay?: number;
}
```


### 源码中的解构默认值

只列出直接写在参数或 props 解构中的默认表达式。条件表达式、运行时主题和其他计算值请结合源码；这里不是全部行为的默认值清单。


```ts
// Transition
keepMountedMode = 'activity'

// Transition
transition = 'fade'

// Transition
duration = 250

// Transition
exitDuration = duration

// Transition
timingFunction = 'ease'
```


### 原生与外部类型

以下外部类型仍由 React 或资源自身依赖定义，没有手工展开为虚构属性。实际可用类型以安装版本的 TypeScript 检查为准。


```ts
MantineTransition
React.CSSProperties
React.JSX.Element
```

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt