react-flip-toolkit

与其他 React FLIP 库的比较

快速开始

npm install react-flip-toolkit 或 yarn add react-flip-toolkit

1. 用单个 Flipper 组件包裹所有需要动画的子元素，该组件有一个 flipKey 属性，每当需要触发动画时该属性都会变化。

2. 用 Flipped 组件包裹需要动画的元素，这些组件应该有一个在不同渲染间匹配的 flipId 属性。

目录

• 可分叉示例
  • 简单示例：展开的 Div
  • 简单示例：两个 Div
  • 简单示例：列表随机排序
  • 列表过渡
  • 交错效果
  • 弹簧自定义
  • 嵌套缩放变换
  • 基于路由的动画与 React Router
  • 更多示例
• 组件
  • Flipper
    • 基本属性
    • 高级属性
  • Flipped
    • 包裹 React 组件
    • 基本属性
    • 回调属性
    • 变换属性
    • 高级属性
  • Spring
• 库详情
• 故障排除
  • 问题 #1：什么都没发生
  • 问题 #2：效果看起来很奇怪/动画表现不正常
  • 问题 #3：仍然无法正常工作
• 性能
  • 记忆化
  • will-change:transform

可分叉示例

简单示例：展开的 Div

在 Code Sandbox 上分叉此示例

import React, { useState } from 'react'
import { Flipper, Flipped } from 'react-flip-toolkit'

const AnimatedSquare = () => {
  const [fullScreen, setFullScreen] = useState(false)
  const toggleFullScreen = () => setFullScreen(prevState => !prevState)

  return (
    <Flipper flipKey={fullScreen}>
      <Flipped flipId="square">
        <div
          className={fullScreen ? 'full-screen-square' : 'square'}
          onClick={toggleFullScreen}
        />
      </Flipped>
    </Flipper>
  )
}

简单示例：两个 Div

在 Code Sandbox 上分叉此示例

import React, { useState } from 'react'
import { Flipper, Flipped } from 'react-flip-toolkit'

const Square = ({ toggleFullScreen }) => (
  <Flipped flipId="square">
    <div className="square" onClick={toggleFullScreen} />
  </Flipped>
)

const FullScreenSquare = ({ toggleFullScreen }) => (
  <Flipped flipId="square">
    <div className="full-screen-square" onClick={toggleFullScreen} />
  </Flipped>
)

const AnimatedSquare = () => {
  const [fullScreen, setFullScreen] = useState(false)
  const toggleFullScreen = () => setFullScreen(prevState => !prevState)

  return (
    <Flipper flipKey={fullScreen}>
      {fullScreen ? (
        <FullScreenSquare toggleFullScreen={toggleFullScreen} />
      ) : (
        <Square toggleFullScreen={toggleFullScreen} />
      )}
    </Flipper>
  )
}

简单示例：列表随机排序

在 Code Sandbox 上分叉此示例

import React, { useState } from 'react'
import { Flipper, Flipped } from 'react-flip-toolkit'
import shuffle from 'lodash.shuffle'

const ListShuffler = () => {
  const [data, setData] = useState([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
  const shuffleList = () => setData(shuffle(data))

  return (
    <Flipper flipKey={data.join('')}>
      <button onClick={shuffleList}> 随机排序</button>
      <ul className="list">
        {data.map(d => (
          <Flipped key={d} flipId={d}>
            <li>{d}</li>
          </Flipped>
        ))}
      </ul>
    </Flipper>
  )
}

列表过渡

通过为卡片的大小和位置变化添加动画，为动态卡片列表增添趣味。

在 Code Sandbox 上分叉此示例

交错效果

react-flip-toolkit 库提供了基于弹簧的交错配置，让你能够实现复杂的序列效果。

对于最基本的交错效果，你只需要在 Flipped 元素上添加一个 stagger 布尔属性：

<Flipped flipId={`element-${i}`} stagger>
  <AnimatedListItem/>
</Flipped>

在 Code Sandbox 上分叉此示例

弹簧自定义

react-flip-toolkit 使用弹簧动画。要自定义弹簧效果，你可以传入一个预设名称:

// 弹簧预设可以是以下之一: "stiff", "noWobble", "gentle", "veryGentle", 或 "wobbly"
<Flipper flipKey='foo' spring='wobbly'>
  {/* 放置 Flipped 组件 */}
</Flipper>

或者自定义弹簧配置:

<Flipper flipKey='foo' spring={{ stiffness: 280, damping: 22 }} >
  {/* 放置 Flipped 组件 */}
</Flipper>

在交互式探索器中查看所有弹簧选项

嵌套缩放变换

• 在 Code Sandbox 上 fork 这个示例
• Fork GitHub 仓库

有趣的动画通常除了简单的平移变换外还包含缩放变换。缩放动画的问题在于子元素 — 如果你将一个 div 放大 2 倍，它的任何子元素也会被放大，从而创建一个看起来很奇怪的动画。这就是为什么这个库允许你用一个带有 inverseFlipId 的 Flipped 组件包裹子元素，以抵消父元素的变换:

<Flipped flipId={id}>
  <div>
    <Flipped inverseFlipId={id} scale>
      <div>不会被扭曲的文本</div>
    </Flipped>
  </div>
</Flipped>

默认情况下，父元素的缩放和平移变换都会被抵消(这允许子组件进行自己的 FLIP 动画而不受父元素影响)。 但在许多使用场景中，你还需要额外指定 scale 属性来限制调整为仅缩放，并允许定位随父元素移动。

注意: 具有反向变换的 DOM 元素应该紧贴其父容器，以实现最无缝的动画效果。

这意味着任何布局样式 — 内边距、弹性盒子等 — 应该应用于反转容器(用带有 inverseFlipId 的 Flipped 组件包裹的元素)而不是父 Flipped 容器。

使用 React Router 的基于路由的动画

Fork GitHub 仓库

react-flip-toolkit 可以很好地与客户端路由器配合使用，提供路由驱动的过渡效果:

<Route
  render={({ location, search }) => {
    return (
      <Flipper
        flipKey={`${location.pathname}-${location.search}`}
      >
      {/* 包含 Flipped 组件的子路由放在这里 */}
      </Flipper>
    )
  }}
/>

更多示例

• 吉他商店
• React-flip-toolkit 标志
• 使用 Portals

组件

Flipper

包含所有需要动画的元素的父包装组件。通常每个页面只需要一个，但有时在页面的不同区域使用多个 Flipper 来处理不同的过渡效果会更方便。

<Flipper flipKey={someKeyThatChanges}>{/* 子元素 */}</Flipper>

基本属性

staggerConfig={{
  // "default" 配置将应用于没有显式键的交错元素
      default: {
        // 默认方向是正向
        reverse: true,
        // 默认为 .1, 0 < n < 1
        speed: .5
      },
  // 这将应用于具有 stagger='namedStagger' 属性的 Flipped 元素
    namedStagger : { speed: .2 }
  }}

高级属性

handleEnterUpdateDelete({
  // 该函数将进入元素的不透明度设为0，以便后续淡入效果
  // 应该立即调用
  hideEnteringElements,
  // 为所有进入的元素调用 `onAppear`
  animateEnteringElements,
  // 为所有退出的元素调用 `onExit`
  // 返回一个 Promise，在所有元素退出后解析
  animateExitingElements,
  // 主要事件：对更新的元素执行 `FLIP` 动画
  // 同样返回一个 Promise，在动画完成时解析
  animateFlippedElements
})

Flipped

包装一个需要动画效果的元素。

例如，在一个组件中你可以有：

<Flipped flipId="coolDiv">
  <div className="small" />
</Flipped>

在另一个组件的其他地方你可以有：

<Flipped flipId="coolDiv">
  <div className="big" />
</Flipped>

它们将通过 react-flip-toolkit 进行过渡动画。

Flipped 组件不会生成任何标记，它只是将一些属性传递给其包装的子元素。

包装 React 组件

如果你想包装 React 组件而不是像 div 这样的 JSX 元素，你可以提供一个渲染属性，然后在你的组件中将 flippedProps 直接应用到被包装的元素上：

<Flipped>
  {flippedProps => <MyCoolComponent flippedProps={flippedProps} />}
</Flipped>

const MyCoolComponent = ({ flippedProps }) => <div {...flippedProps} />

你也可以简单地提供一个普通的 React 组件，只要该组件将未识别的属性直接传递给包装的元素（这种技术适用于包装样式化组件）：

<Flipped>
  <MyCoolComponent />
</Flipped>

const MyCoolComponent = ({ knownProp, ...rest }) => <div {...rest} />

基本属性

回调属性

上面的动画使用 onAppear 和 onExit 回调来实现淡入和淡出动画。

变换属性

默认情况下，FLIP 元素的 translate、scale 和 opacity 属性都会被变换。但是，某些效果需要更多控制，所以如果你指定了以下任何属性，只有指定的属性会被缓动：

高级属性

控制 FLIP 何时发生的函数

Spring

为了方便，react-flip-toolkit 导出了一个小函数，用于访问用于创建 FLIP 过渡的相同弹簧系统。

在 CodeSandbox 上 Fork 示例

import { spring } from 'react-flip-toolkit'

spring({
  config: "wobbly",
  values: {
    translateY: [-15, 0],
    opacity: [0, 1]
  },
  onUpdate: ({ translateY, opacity }) => {
    el.style.opacity = opacity;
    el.style.transform = `translateY(${translateY}px)`;
  },
  delay: i * 25,
  onComplete: () => console.log('完成')
});

全局配置函数

如果需要在所有地方禁用（或重新启用）FLIP动画，可以通过编程方式调用以下函数。

disableFlip()

全局开关，用于禁用所有Flipper容器中的所有动画。

enableFlip()

全局开关，用于（重新）启用所有Flipper容器中的所有动画。默认情况下，动画是启用的。只有在之前使用disableFlip()禁用了动画时，才需要调用此函数。

isFlipEnabled()

返回一个布尔值，指示动画是全局启用还是禁用。

库详情

• 使用Browserstack在最新的Chrome、Firefox、Safari和Edge浏览器中进行了测试。
• 需要React 16+版本
• 使用Rematrix进行矩阵计算，使用Rebound的简化分支进行弹簧动画

故障排除

问题#1：没有任何反应

• 确保在需要触发动画时更新了Flipper组件的flipKey属性。
• 如果你的Flipped组件包裹的是另一个React组件而不是DOM元素，使用渲染属性获取Flipped属性并传递给必要的DOM元素。
• 接收Flipped属性的元素是否在DOM中可见？react-flip-toolkit会尝试优化性能，不会对屏幕外的元素或没有宽度和高度的元素进行动画处理。
• display:inline元素无法进行动画。如果你想让inline元素产生动画效果，请设置display:inline-block。
• 你是否开启了prefers-reduced-motion设置？从v7.1.0版本开始，该设置会禁用所有动画。

问题#2：效果看起来很奇怪/动画行为异常

• 检查确保所有flipId是唯一的。 在任何时候，页面上只能有一个元素具有指定的flipId。如果页面上有多个具有相同id的Flipped元素，动画将会出错。
• 确保你在为想要制作动画的元素添加动画，而不是例如包裹它的div。 如果你为内联元素（如文本）制作动画，但将其包裹在一个div中，实际上你是在为div添加动画，这可能会在某些时候导致宽度比预期的要大得多，从而影响动画效果。检查是否需要给动画元素添加inline-block样式。
• 确保相关元素上没有任何冲突的CSS过渡。
• 如果你在为图片制作动画，尝试给图片设置固定尺寸，看看是否能解决问题。（如果你依赖图片的固有尺寸，可能在浏览器完全渲染新图片尺寸之前就开始测量了。）

问题#3：仍然无法正常工作

• 尝试使用debug属性。如果你仍然无法找出问题所在，可以直接在Flipper组件上添加debug属性来暂停过渡的开始。
• 如果你认为可能确实存在问题，或者完全卡住了，欢迎提出issue。

性能

React-flip-toolkit在底层做了很多工作来尝试最大化你的动画性能 —— 例如，不会对屏幕外的元素进行动画处理，并且样式更新会被批量处理以防止布局抖动。 然而，如果你正在构建特别复杂的动画 —— 涉及数十个元素或大型图片的动画 —— 还有一些额外的策略可以用来确保动画的性能。

记忆化

当你使用react-flip-toolkit触发复杂的FLIP动画时，React可能会在允许动画开始之前花费宝贵的毫秒时间进行不必要的协调工作。如果你注意到动画触发和开始之间有轻微的延迟，这可能就是原因。为了绕过这种可能不必要的工作，尝试使用React.memo或PureComponent对你的动画元素进行记忆化，并看看是否可以重构你的代码，以在动画即将发生时最小化对动画子元素的属性更新。

will-change:transform

.box {
  will-change: transform;
}

这个CSS属性告诉浏览器预期元素将发生变化。应谨慎使用，因为它可能会增加浏览器资源的使用。如果你注意到动画中存在渲染问题，可以尝试看看它是否能提高动画的性能。