@ capgo/ 电容过渡

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

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

演示

特征

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

兼容性

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

安装

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

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

然后使用下列提示:

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

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

npm install @capgo/capacitor-transitions

快速启动

香草 JavaScript / Web 组件

<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>

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');

反应

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',添加项目申报文件:

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

然后确保 TypeScript 包含:

{
  "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数字 :

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

阴道

<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>

丝绒

<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>

固态

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>
  );
}

角质

// 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的页面内容 在原生铬下.

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

首先配置原生铬 :

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

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

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

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

<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>

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

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

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>

页面转换容器.

方法:

• 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"。 。 。 .

<cap-footer>

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

过渡方向

导航动作

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

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

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

帮助函数

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

// 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');

过渡管理员

高级方案控制:

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 风格的页面转换带有平滑动画:

主页

细节 页次

粘贴页

特征显示:

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

要运行反应示例 :

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号节点或更新.

将演示复制到本地项目:

npm install
npm run build:mobile
npx cap sync

要在当地运行它:

npx cap run ios
npx cap run android

要部署一个OTA捆绑到Capgo:

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

许可证

麻省理工学院