翻译 react-transition-group 之 Transition

2024-01-07 17:36:34

目前本人学习到 react 动画组件库，react-transition-group 有一颗感兴趣的心，也想学学大神，翻译一下文档，所以就拿这个开刀，动手。原文通道

Transition 过渡

Transition 组件允许你使用一个简单的申明API去描述一个组件在一段时间内从一个状态过渡到另一个组件。最常见的是，它用于设置组件的挂载和卸载的过渡，但也可以用于描述组件状态本身的过渡

The Transition component lets you describe a transition from one component state to another over time with a simple declarative API. Most commonly it’s used to animate the mounting and unmounting of a component, but can also be used to describe in-place transition states as well.

注意: Transition 是一个不限制平台的跟组件。如果你正在使用css来过渡，你可以使用CSSTransition组件来代替。它不仅包含了Transition组件的所有功能，而且还额外包含了一些Css 过渡所必须的特征。（组件由此得名——Transition）

Note: Transition is a platform-agnostic base component. If you’re using transitions in CSS, you’ll probably want to use CSSTransition instead. It inherits all the features of Transition, but contains additional features necessary to play nice with CSS transitions (hence the name of the component).

默认情况下Transition 组件渲染不会产生额外的副作用，它仅仅是维护组件的enter和exit状态。这些状态的意义和效果取决于你。例如：当组件enter（进入）或者exite（退出）我们可以给组件添加一个内联样式。

By default the Transition component does not alter the behavior of the component it renders, it only tracks “enter” and “exit” states for the components. It’s up to you to give meaning and effect to those states. For example we can add styles to a component when it enters or exits:

import { Transition } from 'react-transition-group';
// 定义过渡的时间
const duration = 300;
// 定义默认的样式， css transition的属性
const defaultStyle = {
  transition: `opacity ${duration}ms ease-in-out`,
  opacity: 0,
}
// 动画的样式
const transitionStyles = {
  entering: { opacity: 1 },
  entered:  { opacity: 1 },
  exiting:  { opacity: 0 },
  exited:  { opacity: 0 },
};

const Fade = ({ in: inProp }) => (
  <Transition in={inProp} timeout={duration}>
    {state => (
      <div style={{
        ...defaultStyle,
        ...transitionStyles[state]
      }}>
        I'm a fade Transition!
      </div>
    )}
  </Transition>
);

Transition 组件包含 4种状态：

‘entering’ 进入中
‘entered’ 进入完成
‘exiting’ 退出中
‘exited’ 完成退出

There are 4 main states a Transition can be in:

‘entering’

‘entered’

‘exiting’

‘exited’

Transition 组件的状态通过in属性来触发。当为 true 的时候，组件开始进入 Enter(进入)阶段。在这一期间，组件将会切换它当前的阶段，从 entering(进入中) 状态等待 duration（过渡时间）完成切换到 entered(完成进入) 状态。让我举下面的例子（我们将会使用 useState 钩子）

Transition state is toggled via the in prop. When true the component begins the “Enter” stage. During this stage, the component will shift from its current transition state, to ‘entering’ for the duration of the transition and then to the ‘entered’ stage once it’s complete. Let’s take the following example (we’ll use the useState hook):

function App() {
  const [inProp, setInProp] = useState(false);
  return (
    <div>
      <Transition in={inProp} timeout={500}>
        {state => (
          // ...
        )}
      </Transition>
      <button onClick={() => setInProp(true)}>
        Click to Enter
      </button>
    </div>
  );
}

当按钮被点击时，组件将会切换到entering(进入中)状态然后保持500ms（timeout 属性定义的之）的过渡动画,它最终回切换到entered(进入完成)状态

When the button is clicked the component will shift to the ‘entering’ state and stay there for 500ms (the value of timeout) before it finally switches to ‘entered’.

当 in属性为 false时候，发和上面进入发生同样的事情，（组件切换到exiting退出中状态然后等待500ms切换到exited 退出完成状态）

When in is false the same thing happens except the state moves from ‘exiting’ to ‘exited’.

Props 属性

nodeRef

需要添加过渡的React DOM的引用：详情查看 https://*.com/a/51127130/4671932

当 nodeRef 属性被使用时候, 节点不会传递一个回调函数（例如：onEnter 事件），因为用户已经可以直接访问该节点
在 TransitionGroup组件中改变Transition 组件中 key 的属性需要提供改变的属性key （查看 text/CSSTransition-test.js）

type: shape

A React reference to DOM element that need to transition: https://*.com/a/51127130/4671932

When nodeRef prop is used, node is not passed to callback functions (e.g. onEnter) because user already has direct access to the node.

When changing key prop of Transition in a TransitionGroup a new nodeRef need to be provided to Transition with changed key prop (see test/CSSTransition-test.js).
type: shape

children

child属性必须是一个函数而不是React 元素。函数的参数是当前过渡状态（entering(进入中)，entered(完成进入)，exiting(退出中)，exited(完成退出)）,该状态当作上下文被用于子级组件的属性。

A function child can be used instead of a React element. This function is called with the current transition status (‘entering’, ‘entered’, ‘exiting’, ‘exited’), which can be used to apply context specific props to a component.

<Transition in={this.state.in} timeout={150}>
  {state => (
    <MyComponent className={`fade fade-${state}`} />
  )}
</Transition>

type: Function | element
required（必须）

in

用于显示里面的子组件，修改后触发进入或者退出状态

Show the component; triggers the enter or exit states

type: boolean
default: false

mountOnEnter

默认情况下，子组件和Transition 组件是立即被挂载的。如果你想在Transition组件第一次 in= {true}的情况下启用“懒加载”，你可以设置 mountOnEnter={true}。组件在第一次进入的 Transition 组件将保持在挂载，甚至在exited(完成退出)组件也保持在挂载阶段，不会生成实际的DOM,除非你特别指定unmountOnExit

By default the child component is mounted immediately along with the parent Transition component. If you want to “lazy mount” the component on the first in={true} you can set mountOnEnter. After the first enter transition the component will stay mounted, even on “exited”, unless you also specify unmountOnExit.

type: boolean
default: false

unmountOnExit

默认情况下，子组件在达到“exited(完成退出)”状态后保持挂载状态。如果希望在组件完成exiting(退出)后卸载组件，请设置unmountOnExit

By default the child component stays mounted after it reaches the ‘exited’ state. Set unmountOnExit if you’d prefer to unmount the component after it finishes exiting.

type: boolean
default: false

appear

默认情况下，子组件在第一次装载时不执行enter(进入)过渡动画，而与in的值无关。如果需要此行为，请将“appear”和“in”都设置为true

By default the child component does not perform the enter transition when it first mounts, regardless of the value of in. If you want this behavior, set both appear and in to true.

注意：这里没有额外的appear状态，类似 appearing/appeared,这个属性仅仅添加到额外的enter(进入)阶段的过渡。然而，在 <CSSTransition>组件中第一次进入过渡可以添加额外的.appea-*类名，这样就可以个性化不同的样式

Note: there are no special appear states like appearing/appeared, this prop only adds an additional enter transition. However, in the component that first enter transition does result in additional .appear-* classes, that way you can choose to style it differently.

type: boolean
default: false

enter

启用或者禁用 enter(进入)阶段的过渡效果

Enable or disable enter transitions.

type: boolean
default: true

exit

启用或者禁用exit(退出)阶段的过渡

Enable or disable exit transitions.

type: boolean
default: true

timeout

过渡的持续时间（毫秒），必选除非提供了 addEndListener事件

The duration of the transition, in milliseconds. Required unless addEndListener is provided.

你可以指定单个时间对于整个过渡：

You may specify a single timeout for all transitions:

timeout={500}
or individually:

timeout={{
 appear: 500,
 enter: 300,
 exit: 500,
}}

appear defaults to the value of enter
enter defaults to 0 exit
defaults to 0

type: number | { enter?: number, exit?: number, appear?: number }

addEndListener

添加一个自定义过渡结束后的事件。返回的参数是过渡中的DOM节点和一个 done()回调函数。允许更细粒度处理过渡结束后的逻辑。如果使用了，超时会依然作为fallback使用

Add a custom transition end trigger. Called with the transitioning DOM node and a done callback. Allows for more fine grained transition end logic. Timeouts are still used as a fallback if provided.

注意：，当 nodeRef属性使用时，node 不会被当作参数返回

Note: when nodeRef prop is passed, node is not passed.

addEndListener={(node, done) => {
  // use the css transitionend event to mark the finish of a transition
  node.addEventListener('transitionend', done, false);
}}

type: Function

onEnter

在应用“enter”状态之前触发回调。提供了一个额外的参数isAppearing来指示enter阶段是否发生在首次挂载上

Callback fired before the “entering” status is applied. An extra parameter isAppearing is supplied to indicate if the enter stage is occurring on the initial mount

**注意：**当 nodeRef属性使用时，node 不会被当作参数返回

Note: when nodeRef prop is passed, node is not passed.

type: Function(node: HtmlElement, isAppearing: bool) -> void
default: function noop() {}