!1699 add developer web doc.

Merge pull request !1699 from lixingchi1/web_0228

!1699 add developer web doc.
Merge pull request !1699 from lixingchi1/web_0228
084a7ed1 · openharmony_ci · Gitee · de2610c5 · 406f552e · 084a7ed1
隐藏空白更改
内联并排

Showing with 195 addition and 0 deletion

zh-cn/application-dev/ui/ui-ts-components-web.md zh-cn/application-dev/ui/ui-ts-components-web.md +195 -0

未找到文件。
--- a/zh-cn/application-dev/ui/ui-ts-components-web.md
+++ b/zh-cn/application-dev/ui/ui-ts-components-web.md
+# Web
+
+Web是提供网页显示能力的组件，具体用法请参考 [Web API](../reference/arkui-ts/ts-media-components-web.md)。
+
+## 创建组件
+
+在main/ets/MainAbility/pages目录下的ets文件中创建一个Web组件。在web组件中通过src指定引用的网页路径，controller为组件的控制器，通过controller绑定Web组件，用于调用Web组件的方法。
+
+  ```
+  // xxx.ets
+  @Entry
+  @Component
+  struct WebComponent {
+    controller: WebController = new WebController();
+    build() {
+      Column() {
+        Web({ src: 'https://www.example.com', controller: this.controller })
+      }
+    }
+  }
+  ```
+
+## 设置样式和属性
+
+Web组件的使用需要添加丰富的页面样式和功能属性。设置height、padding样式可为Web组件添加高和内边距，设置fileAccess属性可为Web组件添加文件访问权限，设置javaScriptAccess属性为true使Web组件具有执行JavaScript代码的能力。
+
+```
+// xxx.ets
+@Entry
+@Component
+struct WebComponent {
+  fileAccess: boolean = true;
+  controller: WebController = new WebController();
+  build() {
+    Column() {
+      Text('Hello world!')
+        .fontSize(20)
+      Web({ src: 'https://www.example.com', controller: this.controller })
+        // 设置高和内边距
+        .height(500)
+        .padding(20)
+        // 设置文件访问权限和脚本执行权限
+        .fileAccess(this.fileAccess)
+        .javaScriptAccess(true)
+      Text('End')
+        .fontSize(20)
+    }
+  }
+}
+```
+## 添加事件和方法
+
+为Web组件添加onProgressChange事件，该事件回调Web引擎加载页面的进度值。将该进度值赋值给Progress组件的value，控制Progress组件的状态。当进度为100%时隐藏Progress组件，Web页面加载完成。
+
+```
+// xxx.ets
+@Entry
+@Component
+struct WebComponent {
+  @State progress: number = 0;
+  @State hideProgress: boolean = true;
+  fileAccess: boolean = true;
+  controller: WebController = new WebController();
+  build() {
+    Column() {
+      Text('Hello world!')
+        .fontSize(20)
+      Progress({value: this.progress, total: 100})
+        .color('#0000ff')
+        .visibility(this.hideProgress ? Visibility.None : Visibility.Visible)
+      Web({ src: 'https://example.com', controller: this.controller })
+        .fileAccess(this.fileAccess)
+        .javaScriptAccess(true)
+        .height(500)
+        .padding(20)
+        // 添加onProgressChange事件
+        .onProgressChange(e => {
+          this.progress = e.newProgress;
+          // 当进度100%时，进度条消失
+          if (this.progress === 100) {
+            this.hideProgress = true;
+          } else {
+            this.hideProgress = false;
+          }
+        })
+      Text('End')
+        .fontSize(20)
+    }
+  }
+}
+```
+在onPageEnd事件中添加runJavaScript方法。onPageEnd事件是网页退出时的回调，runJavaScript方法可以执行HTML中的JavaScript脚本。当页面退出时，触发onPageEnd事件，调用HTML文件中的test方法，在控制台打印信息。
+
+```
+// xxx.ets
+@Entry
+@Component
+struct WebComponent {
+  @State progress: number = 0;
+  @State hideProgress: boolean = true;
+  fileAccess: boolean = true;
+  // 定义Web组件的控制器controller
+  controller: WebController = new WebController();
+  build() {
+    Column() {
+      Text('Hello world!')
+        .fontSize(20)
+      Progress({value: this.progress, total: 100})
+        .color('#0000ff')
+        .visibility(this.hideProgress ? Visibility.None : Visibility.Visible)
+      // 初始化Web组件，并绑定controller
+      Web({ src: 'https://gitee.com', controller: this.controller })
+        .fileAccess(this.fileAccess)
+        .javaScriptAccess(true)
+        .height(500)
+        .padding(20)
+        .onProgressChange(e => {
+          this.progress = e.newProgress;
+          if (this.progress === 100) {
+            this.hideProgress = true;
+          } else {
+            this.hideProgress = false;
+          }
+        })
+        .onPageEnd(e => {
+          // test()在index.html中定义
+          this.controller.runJavaScript('test()');
+          console.info('url: ', e.url);
+        })
+      Text('End')
+        .fontSize(20)
+    }
+  }
+}
+```
+
+在main/resources/rawfile目录下创建一个HTML文件。
+
+```
+<!-- index.html -->
+<!DOCTYPE html>
+<html>
+<meta charset="utf-8">
+<body>
+    Hello world!
+</body>
+<script type="text/javascript">
+  function test() {
+      console.info('Ark Web Component');
+  }
+</script>
+</html>
+```
+## 场景示例
+
+该场景实现了Web组件中视频的动态播放。首先在HTML页面内嵌入视频资源，再使用Web组件的控制器调用onActive和onInactive方法激活和暂停页面渲染。页面消失时，Web组件停止渲染，视频暂停播放；页面显示时，激活Web组件，视频继续播放。
+
+  ```
+  // xxx.ets
+  @Entry
+  @Component
+  struct WebComponent {
+    controller: WebController = new WebController();
+    build() {
+      Column() {
+        Web({ src: $rawfile('index.html'), controller: this.controller })
+        .fileAccess(true)
+      }
+    }
+
+    onPageHide() {
+      // 页面消失时调用
+      this.controller.onInactive();
+    }
+
+    onPageShow() {
+      // 页面显示时调用
+      this.controller.onActive();
+    }
+  }
+  ```
+
+  ```
+  <!-- index.html -->
+  <!DOCTYPE html>
+  <html>
+  <meta charset="utf-8">
+  <body>
+      <video width="320" height="240" controls="controls" muted="muted" autoplay="autoplay">
+          <!-- test.mp4视频文件放在main/resources/rawfile目录下 -->
+          <source src="test.mp4" type="video/mp4">
+      </video>
+  </body>
+  </html>
+  ```