View Transitions

在 ChatGPT 中打开

Java API

25.11 实验性

视图过渡提供在 DOM 变化时的动画过渡，减少视觉冲击并在导航或内容更新期间保持空间上下文。 webforJ 与浏览器的 视图过渡 API 集成，以处理协调旧状态和新状态之间动画的复杂性。

显示代码

ViewTransitionChatView.java

chat.css

DemoHeader.java

demo-header.css

实验性功能

此功能为实验性，未来版本可能会改变或删除。

基本用法

要创建视图过渡，请使用 Page.getCurrent().startViewTransition()，该方法返回一个用于配置过渡的构建器：

Page.getCurrent().startViewTransition()
  .onUpdate(done -> {
    container.remove(oldView);
    container.add(newView);
    done.run();
  })
  .start();

过渡过程捕捉当前状态的快照，在 onUpdate 回调中应用您的 DOM 更改，然后从旧快照动画过渡到新内容。您必须调用 done.run() 来表示您的更改已完成。

onUpdate 回调是必需的

未设置更新回调而调用 start() 会抛出 IllegalStateException。

应用过渡

webforJ 提供预定义的过渡类型，您可以将其应用于进入或退出 DOM 的组件：

常量	效果
ViewTransition.NONE	无动画
ViewTransition.FADE	在旧内容和新内容之间交叉淡入淡出
ViewTransition.SLIDE_LEFT	内容向左流动（如前进导航）
ViewTransition.SLIDE_RIGHT	内容向右流动（如返回导航）
ViewTransition.SLIDE_UP	内容向上流动
ViewTransition.SLIDE_DOWN	内容向下流动
ViewTransition.ZOOM	旧内容缩小，新内容放大
ViewTransition.ZOOM_OUT	旧内容放大，新内容缩小

使用 enter() 为正在添加的组件动画，使用 exit() 为正在移除的组件动画：

// 对进入 DOM 的组件进行动画
Page.getCurrent().startViewTransition()
  .enter(chatPanel, ViewTransition.ZOOM)
  .onUpdate(done -> {
    container.add(chatPanel);
    done.run();
  })
  .start();

// 对退出 DOM 的组件进行动画
Page.getCurrent().startViewTransition()
  .exit(chatPanel, ViewTransition.FADE)
  .onUpdate(done -> {
    container.remove(chatPanel);
    done.run();
  })
  .start();

共享组件过渡

共享组件过渡创建了一个变形效果，其中组件似乎从旧视图中的位置转换到新视图中的位置。这是通过使用 setViewTransitionName() 方法为组件赋予相同的过渡名称来实现的，该方法适用于任何实现了 HasStyle 接口的组件。

// 在卡片视图中
image.setViewTransitionName("blog-image");

// 在详细视图中 - 相同名称创建变形
image.setViewTransitionName("blog-image");

在这些视图之间过渡时，浏览器在位置之间为组件动画，创建一个连贯的视觉体验。

使用唯一名称

在处理列表或重复组件时，请在过渡名称中包含唯一标识符。每个组件需要其自己的独特名称，以便正确地变形到新视图中的对应组件。对多个可见组件使用相同的名称会导致未定义行为。

显示代码

ViewTransitionMorphView.java

BlogCard.java

BlogDetail.java

morph.css

DemoHeader.java

demo-header.css

列表重排序

共享组件过渡的常见用例是在其顺序更改时对列表项进行动画。通过为每个项目分配唯一的 view-transition-name，浏览器自动将组件动画到其新位置：

// 每个卡片根据其 ID 获取唯一的过渡名称
card.setViewTransitionName("card-" + item.id());

// 在洗牌时，仅更新 DOM - 浏览器处理动画
Page.getCurrent().startViewTransition()
  .onUpdate(done -> {
    renderList();
    done.run();
  })
  .start();

显示代码

ViewTransitionShuffleView.java

ShuffleCard.java

shuffle.css

DemoHeader.java

demo-header.css

自定义 CSS 动画

为了完全控制动画，您可以定义自定义 CSS 关键帧。 webforJ 会在您的过渡名称后附加 -enter 或 -exit 后缀，您可以使用这些后缀来定位视图过渡伪元素：

/* 定义进入组件的关键帧 */
@keyframes flip-enter {
  from {
    opacity: 0;
    transform: perspective(1000px) rotateX(-90deg);
  }
  to {
    opacity: 1;
    transform: perspective(1000px) rotateX(0deg);
  }
}

/* 应用到视图过渡伪元素 */
::view-transition-new(flip-in-enter) {
  animation: flip-enter 450ms cubic-bezier(0.34, 1.56, 0.64, 1);
  transform-origin: top center;
}

::view-transition-old(flip-in-enter) {
  display: none;
}

通过将其名称（不带后缀）传递给 enter() 或 exit() 来引用您的自定义动画：

// 使用 "flip-in" - webforJ 会自动添加 "-enter" 后缀
Page.getCurrent().startViewTransition()
  .enter(notification, "flip-in")
  .onUpdate(done -> {
    stage.add(notification);
    done.run();
  })
  .start();

// 对于退出使用 "blur-out" - webforJ 会添加 "-exit" 后缀
Page.getCurrent().startViewTransition()
  .exit(notification, "blur-out")
  .onUpdate(done -> {
    stage.remove(notification);
    done.run();
  })
  .start();

显示代码

ViewTransitionEnterExitView.java

enterexit.css

DemoHeader.java

demo-header.css

CSS 自定义

每种预定义的过渡类型都公开 CSS 自定义属性以便于微调：

淡入

变量	默认值	描述
--vt-fade-duration	200ms	动画持续时间
--vt-fade-easing	cubic-bezier(0.4, 0, 0.2, 1)	缓动函数

向左滑动

变量	默认值	描述
--vt-slide-left-duration	200ms	动画持续时间
--vt-slide-left-easing	cubic-bezier(0.4, 0, 0.2, 1)	缓动函数
--vt-slide-left-distance	30%	滑动距离

向右滑动

变量	默认值	描述
--vt-slide-right-duration	200ms	动画持续时间
--vt-slide-right-easing	cubic-bezier(0.4, 0, 0.2, 1)	缓动函数
--vt-slide-right-distance	30%	滑动距离

向上滑动

变量	默认值	描述
--vt-slide-up-duration	200ms	动画持续时间
--vt-slide-up-easing	cubic-bezier(0.4, 0, 0.2, 1)	缓动函数
--vt-slide-up-distance	30%	滑动距离

向下滑动

变量	默认值	描述
--vt-slide-down-duration	200ms	动画持续时间
--vt-slide-down-easing	cubic-bezier(0.4, 0, 0.2, 1)	缓动函数
--vt-slide-down-distance	30%	滑动距离

缩放

变量	默认值	描述
--vt-zoom-duration	200ms	动画持续时间
--vt-zoom-easing	cubic-bezier(0.4, 0, 0.2, 1)	缓动函数
--vt-zoom-scale	0.8	缩放因子（旧的缩小到这里，新的从这里放大）

缩小

变量	默认值	描述
--vt-zoom-out-duration	200ms	动画持续时间
--vt-zoom-out-easing	cubic-bezier(0.4, 0, 0.2, 1)	缓动函数
--vt-zoom-out-scale	1.2	缩放因子（旧的放大到这里，新的从这里缩小）

覆盖变量

要自定义，请在您的 CSS 中覆盖这些变量：

:root {
  --vt-fade-duration: 300ms;
  --vt-slide-left-distance: 50%;
}

对于高级自定义，直接定位视图过渡伪元素：

::view-transition-old(vt-slide-left-exit) {
  animation-duration: 400ms;
}

::view-transition-new(vt-slide-left-enter) {
  animation-timing-function: ease-out;
}