跳到主要内容
中文系列课

布局

适配模式​

在编辑器中创作的 Rive 图形不一定匹配运行时渲染的容器大小。我们需要确定这种情况下的行为，因为没有一种尺寸适合所有情况。

解决方案是选择适配模式。这在容器上指定，控制 Rive 如何缩放。

  • Layout：使用 Rive 布局引擎将响应式布局应用于画板，匹配容器尺寸。这需要画板在设计时就考虑了布局。有关如何使用此选项的更多信息，请参见响应式布局。
  • Contain：（默认） 保持宽高比并缩放画板，使其较大尺寸匹配容器的对应尺寸。如果宽高比不相同，在较短尺寸的轴上会留出空间。
  • ScaleDown：保持宽高比，当画板大于容器时行为与 Contain 类似。否则，使用画板的原始尺寸。
  • Cover：保持宽高比并缩放画板，使其较小尺寸匹配容器的对应尺寸。如果宽高比不相同，在较大尺寸的轴上会裁剪画板。
  • FitWidth：保持宽高比并缩放画板宽度以匹配容器宽度。如果画板和容器的宽高比不匹配，会导致垂直裁剪或垂直轴上留出空间。
  • FitHeight：保持宽高比并缩放画板高度以匹配容器高度。如果画板和容器的宽高比不匹配，会导致水平裁剪或水平轴上留出空间。
  • Fill：不保持宽高比，拉伸到容器尺寸。
  • None：不缩放。使用画板的原始尺寸。对于任一维度，如果画板的尺寸较大，会被裁剪。如果较小，会留出空间。

对齐​

在所有除 Layout 和 Fill 之外的选项中，Rive 图形可能在其容器内被裁剪或留出空间。对齐决定内容如何在容器内对齐。以下选项可用：

  • TopLeft
  • TopCenter
  • TopRight
  • CenterLeft
  • Center （默认）
  • CenterRight
  • BottomLeft
  • BottomCenter
  • BottomRight

边界​

此运行时通过提供最小和最大 x、y 坐标来公开 Rive 内容渲染区域的边界尺寸。这些坐标相对于容器，且必须全部提供。它们将覆盖对齐设置。

  • minX
  • minY
  • maxX
  • maxY

应用适配模式​

使用 Layout 对象来配置 Fit 和 Alignment。所有枚举选项请参见适配模式和对齐。


// 填充 canvas，必要时裁剪 Rive
let layout = new rive.Layout({
    fit: rive.Fit.Cover,
});

// 适配宽度并与 canvas 顶部对齐
layout = new rive.Layout({
    fit: rive.Fit.FitWidth,
    alignment: rive.Alignment.TopCenter,
});

// 将 Rive 内容约束在 canvas 中的 (minX, minY), (maxX, maxY) 内
layout = new rive.Layout({
    fit: rive.Fit.Contain,
    minX: 50,
    minY: 50,
    maxX: 100,
    maxY: 100,
});

const riveInstance = new rive.Rive({
    src: 'https://cdn.rive.app/animations/vehicles.riv',
    canvas: document.getElementById('canvas'),
    layout: layout,
    autoplay: true
});

// 更新布局
riveInstance.layout = new rive.Layout({ fit: rive.Fit.Fill });

响应式布局​

Rive 的布局功能允许你设计可调整大小的画板，具有内置的响应式行为，从编辑器配置。在运行时确保适配模式设置为 Layout，画板将根据编辑器中定义的约束调整大小以填充其容器。

可选的，你可以提供 布局缩放因子 来乘以内容的缩放比例。这允许你微调容器内的视觉大小。此属性仅在将 Fit 模式设置为 Layout 时适用。

有关更多编辑器信息以及如何配置图形，请参阅布局概述。

步骤

  1. 将 fit 设置为 Fit.Layout —— 当调用 resizeDrawingSurfaceToCanvas() 时，这将自动缩放和调整画板大小以匹配 canvas 大小。
  2. 可选设置 layoutScaleFactor 以手动控制画板大小（缩放因子）。
  3. 订阅 window.onresize 并调用 resizeDrawingSurfaceToCanvas() 以在 canvas 和窗口变化时调整画板大小。
  4. 订阅 设备像素比 变化并调用 resizeDrawingSurfaceToCanvas() 以确保画板在各种屏幕密度上正确更新。例如，在不同设备像素比的多个显示器之间拖动窗口时。
  const rive = new Rive({
    src: "your-rive-file.riv",
    autoplay: true,
    canvas: riveCanvas,
    layout: new Layout({
      fit: Fit.Layout,
      // layoutScaleFactor: 2, // 当使用 `Fit.Layout` 时，布局以 2 倍缩放。这允许你根据需要调整布局大小。
    }),
    stateMachines: ["State Machine 1"],
    onLoad: () => {
      computeSize();
    },
  });

  function computeSize() {
    rive.resizeDrawingSurfaceToCanvas();
  }

  // 订阅窗口大小变化并更新调用 `resizeDrawingSurfaceToCanvas`
  window.onresize = computeSize;

  // 订阅 devicePixelRatio 变化并调用 `resizeDrawingSurfaceToCanvas`
  window
    .matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`)
    .addEventListener("change", computeSize);

TypeScript API 接口​

这些类型从 @rive-app/canvas（或你打包的 rive 全局变量）导出：

export interface LayoutParameters {
  fit?: Fit;
  alignment?: Alignment;
  layoutScaleFactor?: number;
  minX?: number;
  minY?: number;
  maxX?: number;
  maxY?: number;
}

export class Layout {
  constructor(params?: LayoutParameters);
  readonly fit: Fit;
  readonly alignment: Alignment;
  readonly layoutScaleFactor: number;
  readonly minX: number;
  readonly minY: number;
  readonly maxX: number;
  readonly maxY: number;
  copyWith(partial: LayoutParameters): Layout;
}