@cryptonatty/nft-viewer

NFT VIEWER

一个用于浏览 nft 内容的 web component。

支持格式：

• 图片 ⭕
• 视频 ⭕
• 音频 ❌ (待开发)
• 模型 ⭕
• 帧动画 ⭕

Usage

可以通过 script 标签方式引入

<script src="//s1.hdslb.com/bfs/seed/pangu/bnft/nft-viewer/nft-viewer.min.js"></script>

npm 包方式引入

npm i @bilibili/nft-viewer

import '@bilibili/nft-viewer'

不同内容类型的代码示例：

<!-- 图片 -->
<nft-viewer
  type="image"
  src="{{imageUrl}}"
  title="{{title}}"
  alt="{{alt}}"
></nft-viewer>

<!-- 视频 -->
<nft-viewer
  type="video"
  controls
  src="{{videoUrl}}"
  poster="{{posterUrl}}"
></nft-viewer>

<!-- 音频 -->
<nft-viewer
  type="audio"
  controls
  muted
  src="{{audioUrl}}"
  poster="{{posterUrl}}"
></nft-viewer>

<!-- 模型 -->
<nft-viewer
  type="model"
  src="{{modelUrl}}"
  poster="{{posterUrl}}"
></nft-viewer>

<!-- 帧动画 -->
<nft-viewer
  type="animate"
  src="{{雪碧图地址}}"
  frames="{{frameString, 格式见下表}}"
  duration="{{播放时间}}"
  delay="{{延迟时间}}"
></nft-viewer>

属性列表

属性名称	支持类型	作用
type	所有	指定 nft 内容的类型，枚举值：image, video, audio, model, animate
src	所有	指定 nft 内容源地址，音频和视频类型将优先使用 source 属性
title	image video audio	同 html 元素 title 属性
alt	所有	同 img 元素 alt 属性
poster	video audio model	图片封面
controls	video audio	同 video, audio 元素 controls 属性
autoplay	video audio	同 video, audio 元素 autoplay 属性
source	video audio	源地址，支持以分号分割指定多个源地址；没有 source 属性会使用 src 属性值
muted	video audio	是否静音，默认 false
frames	animate	一个指定每帧偏移值的字符串，格式如：x,y;x1,y1;x2,y2
duration	animate	动画一轮播放的持续时长，动画默认重复播放，单位毫秒
delay	animate	动画播放前的延迟时间，单位毫秒
backgroundSize	animate	用于缩放雪碧图，取值的语法同 background-size

方法列表

方法名称	支持类型	参数	作用
play	video audio	-	播放视频/音频
stop	video audio	-	暂停视频/音频

属性监听

nft-viewer 对一些特性属性进行了监听，当这些属性发生变化时，会产生不同的效果。

监听属性和效果如下：

属性	image	video	audio	model	animate
type	重新执行渲染逻辑	同左边	同左边	同左边	同左边
src	替换图片	替换视频源	-	替换模型	替换雪碧图
source	-	替换视频源	-	-	-
poster	-	替换封面图	-	替换封面图（模型加载完成后无效）	-
duration	-	-	-	-	调整动画一轮播放持续时间
delay	-	-	-	-	调整动画播放延时时间，动画将重置从第一帧开始

animate 类型的详细说明

frames 字段说明

由于 web component 仅支持字符串传递 props，所以通常用于表示播放帧顺序的数组需要转换为字符串传入 frames 属性。

举例，播放帧的顺序为

[
  {x: 0, y: 0}, {x: 120, y: 0}, {x: 240, y: 0},
  {x: 0, y: 120}, {x: 120, y: 120}, {x: 240, y: 120},
  {x: 0, y: 240}, {x: 120, y: 240}, {x: 240, y: 240},
]

那么转换为 frameString 则是

"0,0;120,0;240,0;0,120;120,120;240,120;0,240;120,240;240,240"

转换方法代码：

function stringifyFramesArray (arr = []) {
  const result = [];

  arr.forEach(item => {
    const {x, y} = item || {};
    result.push(`${x},${y}`);
  });

  return result.join(';');
}

function parseFramesString (str = '') {
  const result = [];
  const splited = str.split(';');

  splited.forEach(item => {
    const xy = item.split(',');
    result.push({
      x: xy[0] || 0,
      y: xy[1] || 0,
    });
  });
  
  return result;
}

注意，目前必须通过 frames 属性声明雪碧图的帧顺序，暂未开发采用默认帧顺序进行播放的功能。

duration 的缺省策略

nft-viewer 支持不传入 duration 或者传 0，此时每一帧的播放时间约为 41ms，即约 1 秒可播放 24 帧。

高倍图的解决方案

在移动端下通常为了确保视觉高清而需要使用 2x、3x 的图像，nft-viewer 目前并没有自带的解决方案。需要开发中手动处理，比如使用一个外部容器对 nft-viewer 进行缩放或者手动指定 background-size。

scale 方式

比如在 dpr 为 2 的屏幕下，动画视口大小为 100x100，图片每一帧大小为 200x200，那么需要对 nft-viewer 进行 scale(.5) 的调整。

<div class="container">
  <div class="scale"> <!-- 用于设置 scale(.5) 样式 -->
    <div style="width: 200px; height: 200px"> <!-- 设为图片每一帧的大小 --> 
      <nft-viewer />
    </div>
  </div>
</div>

此方式适合不确定雪碧图高宽的场景下使用。

background-size 方式

比如在 dpr 为 2 的屏幕下，动画视口大小为 100x100，并已知图片大小为 600x600，每一帧大小为 200x200，那么需要对 nft-viewer 设置 backgroundSize="300px"。

<!-- 帧动画 -->
<nft-viewer
  type="animate"
  ...
  backgroundSize="300px"
></nft-viewer>

==========

THANKS