属性--veImageX-火山引擎

文档中心

导航

属性

最近更新时间：2024.07.19 19:49:48首次发布时间：2024.07.19 19:49:48

ViewerProps

组件属性。

类型

Omit<JSX.IntrinsicElements['img'], 'src' | 'width' | 'height' | 'loading' | 'srcSet' | 'ref'> & {
  width?: number;
  height?: number;
  src: string;
  layout?: LayoutType;
  loader?: ImageLoader;
  loading?: 'lazy' | 'eager';
  placeholder?: PlaceholderValue;
  quality?: number;
  formats?: typeof ValidFormat[number][];
  imageSizes?: number[];
  unoptimized?: boolean;
  lazyRoot?: React.RefObject<HTMLElement> | null;
  lazyBoundary?: string;
  errorDataURL?: string;
  error?: ReactNode;
  ssr?: boolean;
  ua?: string;
  objectFit?: ImgElementStyle['objectFit'];
  objectPosition?: ImgElementStyle['objectPosition'];
  onLoadingComplete?: OnLoadingComplete;
}

成员

名称	类型	描述
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`	布局方式，详见 LayoutType。
loader	`ImageLoader \| undefined`	图片 URL 拼接函数。当 `unoptimized` 取值为 `false` 时，必填。函数入参包含 src, width, quality, format 等参数，返回拼接处理参数后的 url。格式自适应和分辨率自适应能力均依赖该函数实现。格式自适应：结合浏览器支持性以及 `formats` 属性中指定的格式列表，选择最优的格式传递至函数的入参 `format`，函数返回相应格式的图片 url；分辨率自适应：结合图片所在容器大小、屏幕分辨率以及 `imageSizes` 属性中指定的图片分辨率列表，选择最合适的分辨率传递至函数的入参 `width`，函数返回相应分辨率的图片 url。
loading	`"lazy" \| "eager" \| undefined`	定义图片加载行为。 `lazy`：（默认）懒加载 `eager` ：立即加载
placeholder	`string \| undefined`	占位元素，详见 PlaceholderValue。
quality	`number \| undefined`	质量参数。默认值为 75，取值范围为[0, 100]。取值越低，图片越模糊。
formats	`("webp" \| "avif" \| "heic" \| "jpeg" \| "png")[] \| undefined`	自适应格式列表，结合 loader 方法实现格式自适应。取值如下所示： `webp` （默认） `avif` `jpeg` `png`
imageSizes	`number[] \| undefined`	图片尺寸列表，默认为[480, 750, 1080, 1366, 1920]，加载图片时会从该列表中选取最合适的图片大小。
unoptimized	`boolean \| undefined`	是否关闭图片优化。 `true`：关闭，关闭图片优化后将不再支持格式自适应、分辨率自适应能力。 `false`：（默认）开启。
lazyRoot	`RefObject<HTMLElement> \| null \| undefined`	用于图片懒加载配置，指向图片所在的容器元素。默认值为 null，指向当前视口。
lazyBoundary	`string \| undefined`	用于指定懒加载时触发图片渲染的边界，默认值为 `200px`。
errorDataURL	`string \| undefined`	自定义图片加载错误占位图，建议您传入 base64 编码的占位图。 `layout` 取值为 `raw` 时，暂不支持设置。
error	`ReactNode`	自定义错误样式，若默认的样式不符合要求，支持传入 ReactNode 完全自定义错误兜底。 `layout` 取值为 `raw` 时，暂不支持设置。
ssr	`boolean \| undefined`	当前是否为服务器端渲染（SSR）场景。 `true`：是 `false`：否
ua	`string \| undefined`	在 SSR 场景下，根据传入的用户代理（user agent）判断图片格式。
objectFit	`Property.ObjectFit \| undefined`	`layout` 取值为 `fill` 时，用于指定图片元素在容器中的适应方式，与 css 属性 object-fit 相同。
objectPosition	`Property.ObjectPosition<string \| number> \| undefined`	`layout` 取值为 `fill` 时，用于指定图片元素在容器中的位置，与 css 属性 object-position 相同。
onLoadingComplete	`OnLoadingComplete \| undefined`	图片加载后的回调函数，参数为图片实际的宽高，单位为 px。

ImageLoader

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

类型

(props: ImageLoaderProps) => string

示例

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

OnLoadingComplete

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

类型

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

ImageLoaderProps

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

类型

{
  src: string;
  width: number;
  quality: number;
  format: string;
  extra: {
    domain?: string;
    protocol?: ProtocolType;
    template?: string;
    templateWithoutParams?: string;
    params?: string[];
    suffix?: string;
    search?: string;
    origin: string;
  };
}

成员

名称	类型	描述
src	`string`	图片源 URL，满足公网可访问。不包含域名，例如 imagex-common/5b*******1b。
width	`number`	图片宽度，用于确定加载的图片尺寸。
quality	`number`	图片质量参数，用于确定加载的图片质量。
format	`string`	图片格式，用于确定加载的图片格式。

LayoutType

布局方式。

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

类型

typeof LayoutValues[number]

PlaceholderValue

占位元素。

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

类型

'skeleton' | 'empty' | string