ImageLoaderProps

类型：interface

Loader 函数返回的参数，用于拼接最终加载的图片 URL。

src

类型：string

图片 URL，满足公网可访问。不包含域名，例如 imagex-common/5b*******1b。

width

类型：number

图片宽度，用于确定加载的图片尺寸。

quality

类型：number

图片质量参数，用于确定加载的图片质量。

format

类型：string

图片格式，用于确定加载的图片格式。

ImageLoader

图片 URL 拼接函数，该函数根据传入的参数（src、width、quality 和 format）生成图片的 URL。

类型

(props: ImageLoaderProps) => string

示例

// 域名/src~模板:模板参数:q质量参数.图片格式
const myLoader: ImageLoader = ({ src, width, quality, format }) => {
  return `//www.example.com/${src}~tplv-serviceid-resize:${width}:q${quality}.${format}`
}

PlaceholderValue

占位元素。

• empty: （默认）无占位
• skeleton： 骨架屏占位
• 自定义占位图，例如：data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAMAAAC67D+PAAAABlBMVEW/0v/K2/+wPdJoAAAAI0lEQVQImWNghAMGEGZggDAZIIARxgCxGQgAFG1QnVBzoQAACT8AKbEcZzAAAAAASUVORK5CYII=

类型

'skeleton' | 'empty' | (string & {})

OnLoadingComplete

图片加载后的回调函数，参数为图片实际的宽高，单位为 px。

类型

(result: {
  naturalWidth: number
  naturalHeight: number
}) => void

ViewerProps

类型：interface

width

类型：number | undefined

图片宽度。仅当 layout 取值为 fill 或 raw 时选填，其他布局为必填。

• 在 intrinsic 或 fixed 布局下：表示设置图片渲染宽度
• 在 fill 或 responsive 布局下：表示设置图片宽高比

height

类型：number | undefined

图片高度。仅当 layout 取值为 fill 或 raw 时选填，其他布局为必填。

• 在 intrinsic 或 fixed 布局下：表示设置图片渲染高度
• 在 fill 或 responsive 布局下：表示设置图片宽高比

src

类型：string

图片源 URL，满足公网可访问。不包含域名，例如 imagex-common/5b*******1b。

layout

类型："fill" | "fixed" | "intrinsic" | "responsive" | "raw" | undefined

布局方式。

• intrinsic：（默认）图片宽度自适应容器，最大宽度为组件中设置的图片宽度，图片高度按照原图比例进行缩放。
• responsive：图片宽度完全自适应容器，图片高度按照原图比例进行缩放。
• fixed：固定的图片宽高。
• fill：填充容器，结合 objectFit、objectPosition 可实现多种填充模式。
• raw：移除外层布局相关 dom，只保留纯净的 <img> 标签。

loader

类型：ImageLoader | undefined

图片 URL 拼接函数。

loading

类型："lazy" | "eager" | undefined

定义图片加载行为。

• lazy：（默认）懒加载
• eager：立即加载

placeholder

类型：PlaceholderValue | undefined

占位元素。

errorDataURL

类型：string | undefined

自定义图片加载错误占位图，建议您传入 base64 编码的占位图。

quality

类型：number | undefined

质量参数。默认值为 75，取值范围为[0, 100]。取值越小，压缩率越高，图片越模糊。

formats

类型：("webp" | "avif" | "heic" | "jpeg" | "png")[] | undefined

自适应格式列表，结合 loader 方法实现格式自适应。

• webp （默认）
• avif
• jpeg
• png

注意

图像格式自适应是一种图像压缩方式，SDK 会根据配置自动进行格式压缩并输出对应格式图像。

• 指定 ['webp']时，表示仅支持 webp 格式自适应；
• 若指定为 [avif, webp] 则表示优先 avif 格式自适应，其次是 webp 格式自适应，最后用原图格式兜底。

imageSizes

类型：number[] | undefined

图片尺寸列表，默认为[480, 750, 1080, 1366, 1920]，加载图片时会从该列表中选取最合适的图片大小。

注意

传入空数组 [] 情况下组件会计算图片或其所在容器大小，直接拉取相应大小的图片（若设置为空数组在一定程度上会降低 cdn 的命中率）。

unoptimized

类型：boolean | undefined

是否关闭图片优化。

• true：关闭，关闭图片优化后将不再支持格式自适应、分辨率自适应能力。
• false：（默认）开启。

lazyRoot

类型：HTMLElement | null | undefined

图片懒加载配置，指向图片所在的容器元素。默认值为 null，指向当前视口。

lazyBoundary

类型：string | undefined

懒加载时触发图片渲染的边界，默认值为 200px。

objectFit

类型：string | undefined

当 layout 取值为 fill 时，用于指定图片元素如何适应容器，与 css 属性 object-fit 相同。

objectPosition

类型：string | undefined

当 layout 取值为 fill 时，用于指定图片元素在容器内的位置，与 css 属性 object-position 相同。

onLoadingComplete

类型：OnLoadingComplete | undefined

图片加载后的回调函数，参数为图片实际的宽高，单位为 px。

plugins

类型：string[] | undefined

启用的插件名，当前仅支持取值 decrypt，表示解密插件。

pluginProps

类型：Record<string, any>

插件配置，key 为插件名，value 为对应插件配置。

注意

解密插件配置：

• pem：您在 veImageX 控制台获取的公钥，用于解密对称密钥。
• key：您在上传 SDK 用于加密文件的对称密钥，用于解密加密后文件。