Rive Canvas（懒 Teleport） Alpha

字数

2230 字

阅读时间

10 分钟

🛑 此包仍处于 Alpha 测试阶段

此包仍处于 Alpha 测试阶段，不建议在生产中使用。未来 API 可能会发生变化，当前版本可能存在错误。请谨慎使用。

介绍

Rive Canvas（懒 Teleport）是一种极为特殊的组件，和常规的组件不同，常规的组件使用直接的 <ComponentName /> 的形式在其他的 Vue 组件中引用组件，而 Rive Canvas（懒 Teleport）则是通过在 HTML 中添加特定的标签，搭配其他地方引用的 <NuLazyTeleportRiveCanvas /> 组件，来实现在页面中引入 Rive 动画。

什么时候会需要使用到这样的组件？

1. 对于 VitePress 或者其他静态生成器而言，并不是每个文档和 frontmatter 的参数都是支持渲染为 Vue 组件的，如果直接在 v-html 中插入 Vue 组件，是无法渲染的，这时候就需要使用到 Rive Canvas（懒 Teleport）这样的组件，通过一个占位符 HTML 标签，等到页面加载完成后再引入 Rive 动画。
2. 如果你也使用像是 Astro 和 Rspress 这样的静态生成器，你可能会发现在 Markdown 中插入 Vue 组件是不被支持的，这时候也可以使用 Rive Canvas（懒 Teleport）这样的组件。

示例

安装

运行以下命令，将 @nolebase/ui-rive-canvas 安装到项目依赖项中：

@antfu/ni

ni @nolebase/ui-rive-canvas

pnpm

pnpm add @nolebase/ui-rive-canvas

npm

npm install @nolebase/ui-rive-canvas

yarn

yarn add @nolebase/ui-rive-canvas

用法

注册为全局组件

首先需要在 Vue 组件中引入 NuLazyTeleportRiveCanvas 组件，然后注册为全局组件：

import { NuLazyTeleportRiveCanvas } from '@nolebase/ui-rive-canvas';

app.component('NuLazyTeleportRiveCanvas', NuLazyTeleportRiveCanvas);

配置 Vite

由于 <NuLazyTeleportRiveCanvas /> 底层依赖于 @rive-app/canvas，如果您也使用 Vite 作为打包器和开发环境服务器，则需要像这样在 vite.config.ts 文件中添加以下配置：

import { defineConfig } from 'vite'

export default defineConfig(() => {
  return {
    optimizeDeps: { 
      include: [ 
        // 添加这一行到你的 vite.config.ts 的 optimizeDeps.include 数组中
        '@nolebase/ui-rive-canvas > @rive-app/canvas', 
      ], 
    }, 
  }
})

有关为何要这样配置的更多信息，请参阅 Dep Optimization Options | Vite 文档。

另外，对于 Rive 而言，Rive 所使用的文件格式 .riv 也并不是 Vite 所支持的默认文件格式，所以你可能还需要添加以下配置：

// .vitepress/config.ts
import { defineConfig } from 'vite'

export default defineConfig(() => {
  return { 
    assetsInclude: [ 
      '**/*.riv', 
    ], 
  } 
})

有关为何要这样配置的更多信息，请参阅 Shared Options | Vite 文档。

在入点添加组件

然后在入点（App.vue）中添加 <NuLazyTeleportRiveCanvas /> 组件：

<script setup lang="ts">
import { NuLazyTeleportRiveCanvas } from '@nolebase/ui-rive-canvas'
</script>

<template>
  <NuLazyTeleportRiveCanvas />
</template>

或者 VitePress 的 theme/index.ts 的 layout-top 插槽中添加 <NuLazyTeleportRiveCanvas /> 组件：

// .vitepress/theme/index.ts
import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import { NuLazyTeleportRiveCanvas } from '@nolebase/ui-rive-canvas'

export default {
  extends: DefaultTheme,
  Layout() {
    return h(DefaultTheme.Layout, null, {
      'layout-top': () => [ 
        h(NuLazyTeleportRiveCanvas) 
      ] 
    })
  }
}

在 HTML 中添加 Rive Canvas 会渲染 Canvas 的占位符标签

接下来，在任何一个支持 HTML 原始渲染的地方，为期望渲染为 Canvas 的标签添加以下属性即可：

• class="rive-canvas"
• data-rive-canvas="true"
• data-rive-src="<rive 文件路径>"

注意

由于 Rive Canvas（懒 Teleport）是通过 HTML 标签来引入的，所以任何 Rive Canvas（懒 Teleport）所引用的 .riv Rive 文件都无法自动地被 Vite 所处理，所以你需要手动将 Rive 文件放置到诸如 public 文件夹中，并在 data-rive-src 属性中填写正确的路径。

比如这样：

<span
  class="rive-canvas"
  data-rive-canvas="true"
  data-rive-src="/icons/star-emoji-animated.riv"
></span>

自定义

调整大小

默认情况下，Rive Canvas 会创建一个 500 x 500 的画布。你可以通过添加

• data-rive-canvas-props-canvas-width
• data-rive-canvas-props-canvas-width

这两个属性来自定义画布的大小。

低清 25 x 25 像素

超高清 1000 x 1000 像素

<span
  class="rive-canvas"
  data-rive-canvas="true"
  data-rive-src="/icons/star-emoji-animated.riv"
  data-rive-canvas-props-canvas-width="25"
  data-rive-canvas-props-canvas-height="25"
>
</span>

参考

参数

data-rive-canvas-props-canvas-width

含义：<canvas> 本身的宽度。

介绍：可以理解为分辨率，与 CSS 宽度无关，这个数值的大小会影响到画布上渲染的动画的分辨率，但与此同时如果设置的数值过大，会导致动画的渲染性能下降。

默认值：500

data-rive-canvas-props-canvas-height

含义：<canvas> 本身的高度。

介绍：可以理解为分辨率，与 CSS 高度无关，这个数值的大小会影响到画布上渲染的动画的分辨率，但与此同时如果设置的数值过大，会导致动画的渲染性能下降。

默认值：500

data-rive-canvas-props-width

含义：<canvas> 的 CSS min-width。

介绍：这个数值会影响到 <canvas> 的 CSS 宽度，但不会影响到画布上渲染的动画的分辨率。可以根据不同位置的需求来调整。当作是普通的 CSS 的 min-width 属性就好了。

默认值：16px

data-rive-canvas-props-height

含义：<canvas> 的 CSS min-height。

介绍：这个数值会影响到 <canvas> 的 CSS 高度，但不会影响到画布上渲染的动画的分辨率。可以根据不同位置的需求来调整。当作是普通的 CSS 的 min-height 属性就好了。

默认值：16px

data-rive-canvas-props-padding-top

含义：<canvas> 的 CSS padding-top。

介绍：通常而言，Rive 和 Lottie 动画的渲染应该是全画幅的，意味着绝大多数情况下，动画都会占满整个画布。但是，如果你需要在动画周围添加一些额外的空白，可以通过这个属性来调整。

默认值：4px

data-rive-canvas-props-padding-bottom

含义：<canvas> 的 CSS padding-bottom。

介绍：通常而言，Rive 和 Lottie 动画的渲染应该是全画幅的，意味着绝大多数情况下，动画都会占满整个画布。但是，如果你需要在动画周围添加一些额外的空白，可以通过这个属性来调整。

默认值：4px

data-rive-canvas-props-padding-left

含义：<canvas> 的 CSS padding-left。

介绍：通常而言，Rive 和 Lottie 动画的渲染应该是全画幅的，意味着绝大多数情况下，动画都会占满整个画布。但是，如果你需要在动画周围添加一些额外的空白，可以通过这个属性来调整。

默认值：4px

data-rive-canvas-props-padding-right

含义：<canvas> 的 CSS padding-right。

介绍：通常而言，Rive 和 Lottie 动画的渲染应该是全画幅的，意味着绝大多数情况下，动画都会占满整个画布。但是，如果你需要在动画周围添加一些额外的空白，可以通过这个属性来调整。

默认值：4px

注解

在本篇文档中所使用的是来自 Telegram 的 Animated Emoji。

这些 Emoji 可以通过直接拖动 Telegram 中的 Emoji 到浏览器中直接下载。不过下载到的文件是拓展名为 .tgs 的文件，好在社区有厉害的伙伴给制作了 TGS 到 Lottie 的转换工具 Lottie/TGS Editor，可以通过导入 .tgs 文件，然后导出为 Lottie 的 .json 文件，再将 Lottie .json 文件通过 Rive 的线上编辑器转换为 Rive 的 .riv 文件。

有趣的事实

其实 .tgs 文件是 Telegram 基于 bodymovin 所制作的 AE 插件 bodymovin Fork 和修改而来的 .zip 压缩格式^[1]，内部其实就是 Lottie JSON 文件，这也是为什么可以通过 Lottie/TGS Editor 来转换的原因。

如果你想要了解都有哪些 Animated Emoji，可以通过 Animated Telemoji - Telegram 或者 Animated Emoji Pack 来查看。

当然，可爱的 Emoji 大家都喜欢，Microsoft 的 Fluent Emoji 也是非常有趣的 Emoji，也有人为他们制作了动画版本的 Emoji，你可以通过 Animated Fluent Emojis - Microsoft 列表查看。

贡献者

Neko

页面历史

最后编辑于 15 天前

查看完整历史

a77cb30-feat(index): new plugin vitepress-plugin-index (#328)

a9cf2cd-refactor(ui): split rive-canvas and asciinema from ui package as standalone packages (#229)

f32df0c-fix(ui): incorrect style exports (#181)

021e189-feat(ui): added more components (#138)

47ab3a5-docs(ui): i18n for label texts

1c05b47-fix(ui): incorrectly overrided default options (#135)

263f7e0-docs(ui): added detailed documentations for NuLazyTeleportRiveCanvas with twoslash support

---

1. https://github.com/LottieFiles/tgskit/issues/2#issuecomment-1220326893 ↩︎