# unitypackages-uitransition

**Repository Path**: RoastDango/unitypackages-uitransition

## Basic Information

- **Project Name**: unitypackages-uitransition
- **Description**: 为 Unity 项目提供的一套轻量、灵活的 UI 转场动画解决方案
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-05
- **Last Updated**: 2026-01-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# UI转场动画模块 (UI Transition Module)

## 概述

本模块为 Unity 项目提供了一套轻量、灵活的 UI 转场动画解决方案。它允许开发者通过预制体和 Animator，轻松实现覆盖式的全屏过渡效果，常用于场景加载、UI 面板切换等需要平滑视觉过渡的场景

该模块旨在通过简单的 API 和事件回调，将动画播放与业务逻辑（如资源加载、场景切换）解耦，让转场流程更加清晰和易于管理

## 核心功能

*   **预制体驱动**: 将转场动画封装为预制体，方便在不同场景和项目中复用
*   **事件回调**: 提供转场开始 (`onTransitionBegin`)、到达切换点 (`onTransitionArriveCutPoint`) 和转场完成 (`onTransitionCompleted`) 的 `UnityEvent` 事件，方便在 Inspector 中或通过代码挂载逻辑
*   **灵活的调用方式**:
    *   **自动流程**: 调用 `DoTransition()` 并指定中间停留时间
    *   **注入逻辑**: 在转场切换点执行自定义的协程（`IEnumerator`），非常适合执行异步加载等耗时操作
    *   **手动控制**: 可独立调用淡入 (`TransitionFadeInCoroutine`) 和淡出 (`TransitionFadeOutCoroutine`) 协程，实现对转场流程的完全控制
*   **射线阻挡**: 可选的在转场期间启用全屏射线阻挡，防止用户误操作
*   **自定义动画**: 提供了清晰的工作流，允许快速创建和集成新的转场动画效果

---

## 快速开始

### 1. 依赖项

*   无特定依赖项，可用于各类 Unity 项目

### 2. 安装与设置

1.  在场景的 Canvas 下创建一个空对象，或直接将转场动画预制体拖入 Canvas 中（推荐做法）
2.  将 `UITransition` 组件添加到该对象上
3.  将一个带有转场动画的子对象（包含 `Animator` 组件）放置在该对象下。`UITransition` 组件会自动获取到它
    *   动画器应包含 `fadeIn` 和 `fadeOut` 两个 Trigger 参数
    *   动画状态应分别命名为 `TransitionEnter` 和 `TransitionExit`
4.  在 `UITransition` 组件的 Inspector 中，可以配置默认的动画速度和切换点停留时间

### 3. 基础用法：固定时长的转场

这是最简单的用法，转场动画会完整播放，并在淡入和淡出之间停留指定的时间

```csharp
using DreemurrStudio.UITranstion;
using UnityEngine;

public class SimpleTransition : MonoBehaviour
{
    public UITransition transitionEffect;

    void Start()
    {
        // 执行转场，并在切换点停留 1.5 秒
        transitionEffect.DoTransition(1.5f);

        // 监听转场完成事件
        transitionEffect.onTransitionCompleted.AddListener(() =>
        {
            Debug.Log("转场动画播放完毕！");
        });
    }
}
```

### 4. 在转场期间执行操作

通过传入一个协程，可以在转场动画完全覆盖屏幕时（切换点）执行加载、切换场景或更改 UI 状态等操作

```csharp
using DreemurrStudio.UITranstion;
using UnityEngine;
using System.Collections;
using UnityEngine.SceneManagement;

public class LoadingTransition : MonoBehaviour
{
    public UITransition transitionEffect;
    public GameObject panelA;
    public GameObject panelB;

    // 由UI按钮等调用
    public void SwitchPanels()
    {
        // 执行转场，并在切换点执行 SwitchAction 协程
        transitionEffect.DoTransition(SwitchAction());
    }

    private IEnumerator SwitchAction()
    {
        Debug.Log("转场到达切换点，开始执行加载操作...");

        // 隐藏旧面板
        panelA.SetActive(false);

        // 模拟耗时操作，例如加载资源或场景
        yield return new WaitForSeconds(2f);
        // 或者异步加载场景
        // yield return SceneManager.LoadSceneAsync("MyNewScene");

        // 显示新面板
        panelB.SetActive(true);

        Debug.Log("加载操作完成，即将开始淡出...");
    }
}
```

### 5. 推荐用法：手动控制转场流程

这是最常用和推荐的方式。通过在协程中分别调用淡入和淡出协程来更精细地控制转场的完整流程

```csharp
using DreemurrStudio.UITranstion;
using UnityEngine;
using System.Collections;
using UnityEngine.SceneManagement;

public class ManualTransitionControl : MonoBehaviour
{
    public UITransition transitionEffect;

    void Start()
    {
        StartCoroutine(FullTransitionFlow());
    }

    private IEnumerator FullTransitionFlow()
    {
        // 1. 执行淡入
        Debug.Log("开始淡入...");
        yield return transitionEffect.TransitionFadeInCoroutine();

        // 2. 在切换点执行自定义逻辑
        Debug.Log("淡入完成，开始切换场景");
        yield return SceneManagement.LoadSceneAsync("NextScene");
        yield return new WaitForSeconds(1f); 

        // 3. 等待用户输入
        Debug.Log("等待用户点击...");
        yield return new WaitUntil(() => Input.GetMouseButtonDown(0));

        // 4. 执行淡出
        Debug.Log("开始淡出...");
        yield return transitionEffect.TransitionFadeOutCoroutine();

        Debug.Log("整个流程结束。");
    }
}
```

---

## 如何制作新的转场动画

1. 确定新的转场动画的名称，下文中均以`[NAME]`指代，在包的 `ExtraTransition` 文件夹中创建一个新文件夹命名为 `[NAME]`，后续的新建资源均放置在该文件夹内
2. 在文件夹下创建“[NAME]In”和“[NAME]Out”两段动画，确保它们适合覆盖整个屏幕，并且循环选项（Loop Time）已关闭
3.  创建一个新的动画覆盖控制器（Animator Override Controller），覆盖自名为`TransitionBase`的动画器
4.  将“[NAME]In”和 “[NAME]Out”动画分别设为覆盖动画器对 `TransitionIn` 和 `TransitionOut` 状态的覆盖动画
5.  将包的 `Perfabs`中的`UITransition` 预制体实例拖拽到场景中作为根对象，为其创建一个带Image组件的子对象
6.  为该子对象添加 `Animator` 组件，并将刚创建的动画控制器赋给它的 `Animator` 组件，播放两端动画，检查是否符合预期效果
7.  确认无误后，将根对象保存为新的预制体，即可在项目中使用