`<lynx-view>` Web

<lynx-view> 是一个加载并展示 Lynx 模板的容器组件，可以在 Web 应用中使用它来渲染 Lynx 模板。

API 参考

完成上述集成后，你可以通过 Lynx for Web 提供的 API 实现更灵活的交互控制，以下是核心 API 的详细说明：

lynx-view

Attributes

名称	是否必传	说明
url	是	Rspeedy 产物的url（其它 chunk 的 url 会编译时注入产物自动启动）
globalProps	否	卡片初始化时的 GlobalProps
initData	否	卡片初始化时的 InitData
overrideLynxTagToHTMLTagMap	否	自定义 Lynx 标签到 HTML 标签的映射关系。不支持 React Component，只支持 HTMLElement(可以是webcomponent或者原生标签)

Properties

nativeModulesMap

自定义的 NativeModule，key 为 module 名称，value 为 module 实现（一个 esm url）：

type NativeModulesMap = Record<string, string>;

示例:

const nativeModulesMap = {
  CustomModule: URL.createObjectURL(
    new Blob(
      [
        `export default function(NativeModules, NativeModulesCall) {
    return {
      async getColor(data, callback) {
        const color = await NativeModulesCall('getColor', data);
        callback(color);
      },
    }
  };`,
      ],
      { type: 'text/javascript' },
    ),
  ),
};
lynxView.nativeModulesMap = nativeModulesMap;

onNativeModulesCall

处理 NativeModules（JSB 等）相关调用的入口:

(name: string, data: any, moduleName: string) => Promise<any> | any;

示例：

// 处理 NativeModule.bridge.call('request')
lynxView.onNativeModulesCall = (name, data, moduleName) => {
  if (moduleName === 'bridge') {
    if (name === 'request') {
      // ...

      // return data 会被自动处理为 callback data
      return {};
    }
  }
};

customTemplateLoader

允许用户实现自定义模板加载功能（默认是 fetch）：

lynxView.customTemplateLoader = (url) => {
  return await(
    await fetch(url, {
      method: 'GET',
    }),
  ).json();
};

Events

error

报错信息通知：

type LynxError = CustomEvent<{
  error: Error;
  sourceMap: {
    offset: {
      // 行偏移量
      line: number;
      // 列偏移量
      col: number;
    };
  };
  release: string;
  fileName: 'lepus.js' | 'app-service.js';
}>;

lynxView.addEventListener('error', (err: LynxError) => {
  // ...
});

Methods

updateData

详见

export type Cloneable<T = string | number | null | boolean | undefined> =
  | T
  | Record<string, T>
  | T[];

updateData(
  data: Cloneable,
  updateDataType: UpdateDataType,
  callback?: () => void,
): void

updateGlobalProps

详见

updateGlobalProps(data: Cloneable): void;

sendGlobalEvent

详见

sendGlobalEvent(eventName: string, params: Cloneable[]): void;

宽、高

Note

lynx-view的内部排版会被强制移出外部排版流

我们会给所有 lynx-view 强制应用 CSS Containment。

也就是默认情况下，您需要给 lynx-view 设置一个宽高。宽高可以是 flex-grow 分配的、可以是百分比指定的，但是不可以是“撑开”的。设置宽高是强烈推荐的做法，也是性能的最佳实践。

有些情况下您的确需要由 lynx-view 的内容决定宽或高，您可以设置 height="auto" 或者 width="auto" 来启动自动宽高监听器。在这种情况下，lynx-view 的内部排版依旧与外部排版流独立。

兼容性

推荐配置为：Chrome > 118, safari>18, Firefox NSR

如果你想支持 chrome < 118，safari < 18 的浏览器，需要做以下处理：

引入降级插件：

import '@lynx-js/web-elements-compat/LinearContainer';

额外编译 @lynx-js 依赖。如果你的项目是 Rsbuild，则按照如下配置修改：

// rsbuild.config.ts
export default {
  source: {
    include: [/@lynx-js/],
  },
  output: {
    polyfill: 'usage',
  },
};

FAQ

运行时报错：`Uncaught SecurityError: Failed to construct 'Worker': Script at 'xxx' cannot be accessed from origin 'xxx'`.

这是因为 Worker 加载远程脚本需要遵守同源策略，而项目的 JS 资源一般会部署在 CDN 上，从而造成了跨域问题。

可以通过引入 remote-web-worker 的形式解决：

// 引入位置需要保证在 @lynx-js/web-core 前
import 'remote-web-worker';

import '@lynx-js/web-core';
import '@lynx-js/web-core/index.css';
import '@lynx-js/web-elements/all';
import '@lynx-js/web-elements/index.css';
document.body.innerHTML = `
<lynx-view
    style="height:100vh; width:100vw;"
    url="http://localhost:3000/main/index.main.bundle"
>
</lynx-view>`;

性能优化

我们提供了 RSBuild 插件来做性能优化，你可以在你的 web 工程中引入该插件

#<lynx-view> Web

#API 参考

#lynx-view

#Attributes

#Properties

#nativeModulesMap

#onNativeModulesCall

#customTemplateLoader

#Events

#error

#Methods

#updateData

#updateGlobalProps

#sendGlobalEvent

#宽、高

#兼容性

#FAQ

#运行时报错：Uncaught SecurityError: Failed to construct 'Worker': Script at 'xxx' cannot be accessed from origin 'xxx'.

#性能优化