# @capgo/capacitor-transitions 中文文档

规范地址：https://npmcn.com/package/%40capgo/capacitor-transitions/

版本：8\.3\.9
npm 元数据更新时间：2026-11-09T07:02:31.972Z
中文译文更新时间：2026-11-09T02:54:52.376Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-transitions
原文对照：https://npmcn.com/package/%40capgo/capacitor-transitions/?lang=original
项目主页：https://capgo.app/docs/plugins/transitions/
源码仓库：https://github.com/Cap-go/capacitor-transitions

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.4 MB，37 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：vue \>=3\.0\.0，react \>=18\.0\.0，svelte \>=4\.0\.0，solid-js \>=1\.0\.0，react-dom \>=18\.0\.0，@angular/core \>=17\.0\.0
- 首次发布：2026-05-10T19:18:10.618Z
- 最新版本发布：2026-11-09T07:02:31.590Z
- 近 30 天下载量：66477（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 31 个）

## 中文简介

Capacitor apps 的框架不可知页面转换 - iOS 风格的没有意见的导航

## 安装

```sh
npm install @capgo/capacitor-transitions
```

也可以使用：`pnpm add @capgo/capacitor-transitions`、`yarn add @capgo/capacitor-transitions`、`bun add @capgo/capacitor-transitions`

## README

# @ capgo/ 电容过渡

[![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-transitions)](https://capgo.app/?ref=plugin_transitions)

**队长**:在几分钟内向您的Capacitor用户推进修正,在没有Mac的情况下构建签名的iOS和Android应用程序,以及 卷回一击.

## [\*免费开始\*](https://capgo.app/register/?ref=plugin_transitions)

14天无限自由审判. 不需要信用卡

> 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_transitions) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/capacitor-transitions` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _加上@capgo/电容-过渡到我的电容软件上_ [代理设置指南](https://capgo.app/agents/?ref=plugin_transitions) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_transitions)

Capacitor apps的架构-不可知页面转换. iOS-style discovery without opinions.

## 演示

![Demo of capacitor-transitions in action](https://npmcn.com/package/%40capgo/capacitor-transitions/docs/demo.webp)

## 特征

-   **框架不可知论** - 与React、Vue、Angular、Svelte、Solid和任何其他框架合作
-   **iOS & Android 动画** - 将平台适当转换出方框
-   **网络动画 API** - 平滑的GPU加速动画
-   **查看过渡 API** - 支持浏览器的可选渐进增强
-   **无设计意见** - 只是过渡逻辑,你带来自己的风格
-   **协调过渡** - 标题、内容和页脚合在一起
-   **页面缓存** - 将页面保留在DOM中,以便立即回向导航
-   **音效风格 iOS 刷回** - 与Capacitor本地iOS自动启用的可选边缘手势
-   **生命周期钩** - 将进入,将进入, 将离开,将离开事件

## 兼容性

此插件与他最新版本上的所有电容器版本兼容

## 安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```

然后使用下列提示:

```text
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-transitions` plugin in my project.
```

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
npm install @capgo/capacitor-transitions
```

## 快速启动

### 香草 JavaScript / Web 组件

```html
<cap-router-outlet platform="auto">
  <cap-page>
    <cap-header slot="header">
      <h1>My Page</h1>
    </cap-header>
    <cap-content slot="content">
      <p>Page content here</p>
    </cap-content>
    <cap-footer slot="footer">
      <nav>Tab bar</nav>
    </cap-footer>
  </cap-page>
</cap-router-outlet>
```

```javascript
import '@capgo/capacitor-transitions';

// Navigate programmatically
const outlet = document.querySelector('cap-router-outlet');
outlet.push(newPageElement);
outlet.pop();
outlet.setRoot(newRootElement);
outlet.setRoot(onboardingDoneElement, { direction: 'forward' });

// For router-driven replace/reset flows, reset the stack but keep a forward slide.
outlet.setNavigation('root', 'forward');
yourRouter.replace('/home');
```

### 反应

```tsx
import { useRef, useEffect } from 'react';
import { useNavigate } from 'react-router-dom';
import {
  initTransitions,
  setDirection,
  setNavigation,
  setupPage,
  setupRouterOutlet,
} from '@capgo/capacitor-transitions/react';
import '@capgo/capacitor-transitions';

// Initialize once at app startup
initTransitions({ platform: 'auto' });

function App() {
  const outletRef = useRef<HTMLElement>(null);

  useEffect(() => {
    if (outletRef.current) {
      setupRouterOutlet(outletRef.current, { platform: 'auto', swipeGesture: 'auto' });
    }
  }, []);

  return (
    <cap-router-outlet ref={outletRef}>
      <Routes>
        <Route path="/" element={<HomePage />} />
        <Route path="/details/:id" element={<DetailsPage />} />
      </Routes>
    </cap-router-outlet>
  );
}

function HomePage() {
  const navigate = useNavigate();
  const pageRef = useRef<HTMLElement>(null);

  useEffect(() => {
    if (pageRef.current) {
      return setupPage(pageRef.current, {
        onDidEnter: () => console.log('entered'),
      });
    }
  }, []);

  const goToDetails = (id: number) => {
    setDirection('forward');
    navigate(`/details/${id}`);
  };

  const finishOnboarding = () => {
    setNavigation('root', 'forward');
    navigate('/home', { replace: true });
  };

  return (
    <cap-page ref={pageRef}>
      <cap-header slot="header">
        <h1>Home</h1>
      </cap-header>
      <cap-content slot="content">
        <button onClick={() => goToDetails(1)}>Go to Details</button>
      </cap-content>
      <cap-footer slot="footer">
        <nav>Tab bar</nav>
      </cap-footer>
    </cap-page>
  );
}
```

#### 反应 JSX TypeScript 设置

从 `@capgo/capacitor-transitions/react` 登记网络组件,并包括: `cap-router-outlet`, (中文(简体) ), `cap-page`, (中文(简体) ), `cap-header`, (中文(简体) ), `cap-content`,以及 `cap-footer`。在大多数反应项目中,上述示例中的导入就够了.

如果类型脚本仍然显示 `Property 'cap-router-outlet' does not exist on type 'JSX.IntrinsicElements'`,添加项目申报文件:

```ts
// src/capgo-transitions.d.ts
import '@capgo/capacitor-transitions/react';
```

然后确保 TypeScript 包含:

```json
{
  "include": ["src", "src/capgo-transitions.d.ts"]
}
```

对于Vite, 创建 React App, 以及大多数 Webpack React App, 设置 `capgo-transitions.d.ts` 内部 `src/` 够了。 下个J,放进去 `src/` 或工程根并保留在 `tsconfig.json`。对于自定义的 TypeScript 或 Web package 设置, 单独设置 `types/` 文件夹,将文件夹添加到 `tsconfig.json`数字 :

```json
{
  "include": ["src", "types"]
}
```

### 阴道

```vue
<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
import { useRouter } from 'vue-router';
import { initTransitions, setDirection, setupPage, setupRouterOutlet } from '@capgo/capacitor-transitions/vue';
import '@capgo/capacitor-transitions';

// Initialize once
initTransitions({ platform: 'auto' });

const router = useRouter();
const outletRef = ref(null);
const pageRef = ref(null);
let cleanup;

onMounted(() => {
  if (outletRef.value) {
    setupRouterOutlet(outletRef.value, { platform: 'auto' });
  }
  if (pageRef.value) {
    cleanup = setupPage(pageRef.value, {
      onDidEnter: () => console.log('entered'),
    });
  }
});

onUnmounted(() => cleanup?.());

const goToDetails = (id) => {
  setDirection('forward');
  router.push(`/details/${id}`);
};
</script>

<template>
  <cap-router-outlet ref="outletRef">
    <cap-page ref="pageRef">
      <cap-header slot="header">
        <h1>Home</h1>
      </cap-header>
      <cap-content slot="content">
        <button @click="goToDetails(1)">Go to Details</button>
      </cap-content>
    </cap-page>
  </cap-router-outlet>
</template>
```

### 丝绒

```svelte
<script>
  import { routerOutlet, page, setDirection } from '@capgo/capacitor-transitions/svelte'
  import '@capgo/capacitor-transitions'

  function navigate(to, direction = 'forward') {
    setDirection(direction)
    // Use your router's navigate function
  }
</script>

<cap-router-outlet use:routerOutlet>
  <cap-page use:page={{ onDidEnter: () => console.log('entered') }}>
    <cap-header slot="header">
      <h1>Home</h1>
    </cap-header>
    <cap-content slot="content">
      <button on:click={() => navigate('/details/1')}>Go to Details</button>
    </cap-content>
  </cap-page>
</cap-router-outlet>
```

### 固态

```tsx
import { onMount, onCleanup } from 'solid-js';
import { useNavigate } from '@solidjs/router';
import { initTransitions, setDirection, setupPage, setupRouterOutlet } from '@capgo/capacitor-transitions/solid';
import '@capgo/capacitor-transitions';

// Initialize once
initTransitions({ platform: 'auto' });

function HomePage() {
  const navigate = useNavigate();
  let pageRef;

  onMount(() => {
    if (pageRef) {
      const cleanup = setupPage(pageRef, {
        onDidEnter: () => console.log('entered'),
      });
      onCleanup(cleanup);
    }
  });

  const goToDetails = (id) => {
    setDirection('forward');
    navigate(`/details/${id}`);
  };

  return (
    <cap-page ref={pageRef}>
      <cap-header slot="header">
        <h1>Home</h1>
      </cap-header>
      <cap-content slot="content">
        <button onClick={() => goToDetails(1)}>Go to Details</button>
      </cap-content>
    </cap-page>
  );
}
```

### 角质

```typescript
// app.component.ts
import { Component, CUSTOM_ELEMENTS_SCHEMA, ElementRef, ViewChild, AfterViewInit } from '@angular/core';
import '@capgo/capacitor-transitions';

@Component({
  selector: 'app-root',
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <cap-router-outlet #outlet platform="auto">
      <router-outlet></router-outlet>
    </cap-router-outlet>
  `,
})
export class AppComponent {}

// home.component.ts
@Component({
  selector: 'app-home',
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <cap-page>
      <cap-header slot="header">
        <h1>Home</h1>
      </cap-header>
      <cap-content slot="content">
        <button (click)="goToDetails(1)">Go to Details</button>
      </cap-content>
    </cap-page>
  `,
})
export class HomeComponent {
  constructor(private router: Router) {}

  goToDetails(id: number) {
    this.router.navigate(['/details', id]);
  }
}
```

## 用 @ capgo/ native- 导航

使用 `@capgo/native-navigation` 当本地图层拥有导航栏或标签栏时,并使用 `@capgo/capacitor-transitions` 在WebView的页面内容 在原生铬下.

```bash
npm install @capgo/capacitor-transitions @capgo/native-navigation
npx cap sync
```

首先配置原生铬 :

```typescript
import { NativeNavigation } from '@capgo/native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
});

await NativeNavigation.setNavbar({
  title: 'Inbox',
  backButton: { visible: false },
});
```

将过渡输出集中在页面上, 而不是本地栏 :

```html
<cap-router-outlet platform="auto" swipe-gesture="auto">
  <cap-page>
    <cap-content slot="content" fullscreen>
      <main class="native-page">Inbox content</main>
    </cap-content>
  </cap-page>
</cap-router-outlet>
```

```css
.native-page {
  padding-top: var(--cap-native-navigation-top);
  padding-bottom: var(--cap-native-navigation-bottom);
}
```

从相同的路由器动作驱动两个软件包 :

```typescript
import { NativeNavigation } from '@capgo/native-navigation';
import { setDirection, setNavigation } from '@capgo/capacitor-transitions/react';
import { router } from './router';

await NativeNavigation.addListener('navbarBack', () => {
  setDirection('back');
  router.back();
});

async function openMessage(id: string) {
  setDirection('forward');
  router.push(`/message/${id}`);

  await NativeNavigation.setNavbar({
    title: 'Message',
    backButton: { visible: true, title: 'Inbox' },
  });
}

async function finishOnboarding() {
  setNavigation('root', 'forward');
  router.replace('/inbox');

  await NativeNavigation.setNavbar({
    title: 'Inbox',
    backButton: { visible: false },
  });
}
```

不要让本地的上巴再次移动 `<cap-header>`。原生导航保持条形原生;这个软件包可以动画网页正文.

## API 参考

### 构成部分

#### `<cap-router-outlet>`

页面转换容器.

| 属性 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `platform` | `'ios' | 'android' | 'auto'` | `'auto'` | 动画风格 |
| `duration` | `number` | 平台默认 | 动画持续时间( ms) |
| `keep-in-dom` | `boolean` | `true` | 导航后在 DOM 中保留页面 |
| `max-cached` | `number` | `10` | 保存缓存的最大页面 |
| `swipe-gesture` | `boolean | 'auto'` | `'auto'` | 启用边缘刷回手势 . `'auto'` 仅在本地的 iOS Capacitor apps 中启用 |

方法:

-   `push(element, config?)` - 导航到新页面
-   `pop(config?)` - 导航回来
-   `setRoot(element, config?)` - 替换导航堆栈。 过 `{ direction: 'forward' }` 用前向幻灯片重置堆栈.
-   `setNavigation(action, direction?)` - 为下一个路由器驱动的导航设置堆栈动作和动画方向
-   `setSwipeGesture(true | false | 'auto')` - 启用、禁用或自动检测边缘刷回手势

`swipe-gesture="auto"` 使用 Capacitor 的运行时间助手( )`Capacitor.isNativePlatform()` 财务报告和审定财务报表 `Capacitor.getPlatform()`)并只允许本地iOS应用程序的手势. 使用 `swipe-gesture="true"` 强迫它上任何平台或 `swipe-gesture="false"` 来禁用它.

#### `<cap-page>`

带有页眉/内容/页脚槽的页面容器.

活动 :

-   `cap-will-enter` - 在页面可见之前
-   `cap-did-enter` - 在页面可见后
-   `cap-will-leave` - 在离开前
-   `cap-did-leave` - 在页后离开

#### `<cap-header>`

信头容器。 使用方式 `slot="header"` 内部 `<cap-page>`。 。 。 .

#### `<cap-content>`

主要可滚动内容区域. 使用方式 `slot="content"`。 。 。 .

| 属性 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `fullscreen` | `boolean` | `false` | 内容滚动到标题后 |
| `scroll-x` | `boolean` | `true` | 启用水平滚动 |
| `scroll-y` | `boolean` | `true` | 启用垂直滚动 |

#### `<cap-footer>`

脚印容器。 使用方式 `slot="footer"`。 。 。 .

### 过渡方向

| 方向 | 说明 |
| --- | --- |
| `'forward'` | 推动动画( iOS: 从右侧滑出) |
| `'back'` | 流行动画( iOS: 幻灯片向右) |
| `'root'` | 替换动画( 淡出) |
| `'none'` | 没有动画 |

### 导航动作

导航动作独立于视觉动画控制所记录的堆栈. 当路由器出现时, 这会有用 `replace` 或本地导航重置应感觉像前行页面推取,但不得留下刷回条目.

```typescript
setNavigation('root', 'forward');
router.replace('/home');
```

`setNavigation('root', 'forward')` 清除导航后的过渡堆栈并播放前方动画。 刷新背面因没有前页而禁用 .

### 帮助函数

所有框架绑定导出这些帮助函数 :

```typescript
// Initialize the transition system
initTransitions({ platform: 'auto' });

// Set the direction for the next navigation
setDirection('forward' | 'back' | 'root' | 'none');

// Set the stack action and animation direction for the next navigation
setNavigation('root', 'forward');
setNavigation('root'); // direction is optional and defaults to the same value as the stack action.

// Set up a router outlet element
setupRouterOutlet(element, options);

// Auto-enable the iOS edge swipe-back gesture in native Capacitor iOS apps
setupRouterOutlet(element, { swipeGesture: 'auto' });

// Force enable or disable from JavaScript
setupRouterOutlet(element, { swipeGesture: true });
setupRouterOutlet(element, { swipeGesture: false });

// Set up a page element with lifecycle callbacks (returns cleanup function)
setupPage(element, { onWillEnter, onDidEnter, onWillLeave, onDidLeave });

// Create a transition-aware navigate function
const transitionNavigate = createTransitionNavigate(navigate);
transitionNavigate('/path', 'forward');
```

### 过渡管理员

高级方案控制:

```typescript
import { createTransitionController } from '@capgo/capacitor-transitions';

const controller = createTransitionController({
  platform: 'auto',
  duration: 400,
  useViewTransitions: true,
});

// Navigate
await controller.push(element, { direction: 'forward' });
await controller.pop({ direction: 'back' });
await controller.setRoot(element, { direction: 'root' });
await controller.setRoot(element, { direction: 'forward' });

// Lifecycle hooks
controller.registerLifecycle('page-id', {
  onWillEnter: (event) => console.log('Will enter', event),
  onDidEnter: (event) => console.log('Did enter', event),
  onWillLeave: (event) => console.log('Will leave', event),
  onDidLeave: (event) => console.log('Did leave', event),
});
```

## 浏览器支持

-   有 Web 动画 API 支持的现代浏览器
-   可选视图过渡 API (Chrome 111+, Edge 111+, Safari 18+) 支持
-   旧浏览器的优雅回落

## 设计哲学

这个图书馆有意对造型无动于衷:

1.  **最小结构CSS** - 你带了自己的视觉系统
2.  **无设计系统** - 任何UI库或自定义风格的作品
3.  **只是过渡** - 注重平滑的页面导航
4.  **框架不可知论** - 使用React、Vue、Angular、Svelte、Solid或vanilla JS

目标是在没有Ionic的设计系统或框架锁定的情况下提供Ionic质量的页面转换.

## 实例

见 `/examples` 完整示例目录 :

-   `react-app` - 用回放路由器反应
-   `vue-app` - Vue 3带Vue路由器
-   `angular-app` - 有角路由器的角
-   `svelte-app` - 斯维尔特5号
-   `solid-app` - 固态路由器
-   `tanstack-app` - 与 TanStack 路由器反应

### 反应示例

React 示例显示 iOS 风格的页面转换带有平滑动画:

![React transition demo](https://npmcn.com/package/%40capgo/capacitor-transitions/docs/react-transition-demo.webp)

<table><tbody><tr><td align="center"><img alt="React Home Page" src="https://github.com/user-attachments/assets/c06a6c5a-c318-44ab-a57c-992ba9cfacd4" width="300" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br><strong>主页</strong></td><td align="center"><img alt="React Details Page" src="https://github.com/user-attachments/assets/6fd808da-6352-4660-8c79-e32184332df8" width="300" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br><strong>细节 页次</strong></td><td align="center"><img alt="React Nested Page" src="https://github.com/user-attachments/assets/8516dcf0-4189-40d9-a400-154b73c0135e" width="300" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br><strong>粘贴页</strong></td></tr></tbody></table>

特征显示:

-   使用滑入动画的前进导航
-   以滑出动画后导航
-   多级别页面堆栈
-   坐标头/内容/脚步过渡

要运行反应示例 :

```bash
cd examples/react-app
npm install
npm run dev
```

### 移动Demo App

该寄存器还包括一个Capacitor shell,用于在真实设备上测试回声演示并经过Capgo. 它使用应用代号 `app.capgo.capacitor.transitions`,应用程序名称 `Capgo Transitions`,以及 `examples/react-app/dist` 作为本地网络捆绑.

CLI控制器需要22号节点或更新.

将演示复制到本地项目:

```bash
npm install
npm run build:mobile
npx cap sync
```

要在当地运行它:

```bash
npx cap run ios
npx cap run android
```

要部署一个OTA捆绑到Capgo:

```bash
npm run build:mobile
npx @capgo/cli@latest bundle upload app.capgo.capacitor.transitions --channel dev --delta
```

## 许可证

麻省理工学院

## 常见问题

### @capgo/capacitor-transitions 是什么？

Capacitor apps 的框架不可知页面转换 - iOS 风格的没有意见的导航

### 如何安装 @capgo/capacitor-transitions？

在项目目录运行 npm install @capgo/capacitor-transitions，或使用 pnpm add / yarn add / bun add。

### @capgo/capacitor-transitions 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capgo/capacitor-transitions 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capgo/capacitor-transitions 可以商用吗？

@capgo/capacitor-transitions 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @capgo/capacitor-transitions 的下载量有多少？

根据 npm 官方下载统计，@capgo/capacitor-transitions 在 2026/10/09 – 2026/11/07 这 30 天内被下载 66,477 次，日均约 2,216 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capgo/capacitor-transitions 还在维护吗？

最新版本 8\.3\.9 发布于 2026/11/09（今天）；至今共发布 31 个版本，其中过去 12 个月发布了 31 个；首次发布于 2026/05/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。