Lynx
指引
API
博客
贡献
指引
API
博客
贡献
简体中文

lynx: requestResourcePrefetch() static method

  • 该 API 用于前端主动发起 CDN 资源的预加载，目前只支持 image, video, audio 三种资源类型。
  • 预加载的资源并不会通过此 API 返回给前端，而是保留在内存或磁盘中。因此预加载完成后，需要通过一个唯一的 key 给组件指定资源：
    • image 资源的 key 与其预加载时的 uri 参数一致。渲染时，将这个 key 传给 <image> 组件的 src 属性，使得组件能够找到该资源。

语法

requestResourcePrefetch(data: object, callback: (res: object) => void) : void;

参数

data

一个描述了所有要预加载的资源详情的合集，它的 key 定义如下：

  • data：类型 array，array 内部每个 item 对应一个资源。每个 item 内的 key 定义如下
    • uri：类型 string，表示资源的 CDN 地址。
    • type：类型 string，表示资源的类型，支持的资源类型定义如下
      • image：图片资源（iOS 需要打开 Image 组件的 trailNewImage 开关才能预加载图片）
      • video：视频资源
      • audio：音频资源
    • params（可选）：资源预加载的自定义控制参数，支持的参数如下
      • priority（可选）：仅用于 image 类型的资源。表示网络请求优先级。如果请求优先级为 high，那么在图片库预加载这些图片时，其他的图片的请求会被阻塞等待，可能导致其他图片的展示变慢。所以如果预加载的这些图片如果不是马上需要展示的，可以把优先级调低。支持的选项如下
        • high：高优先级
        • medium：中优先级
        • low：低优先级，这是默认值
      • cacheTarget（可选）：仅用于 image 类型的资源。表示资源保存的形式。支持的选项如下
        • disk：资源预加载完成后保存于磁盘，这是默认值。
        • bitmap：资源预加载后解码成 bitmap 保存于内存。（** 注：现在 Android bitmap 缓存暂不能生效 **）
      • preloadKey：仅用于 video, audio 类型的资源。表示标识该资源的唯一的 key。渲染 <view-engine> 组件时，需要为其指定这个 key，这样组件才能找到预加载的资源缓存。必选参数。
      • size（可选）：仅用于 video 类型的资源。表示预加载的尺寸大小，默认值为 500 * 1024（字节）

callback

API 执行完成或失败后调用的回调函数。它的回参内部定义如下：

  • code：类型 number，状态码，它可能取值如下
    • 0：成功
    • 11001：参数错误
  • msg：类型 string，全局错误信息
  • details：类型 array，里面每个 detail 表示一个资源的预加载状态详情，detail 内部定义如下
    • code：类型 number，状态码，它可能取值如下
      • 0：成功
      • 11001：参数错误
    • msg：类型 string，错误信息
    • uri：类型 string，表示资源的 CDN 地址。
    • type：类型 string，表示资源的类型，资源类型定义如下
      • image：图片资源
      • video：视频资源
      • audio：音频资源

返回值

无（undefined）。

异常

  • 当出现参数错误时，code 会返回 11001 错误码，并且在 msg 中有详细错误信息。

示例

import { useState, useEffect } from '@lynx-js/react';

function Page() {
  const [show, setShow] = useState(false);

  useEffect(() => {
    // 在页面 DidMount 时我们提前发起资源预加载
    // 我们需要预加载一批资源，包括两张图片和两段视频。
    // 首先准备好资源参数，给图片指定 priority 和 cacheTarget，给视频指定必需的 preloadKey。
    let resData = [
      {
        uri: 'https://xxxxx1.jpg',
        type: 'image',
        params: { priority: 'high', cacheTarget: 'disk' },
      },
      {
        uri: 'https://xxxxx2.jpg',
        type: 'image',
        params: { cacheTarget: 'bitmap' },
      },
      {
        uri: 'https://zzzzz1.mp4',
        type: 'video',
        params: { preloadKey: 'zzzzz1' },
      },
      {
        uri: 'https://zzzzz2.mp4',
        type: 'video',
        params: { preloadKey: 'zzzzz2' },
      },
    ];

    // 调用 requestResourcePrefetch 发起预加载
    lynx.requestResourcePrefetch?.(
      {
        data: resData,
      },
      (res) => {
        if (res.code == 0) {
          console.log('success!');
        } else {
          console.log('fail! ', res.msg);
        }
        console.log(
          'prefetch status of each resource:',
          JSON.stringify(res.details),
        );
      },
    );
  }, []);

  const handleTap = () => {
    // 通过setShow改变show状态，控制图片、视频的展示
    setShow(!show);
  };

  return (
    <view onTap={handleTap}>
      {/* 根据 show 状态来决定是否展示图片，注意这里 src 是上述的唯一的 key，这里应该保持 src 和预加载时一致 */}
      {show && <image src="https://xxxxx1.jpg" />}
      {show && <image src="https://xxxxx2.jpg" />}
      {/* 根据 show 状态来决定是否展示视频，注意这里 preload-key 是上述唯一的 key，这里应该保持 preload-key 和预加载时一致 */}
      {show && <view-pro src="https://zzzzz1.mp4" preload-key="zzzzz1" />}
      {show && <view-pro src="https://zzzzz2.mp4" preload-key="zzzzz2" />}
    </view>
  );
}

export default Page;

兼容性

LCD tables only load in the browser

除非另有说明，本项目采用知识共享署名 4.0 国际许可协议进行许可，代码示例采用 Apache License 2.0 许可协议进行许可。