#WebView Site

A WebView site is a static file site published alongside the miniapp. It reduces the burden of deploying static HTML files for developers and supports offline mode. Developers can use the WebView component in the miniapp to load the WebView site, enabling seamless integration between the miniapp and the WebView site.

#Features

• Supports offline mode for improved access speed
• Supports bidirectional communication with the miniapp logic layer

#Usage

#1. Declare the WebView site directory

Declare the webviewRoot field in the tuya export of src/global.config.ts to specify the WebView site directory:

// src/global.config.ts
import { GlobalConfig } from '@ray-js/types';

export const tuya = {
  webviewRoot: 'my-webview',
};

const globalConfig: GlobalConfig = {
  basename: '',
};

export default globalConfig;

The miniapp will deploy using the directory specified by webviewRoot to serve the WebView site files.

Directory structure:

├── src
│   ├── global.config.ts
│   └── pages
│       └── index
│           └── index.tsx
└── my-webview
    ├── index.html
    └── index.js

Note: The webviewRoot field can only be declared once, using a relative path. Absolute paths are not supported.

#2. Use the WebView component to load the WebView site

The site protocol is webview://. Use the WebView component in a Ray page:

// src/pages/index/index.tsx
import React, { useRef } from 'react';
import { WebView } from '@ray-js/ray';

export default function IndexPage() {
  return (
    <WebView
      id="yourId"
      src="webview://my-webview/index.html"
      onMessage={(event) => {
        const messageData = event.detail;
        // messageData = { msg: 'sent to logic layer -> 13891819819' }
        console.log('Received WebView message:', messageData);
      }}
      onLoad={() => console.log('WebView loaded successfully')}
      onError={() => console.log('WebView failed to load')}
    />
  );
}

The src attribute value starts with webview://, followed by the directory specified by webviewRoot and the path to the WebView site file.

• onMessage: Communication between the WebView site and the miniapp logic layer
• onLoad: Triggered when the WebView site loads successfully
• onError: Triggered when the WebView site fails to load

#3. Communication between the WebView site and the logic layer

Communication between the WebView site and the miniapp logic layer is implemented via @tuya-miniapp/jssdk.

<!-- my-webview/index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>WebView Site</title>
</head>
<body>
  <script src="index.js"></script>
</body>
</html>

// my-webview/index.js
// Send a message to the logic layer
window.ty.miniProgram.postMessage({
  data: {
    msg: 'sent to logic layer -> ' + Date.now()
  }
});

// Receive messages from the logic layer
window.ty.miniProgram.onMessage(function (event) {
  const messageData = event.data;
  // messageData = { msg: 'sent to h5 -> 13991818111' }
});

Use ty.createWebviewContext in a Ray page to send messages to the WebView site:

// src/pages/index/index.tsx
import React, { useEffect, useRef } from 'react';
import { WebView, ty } from '@ray-js/ray';

export default function IndexPage() {
  const webviewContextRef = useRef(null);

  useEffect(() => {
    if (ty.createWebviewContext) {
      webviewContextRef.current = ty.createWebviewContext('yourId');
    }
  }, []);

  function sendMessage() {
    webviewContextRef.current?.postMessage({
      data: {
        msg: 'sent to h5 -> ' + Date.now(),
      },
    });
  }

  return (
    <WebView
      id="yourId"
      src="webview://my-webview/index.html"
      onMessage={(event) => {
        const messageData = event.detail;
        // messageData = { msg: 'sent to logic layer -> 13891819819' }
        console.log('Received WebView message:', messageData);
      }}
    />
  );
}

#Supported File Types

Supported file extensions: .jpg .jpeg .png .gif .bmp .ico .tiff .svg .ttf .woff .woff2 .json .html .htm .js .css .mp3 .mp4

While the WebView site supports many file types, not all files are suitable for inclusion. Developers should select appropriate file types and sizes based on actual requirements. Excessively large files may slow down miniapp loading speeds and degrade the user experience, or may fail to upload to the miniapp platform.

#Requirements

• Tuya MiniApp IDE >= 0.5.10
• Base library version >= 2.14.2
• Container version >= 3.12.0
• @tuya-miniapp/jssdk >= 0.1.2

#Notes

1. Files in the WebView site directory do not support miniapp components such as View and ScrollView. Only static HTML tags are supported.
2. Developers must ensure the legality of WebView site content. Content that is illegal, pornographic, or violent is prohibited, or the miniapp may be banned from the platform.
3. JavaScript files must be secure and must not contain malicious code, or the miniapp may be banned from the platform.
4. JavaScript files must ensure compatibility, for example by using ES5 syntax instead of ES6 syntax, to avoid compatibility issues on mobile browsers.