可显示元素

将元素移动到新的位置

element.pos({
    xalign: 0.3
}, 1000, "linear"); // 在 1000 毫秒内以线性缓动将元素移动到 x: 0.3

• position: CommonDisplayableConfig["position"] - 元素的新位置，参见 CommonDisplayableConfig
• duration?: number - 变换的持续时间，以毫秒为单位
• easing?: TransformDefinitions.EasingDefinition - 使用的缓动函数，参见 TransformDefinitions.EasingDefinition

缩放元素

element.scale(1.5, 0.8, 1000, "easeInOut"); // 在 1000 毫秒内以 easeInOut 缓动将元素在 X 轴缩放到 1.5 倍，Y 轴缩放到 0.8 倍

• scaleX: number - 元素在 X 轴的新缩放比例，使用负值可以反转缩放
• scaleY: number - 元素在 Y 轴的新缩放比例，使用负值可以反转缩放
• duration?: number - 变换的持续时间，以毫秒为单位
• easing?: TransformDefinitions.EasingDefinition - 使用的缓动函数，参见 TransformDefinitions.EasingDefinition

在 X 轴方向缩放元素

element.scaleX(1.5, 1000, "easeInOut"); // 在 1000 毫秒内以 easeInOut 缓动将元素在 X 轴缩放到 1.5 倍

• scaleX: number - 元素在 X 轴的新缩放比例
• duration?: number - 变换的持续时间，以毫秒为单位
• easing?: TransformDefinitions.EasingDefinition - 使用的缓动函数，参见 TransformDefinitions.EasingDefinition

在 Y 轴方向缩放元素

element.scaleY(0.8, 1000, "easeInOut"); // 在 1000 毫秒内以 easeInOut 缓动将元素在 Y 轴缩放到 0.8 倍

• scaleY: number - 元素在 Y 轴的新缩放比例
• duration?: number - 变换的持续时间，以毫秒为单位
• easing?: TransformDefinitions.EasingDefinition - 使用的缓动函数，参见 TransformDefinitions.EasingDefinition

同时在 X 和 Y 轴方向缩放元素

element.scaleXY(1.2, 0.9, 1000, "easeInOut"); // 在 1000 毫秒内以 easeInOut 缓动将元素在 X 轴缩放到 1.2 倍，Y 轴缩放到 0.9 倍

• scaleX: number - 元素在 X 轴的新缩放比例
• scaleY: number - 元素在 Y 轴的新缩放比例
• duration?: number - 变换的持续时间，以毫秒为单位
• easing?: TransformDefinitions.EasingDefinition - 使用的缓动函数，参见 TransformDefinitions.EasingDefinition

缩放图像（推荐用于图像缩放）

element.zoom(2, 1000, "easeInOut"); // 在 1000 毫秒内以 easeInOut 缓动将图像缩放到 2 倍

• zoom: number - 图像的新缩放比例
• duration?: number - 变换的持续时间，以毫秒为单位
• easing?: TransformDefinitions.EasingDefinition - 使用的缓动函数，参见 TransformDefinitions.EasingDefinition

旋转元素

element.rotate(90, 1000, "easeInOut"); // 在 1000 毫秒内以 easeInOut 缓动将元素旋转到 90 度

• angle: number - 元素的新角度，以度为单位
• duration?: number - 变换的持续时间，以毫秒为单位
• easing?: TransformDefinitions.EasingDefinition - 使用的缓动函数，参见 TransformDefinitions.EasingDefinition

更改元素的不透明度

element.opacity(0.5, 1000, "easeInOut"); // 在 1000 毫秒内以 easeInOut 缓动将元素的不透明度更改为 0.5

• opacity: number - 元素的新不透明度，介于 0 和 1 之间
• duration?: number - 变换的持续时间，以毫秒为单位
• easing?: TransformDefinitions.EasingDefinition - 使用的缓动函数，参见 TransformDefinitions.EasingDefinition

直接应用一个或多个视觉效果字段

• effect: TransformDefinitions.VisualEffectTransformProps - 支持 maskImage、maskSize、maskPosition、maskRepeat、maskMode、clipPath、filter、backdropFilter 和 mixBlendMode
• options?: TransformDefinitions.VisualEffectOptions - 过渡选项，如 duration、ease、delay 和 at

应用图片遮罩。遮罩图片会自动注册到预加载列表

• src: ImageSrc - 遮罩图片源
• options?: TransformDefinitions.MaskOptions - 遮罩字段和过渡选项

清除当前遮罩

• options?: TransformDefinitions.VisualEffectOptions - 过渡选项

应用或清除 CSS clip-path

scene.action([
    image.clip("inset(0 0 50% 0)", { duration: 200 }),
    image.clearClip({ duration: 0 }),
]);

• clipPath: React.CSSProperties["clipPath"] - CSS clip path 值
• options?: TransformDefinitions.VisualEffectOptions - 过渡选项

使用圆形 clip-path 显示或收起元素

• options?: TransformDefinitions.CircleRevealOptions | TransformDefinitions.CircleCloseOptions
• 常用选项：center、from、to、clearClip、duration、ease

使用方向擦除显示或隐藏元素

• options?: TransformDefinitions.WipeOptions
• 常用选项：direction、reverse、clearClip、duration、ease

应用或清除 CSS filter

• filter: React.CSSProperties["filter"] - 例如 blur(4px) 或 brightness(0.8)
• options?: TransformDefinitions.VisualEffectOptions - 过渡选项

应用 CSS backdrop-filter。适合制作玻璃感或背景模糊覆盖层

• backdropFilter: React.CSSProperties["backdropFilter"]
• options?: TransformDefinitions.VisualEffectOptions - 过渡选项

应用 CSS mix-blend-mode

• mixBlendMode: React.CSSProperties["mixBlendMode"]
• options?: TransformDefinitions.VisualEffectOptions - 过渡选项

对元素应用自定义变换

element.transform(new Transform(
/* 变换定义 */
));

• transform: Transform - 应用于元素的自定义变换，参见 Transform

让元素反复播放一个变换，直到有东西让它停下。

这一行不会等待。 这是它与 transform() 唯一的区别：transform() 是故事的一步，下一行要等它播完； 而 loop() 是元素自己带着的一个属性——设上之后故事继续往下走，动作在后面的一切之下一直跑着。

一个元素同一时刻只带一个变换，所以任何别的东西作用到它身上都会把它收回来：transform()、pos()、 zoom()、show()、hide() 等等都会结束循环，并从它当时所在的位置继续。不会结束它的有：玩家跳过或快进、 转场换图、切换场景，以及存档读档——读回来的存档会把循环装回去。

循环开始前元素所处的姿态，就是它要回到的地方，也是存档唯一记下的东西；中间那些帧从不落盘。

const breathe = Transform.create()
    .scaleY(1.015)
    .commit({ duration: 1900, ease: "easeInOut" });

scene.action([
    yuko.loop(breathe, { repeatType: "mirror" }),
    yuko.say`今天很安静。`,            // 她一边呼吸，这句一边播
    yuko.stopLoop({ duration: 300 }),
]);

• transform: Transform - 要重复的动作，参见 Transform。它必须已经 commit，这一点和 transform() 一样。如果不希望每次重复时画面跳一下，要么让它回到起点，要么传 repeatType: "mirror"。
• options?: LoopOptions - 重复的方式。
  • repeatType?: "loop" | "reverse" | "mirror" - 默认 "loop"。
  • repeatDelay?: number - 下一次重复开始前，保持最后一个姿态的毫秒数。默认 0。

结束元素的循环变换，并把它放回循环开始前的姿态。

与 loop() 不同，这一行会等待——因为它有一个明确的终点。不给时长时，元素在同一帧就回到位。 对没有在循环的元素调用它不做任何事。

yuko.stopLoop({ duration: 300, ease: "easeOut" });

• options?: LoopStopOptions - 元素如何从循环中退出。
  • duration?: number - 回到循环开始前那个姿态所花的毫秒数。默认 0。
  • ease?: EasingDefinition - 参见 Transform。

重载 1 / 3

立即显示元素

element.show();

重载 2 / 3

使用自定义变换显示元素

element.show({
    /* 变换定义 */
});

• options: Transform - 应用于元素的自定义变换，参见 Transform

重载 3 / 3

使用变换配置显示元素，将对元素应用一个 alpha: 1 的变换

element.show({
    duration: 1000,
    ease: "easeInOut",
});

• options: Partial<TransformDefinitions.CommonTransformProps> - 参见 TransformDefinitions.CommonTransformProps

重载 1 / 3

立即隐藏元素

element.hide();

重载 2 / 3

使用自定义变换隐藏元素

element.hide({
    /* 变换定义 */
});

• options: Transform - 应用于元素的自定义变换，参见 Transform

重载 3 / 3

使用变换配置隐藏元素，将对元素应用一个 alpha: 0 的变换

element.hide({
    duration: 1000,
    ease: "easeInOut",
});

• options: Partial<TransformDefinitions.CommonTransformProps> - 参见 TransformDefinitions.CommonTransformProps

自 0.30.0 起可用

把这个元素提到所在图层的最前面，盖在已经站在那里的一切之上。在下一个元素被提前之前它一直在前面。

• 返回链

scene.action([
    yukoSprite.bringToFront(),
    yuko.say`一直都是我。`,
]);