Rive Canvas (Lazy Teleport) Alpha
🛑 This package is still in the Alpha test stage.
This package is still in the Alpha test stage and is not recommended for use in production. The API may change in the future, and there may be errors in the current version. Please use it with caution.
Introduce
Rive Canvas is a very special component. Unlike regular components, regular components refer to components in other Vue components in the form of direct <ComponentName />, while Rive Canvas (Lazy Teleport) introduces Rive animation into the page by adding specific tags to HTML with the <NuLazyTeleportRiveCanvas /> component referenced elsewhere.
When will such components need to be used?
- For VitePress or other static generators, not every document and frontmatter parameter supports rendering as a Vue component. If the Vue component is inserted directly in
v-html, it cannot be rendered. You need to use a component such as Rive Canvas (Lazy Teleport) to introduce Rive animation through a placeholder HTML tag until the page is loaded. - If you also use static generators like Astro and Rspress, you may find that inserting Vue components in Markdown is not supported. At this time, you can also use Rive Canvas (Lazy Teleport) Such a component.
Example
Installation
Install @nolebase/ui-rive-canvas to your project dependencies by running the following command:
ni @nolebase/ui-rive-canvaspnpm add @nolebase/ui-rive-canvasnpm install @nolebase/ui-rive-canvasyarn add @nolebase/ui-rive-canvasUsage
Register as a global component
First, you need to import the NuLazyTeleportRiveCanvas component in the Vue component and then register it as a global component:
import { NuLazyTeleportRiveCanvas } from '@nolebase/ui-rive-canvas';
app.component('NuLazyTeleportRiveCanvas', NuLazyTeleportRiveCanvas);Configure Vite
Since <NuLazyTeleportRiveCanvas /> depends on @rive-app/canvas. If you also use Vite as your bundler and development environment server, you need to add the following configuration to your vite.config.ts file like this:
import { defineConfig } from 'vite'
export default defineConfig(() => {
return {
optimizeDeps: {
include: [
// 添加这一行到你的 vite.config.ts 的 optimizeDeps.include 数组中
'@nolebase/ui-rive-canvas > @rive-app/canvas',
],
},
}
})For more information about why configure this, please refer to the Dep Optimization Options | Vite documentation.
Also, for Rive, the file format .riv used by Rive is not the default file format supported by Vite. The file format used by Rive .riv is also not the default file format supported by Vite, so you may need to add the following configuration:
// .vitepress/config.ts
import { defineConfig } from 'vite'
export default defineConfig(() => {
return {
assetsInclude: [
'**/*.riv',
],
}
})For more information about why configure this, please refer to the Shared Options | Vite documentation.
Import and use in entry file
Then add the <NuLazyTeleportRiveCanvas /> component in the entry file (App.vue):
<script setup lang="ts">
import { NuLazyTeleportRiveCanvas } from '@nolebase/ui-rive-canvas'
</script>
<template>
<NuLazyTeleportRiveCanvas />
</template>Or add <NuLazyTeleportRiveCanvas /> component into layout-top slot you can specify in theme/index.ts of VitePress:
// .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)
]
})
}
}Adding placeholder elements for Rive Canvas in HTML will render the placeholder tag of Canvas
Next, wherever raw HTML rendering (v-html) is supported, just add the following attribute to the tag that is expected to be rendered as a Canvas:
class="rive-canvas"data-rive-canvas="true"data-rive-src="<rive file path>"
Attention
Since Rive Canvas (Lazy Teleport) is introduced via HTML tags, any .riv Rive files referenced by Rive Canvas (Lazy Teleport) will not be automatically processed by Vite, so you will need to manually place the Rive file in a location such as public folder. automatically processed by Vite, so you'll need to manually place the Rive file in a folder such as public and fill in the data-rive-src attribute with the correct path.
For example:
<span
class="rive-canvas"
data-rive-canvas="true"
data-rive-src="/icons/star-emoji-animated.riv"
></span>Customization
Adjust the size
By default, Rive Canvas creates a 500 x 500 canvas. You can customize the size of the canvas by adding the two attributes:
data-rive-canvas-props-canvas-widthdata-rive-canvas-props-canvas-width
25 x 251000 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>References
Props
data-rive-canvas-props-canvas-width
The width of the <canvas> itself.
Description: It can be understood as the resolution, which is independent of the CSS width. The size of this value will affect the resolution of the animation rendered on the canvas, but at the same time, if the set value is too large, it will cause the rendering performance of the animation to decrease.
Default value: 500
data-rive-canvas-props-canvas-height
The height of the <canvas> itself.
Description: It can be understood as the resolution, which is independent of the CSS height. The size of this value will affect the resolution of the animation rendered on the canvas, but at the same time, if the set value is too large, it will cause the rendering performance of the animation to decrease.
Default value: 500
data-rive-canvas-props-width
The CSS min-width of the <canvas>.
Description: This value will affect the CSS width of the <canvas>, but will not affect the resolution of the animation rendered on the canvas. It can be adjusted according to the requirements of different locations. Just treat it as a normal CSS min-width property.
Default value: 16px
data-rive-canvas-props-height
The CSS min-height of the <canvas>.
Description: This value will affect the CSS height of the <canvas>, but will not affect the resolution of the animation rendered on the canvas. It can be adjusted according to the requirements of different locations. Just treat it as a normal CSS min-height property.
Default value: 16px
data-rive-canvas-props-padding-top
The CSS padding-top of the <canvas>.
Description: Generally speaking, the rendering of Rive and Lottie animations should be full-screen, which means that in most cases, the animation will occupy the entire canvas. However, if you need to add some extra space around the animation, you can adjust it with this attribute.
Default value: 4px
data-rive-canvas-props-padding-bottom
The CSS padding-bottom of the <canvas>.
Description: Generally speaking, the rendering of Rive and Lottie animations should be full-screen, which means that in most cases, the animation will occupy the entire canvas. However, if you need to add some extra space around the animation, you can adjust it with this attribute.
Default value: 4px
data-rive-canvas-props-padding-left
The CSS padding-left of the <canvas>.
Description: Generally speaking, the rendering of Rive and Lottie animations should be full-screen, which means that in most cases, the animation will occupy the entire canvas. However, if you need to add some extra space around the animation, you can adjust it with this attribute.
Default value: 4px
data-rive-canvas-props-padding-right
The CSS padding-right of the <canvas>.
Description: Generally speaking, the rendering of Rive and Lottie animations should be full-screen, which means that in most cases, the animation will occupy the entire canvas. However, if you need to add some extra space around the animation, you can adjust it with this attribute.
Default value: 4px
Annotation
The cute animated emojis are Animated Emoji authored by wonderful Telegram team.
These Emoji can be directly downloaded by dragging the Emoji from Telegram into the browser. However, the downloaded file is a file with the extension .tgs, but fortunately, the community has powerful contributors who have made a TGS to Lottie conversion tool Lottie/TGS Editor, which can be imported by importing the .tgs file, then export it as a Lottie .json file, and then convert the Lottie .json file to a Rive .riv file through the Rive online editor.
Fun fact
In fact, the .tgs file is a .zip compression format derived from the AE plugin bodymovin over Telegram's fork based on the original one. There's actually a Lottie JSON file inside, which is why converting through Lottie/TGS Editor is possible.
If you want to know which Animated Emoji are available, you can check them out through Animated Telemoji - Telegram or Animated Emoji Pack.
Of course, everyone loves cute Emoji, and Microsoft's Fluent Emoji is also a very interesting Emoji. Someone has also made an animated version of the Emoji for them. You can check them out through the Animated Fluent Emojis - Microsoft list.
Neko