From 5b00e0eb945e71df0f6a308e1fa928b5e8d53fd5 Mon Sep 17 00:00:00 2001 From: maosiping Date: Mon, 6 Dec 2021 11:47:27 +0800 Subject: [PATCH] =?UTF-8?q?=E5=B0=8F=E5=9E=8B=E7=B3=BB=E7=BB=9F=E6=8F=90?= =?UTF-8?q?=E4=BE=9B@system.fetch=E6=A8=A1=E5=9D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: maosiping --- .../fetch-development-guideline.md | 70 +++++++++ .../connectivity/fetch-overview.md | 27 ++++ zh-cn/application-dev/connectivity/fetch.md | 6 + .../js-reference/apis/js-apis-fetch.md | 141 ++++++++++++++++++ .../js-reference/apis/js-apis-telephony.md | 3 +- ...41\345\255\220\347\263\273\347\273\237.md" | 62 +++++++- zh-cn/release-notes/OpenHarmony-v3.0-LTS.md | 2 +- 7 files changed, 307 insertions(+), 4 deletions(-) create mode 100644 zh-cn/application-dev/connectivity/fetch-development-guideline.md create mode 100644 zh-cn/application-dev/connectivity/fetch-overview.md create mode 100644 zh-cn/application-dev/connectivity/fetch.md create mode 100644 zh-cn/application-dev/js-reference/apis/js-apis-fetch.md diff --git a/zh-cn/application-dev/connectivity/fetch-development-guideline.md b/zh-cn/application-dev/connectivity/fetch-development-guideline.md new file mode 100644 index 00000000000..fe4db90c232 --- /dev/null +++ b/zh-cn/application-dev/connectivity/fetch-development-guideline.md @@ -0,0 +1,70 @@ +# 通过fetch发送Http请求开发指导 + +- [接口说明](#接口说明) +- [开发步骤](#开发步骤) + +## 接口说明 + +fetch模块只有一个接口 + +``` +fetch(options: { + url: string; + data?: string | Object; + header?: Object; + method?: string; + responseType?: string; + success?: (data: FetchResponse) => void; + fail?: (data: any, code: number) => void; + complete?: () => void; +}): void; +``` + +## 开发步骤 + +index.js参考： +``` +// 引入包名 +import fetch from '@system.fetch'; + +// 编写回调函数 +function OnSuccess(resp) { + console.log("code = " + resp.code) + console.log("data = " + resp.data) +} + +function OnFail(errString, errCode) { + console.log("errString: " + errString) + console.log("errCode: " + errCode) +} + +function OnComplete() { + console.log("Fetch Complete") +} + +// 调用Api +function TestHttpApi() { + let options = { + url: "https://www.baidu.com", + method: "GET", + success: OnSuccess, + fail: OnFail, + complete: OnComplete + } + fetch.fetch(options) +} + +//导出 +export default { + testHttpApi: function () { + TestHttpApi() + } +} +``` + +index.xml参考: +``` +
+ +
+``` \ No newline at end of file diff --git a/zh-cn/application-dev/connectivity/fetch-overview.md b/zh-cn/application-dev/connectivity/fetch-overview.md new file mode 100644 index 00000000000..49877db4b74 --- /dev/null +++ b/zh-cn/application-dev/connectivity/fetch-overview.md @@ -0,0 +1,27 @@ +# Http接口fetch概述 + +- [介绍](#介绍) +- [约束与限制](#约束与限制) +- [相关模块](#相关模块) + +## 介绍 +fetch模块是OpenHarmony为开发者提供的发送Http请求的接口。js的解析由ace框架完成，Http的请求的发送以及响应的获取是基于curl，TLS协议由mbedtls提供，Http2.0协议由nghttp2提供。 + + +## 约束与限制 +1. 小型系统上使用: **@system.fetch**
+2. 开发板(以Hi3516为例)上需要在/etc下新建一个文件resolv.conf在里面写入dns服务器地址，这是使用Http的前置条件。具体的dns地址跟所连的wifi有关，在公网上，国内可使用**114.114.114.114**，国外可使用**8.8.8.8**。因此如果连接的wifi是公网，/etc/resolv.conf里的内容可参考如下方式编写： + ``` + nameserver 114.114.114.114 + nameserver 8.8.8.8 + ``` + + +## 相关模块 +[ ace_engine_lite ](https://gitee.com/openharmony/ace_engine_lite) + +[ third_party_curl ](https://gitee.com/openharmony/third_party_curl) + +[ third_party_mbedtls ](https://gitee.com/openharmony/third_party_mbedtls) + +[ third_party_nghttp2 ](https://gitee.com/openharmony/third_party_nghttp2) \ No newline at end of file diff --git a/zh-cn/application-dev/connectivity/fetch.md b/zh-cn/application-dev/connectivity/fetch.md new file mode 100644 index 00000000000..5aaebb1851d --- /dev/null +++ b/zh-cn/application-dev/connectivity/fetch.md @@ -0,0 +1,6 @@ +# Http接口fetch + + +- **[Http接口fetch概述](fetch-overview.md)** + +- **[通过fetch发送Http请求开发指导](fetch-development-guideline.md)** \ No newline at end of file diff --git a/zh-cn/application-dev/js-reference/apis/js-apis-fetch.md b/zh-cn/application-dev/js-reference/apis/js-apis-fetch.md new file mode 100644 index 00000000000..9ed08a9b0d9 --- /dev/null +++ b/zh-cn/application-dev/js-reference/apis/js-apis-fetch.md @@ -0,0 +1,141 @@ +# Http请求 + +>**说明：** +1. 小型系统上使用: **@system.fetch**
+2. 开发板(以Hi3516为例)上需要在/etc下新建一个文件resolv.conf在里面写入dns服务器地址，这是使用Http的前置条件。具体的dns地址跟所连的wifi有关，在公网上，国内可使用**114.114.114.114**，国外可使用**8.8.8.8**。因此如果连接的wifi是公网，/etc/resolv.conf里的内容可参考如下方式编写： + ``` + nameserver 114.114.114.114 + nameserver 8.8.8.8 + ``` + +- [导入模块](#导入模块) +- [API fetch.fetch](#API fetch.fetch) +- [示例](#示例) +- [相关仓](#相关仓) + +## 导入模块 + +``` +import fetch from '@system.fetch' +``` + +## API fetch.fetch + +``` +fetch(options: { + url: string; + data?: string | Object; + header?: Object; + method?: string; + responseType?: string; + success?: (data: FetchResponse) => void; + fail?: (data: any, code: number) => void; + complete?: () => void; +}): void; +``` + +将Http请求内容以及回调函数放心options对应的字段，然后调用 **fetch.fetch(options)** 发送网络请求，请求成功或者失败后执行对应的回调函数 + +- 参数 + + |参数名|类型|必填|说明| + |----|----|----|----| + |options|Object|是|包含http请求参数以及请求成功或失败时执行的回调函数| + +- options各字段含义 + + |字段名|类型|必填|说明| + |----|----|----|----| + |url|string|是|网站地址，比如"https://www.baidu.com"或者"http://www.4399.com"等| + |data|string或者Object|否|1、如果请求方法是GET、OPTIONS等，data字段会被编码到URL作为URL的参数。
2、如果请求方法是POST、PUT，data字段会作为http报文中的请求体，也就是body。
详见[请求体data字段详解](#请求体data字段详解)| + |header|Object|否|Http头，以 **{"name": "value"}** 的形式提供| + |method|string|否|支持OPTIONS, GET, HEAD, POST, PUT, DELETE以及TRACE。默认是GET| + |responseType|string|否|响应中的data字段是否需要转换成Object对象，如果responseType是"JSON"(不区分大小写)，那么响应提中的data字段会转换为Object对象再调用回调函数，没提供或者不是"JSON"，则不进行转换。详见[响应详解](#响应详解)| + |success|function (data: FetchResponse) => void;|否|请求成功时执行的回调函数(不是指Http的状态码，成功是指请求发出去了，并且得到了回应)。详见[响应详解](#响应详解)| + |fail|function (data: string, code: number) => void;|否|请求失败时执行的回调函数，data是错误提示，code是错误码。| + |complete|function () => void;|否|请求完成时执行的回调(无论成功还是失败)| + +## 请求体data字段详解 +- 请求方法是OPTIONS, GET, HEAD, TRACE或者GET + - data类型是string + - data字段会直接与url进行拼接，并进行url encode，也就是将data当作url的参数 + - data类型是Object + - Object会被解析成"name1=value1&name2=value2"这样的url参数，仅对类型是string的字段进行解析 + - 举例： + - url = "https://www.baidu.com"
data = "name=Tony&age=20" +
那么最终的请求发出去时的url就是: "https://www.baidu.com?name=Tony&age=20" + - url = "https://www.baidu.com?type=animal"
data = "name=Tony&age=20" +
那么最终的请求发出去时的url就是: "https://www.baidu.com?type=animal&name=Tony&age=20" + - url = "https://www.baidu.com?type=animal"
data = {"name": "Tony", "age": "20"} +
那么最终的请求发出去时的url就是: "https://www.baidu.com?type=animal&name=Tony&age=20" + - url = "https://www.baidu.com?type=animal" +
data = {"name": "Tony", "age": "20", "any": {"country": "China"}} +
那么最终的请求发出去时的url就是: "https://www.baidu.com?type=animal&name=Tony&age=20" +
忽略"any"字段，因为其类型不是string + +- 请求方法是POST或者PUT + - data类型是string + - 直接当作Http报文的body部分 + - data类型是Object + - 将data转换成string然后放在Http报文的body部分 + - 举例 + - data = {
  "name": "Tony",
  "age": "20",
  "any": {
    "country": "China"
  }
} +
那么最终的body部分是```{"name": "Tony", "age": "20", "any": {"country": "China"}}```这个字符串 + +## 响应详解 +``` +interface FetchResponse { + code: number; + data: string | object; + headers: Object; +} +``` +|字段名|类型|说明| +|----|----|----| +|code|number|当请求成功发出去并且收到响应，code是Http状态码，否则是-1| +|data|string或者Object|当请求成功发出去并且收到响应，data是Http响应体
  ```默认使用string保存，如果请求时的responseType是"json"，那么会尝试将字符串转换成Object。```
当请求没有成功发送出去时，data是错误提示。| +|headers|Object|Http响应头，以 **{"name1": "value1", "name2": "value2"}** 这样的形式返回| + +## 示例 + +``` +// 引入包名 +import fetch from '@system.fetch'; + +// 编写回调函数 +function OnSuccess(resp) { + console.log("code = " + resp.code) + console.log("data = " + resp.data) +} + +function OnFail(errString, errCode) { + console.log("errString: " + errString) + console.log("errCode: " + errCode) +} + +function OnComplete() { + console.log("Fetch Complete") +} + +// 调用Api +function TestHttpApi() { + let options = { + url: "https://www.baidu.com", + method: "GET", + success: OnSuccess, + fail: OnFail, + complete: OnComplete + } + fetch.fetch(options) +} +``` + +## 相关仓 + +[ ace_engine_lite ](https://gitee.com/openharmony/ace_engine_lite) + +[ third_party_curl ](https://gitee.com/openharmony/third_party_curl) + +[ third_party_mbedtls ](https://gitee.com/openharmony/third_party_mbedtls) + +[ third_party_nghttp2 ](https://gitee.com/openharmony/third_party_nghttp2) \ No newline at end of file diff --git a/zh-cn/application-dev/js-reference/apis/js-apis-telephony.md b/zh-cn/application-dev/js-reference/apis/js-apis-telephony.md index ab33a0a089a..506ef87131f 100644 --- a/zh-cn/application-dev/js-reference/apis/js-apis-telephony.md +++ b/zh-cn/application-dev/js-reference/apis/js-apis-telephony.md @@ -3,4 +3,5 @@ - [拨打电话](js-apis-call.md) - [短信服务](js-apis-sms.md) - [SIM卡管理](js-apis-sim.md) -- [网络搜索](js-apis-radio.md) \ No newline at end of file +- [网络搜索](js-apis-radio.md) +- [Http请求](js-apis-fetch.md) \ No newline at end of file diff --git "a/zh-cn/readme/\347\224\265\350\257\235\346\234\215\345\212\241\345\255\220\347\263\273\347\273\237.md" "b/zh-cn/readme/\347\224\265\350\257\235\346\234\215\345\212\241\345\255\220\347\263\273\347\273\237.md" index bf5a7381cd1..51fd3d7bb84 100755 --- "a/zh-cn/readme/\347\224\265\350\257\235\346\234\215\345\212\241\345\255\220\347\263\273\347\273\237.md" +++ "b/zh-cn/readme/\347\224\265\350\257\235\346\234\215\345\212\241\345\255\220\347\263\273\347\273\237.md" @@ -6,12 +6,13 @@ - [使用说明](#section128mcpsimp) - [获取当前蜂窝网络信号信息](#section1458213210369) - [观察蜂窝网络状态变化](#section750135512369) + - [发送Http请求来访问网络](#section78465345345) - [相关仓](#section152mcpsimp) ## 简介 -电话服务子系统，提供了一系列的API用于获取无线蜂窝网络和SIM卡相关的一些信息。应用可以通过调用API来获取当前注册网络名称、网络服务状态、信号强度以及SIM卡的相关信息。 +电话服务子系统，提供了一系列的API用于获取无线蜂窝网络和SIM卡相关的一些信息，并且提供发送Http请求的API。应用可以通过调用API来获取当前注册网络名称、网络服务状态、信号强度以及SIM卡的相关信息，并且可以通过调用Http的API来访问网络。 各个模块主要作用如下： @@ -36,9 +37,23 @@ base/telephony/ └── state_registry # 状态注册 ``` +``` +/foundation/communication/netstack +├── frameworks # 框架代码目录 +│ ├── js # JS适配层 +│ ├── builtin # 轻量级系统和小型系统上HttpAPI基于JSI的JS适配层 +│ └── napi # 标准系统上HttpAPI基于NAPI的JS适配层 +├── interfaces # 对外暴露的API +│ └── kits # OpenHarmony SDK API +│ └── js # JS API +├── utils # 公共工具 +│ └── log # 日志工具 +``` + ## 约束 -1. 目前开源的范围仅支持蜂窝通话（仅支持CS通话）和短信，不支持蜂窝数据上网，仅支持单SIM卡。 +1. 支持蜂窝通话（仅支持CS通话）和短信，仅支持单SIM卡。 +2. 支持使用Http接口访问网络。 ## 使用说明 @@ -130,6 +145,47 @@ base/telephony/ ``` +### 发送Http请求来访问网络 + +**小型系统上发送Http请求** + +1. 从@system.fetch.d.ts中导入fetch类。 +2. 调用fetch(options: Object)方法发送Http请求，options参数里可写上对应的回调函数。 +3. 当网络状态发生变更时，调用者会收到回调。 + + ``` + // 引入包名 + import fetch from '@system.fetch'; + + // 编写回调函数 + function OnSuccess(resp) { + console.log("code = " + resp.code) + console.log("data = " + resp.data) + } + + function OnFail(errString, errCode) { + console.log("errString: " + errString) + console.log("errCode: " + errCode) + } + + function OnComplete() { + console.log("Fetch Complete") + } + + // 调用Api + function TestHttpApi() { + let options = { + url: "https://www.baidu.com", + method: "GET", + success: OnSuccess, + fail: OnFail, + complete: OnComplete + } + + fetch.fetch(options) + } + ``` + ## 相关仓 **电话服务子系统** @@ -143,3 +199,5 @@ base/telephony/ [telephony\_sms\_mms](https://gitee.com/openharmony/telephony_sms_mms/blob/master/README_zh.md) [telephony\_state\_registry](https://gitee.com/openharmony/telephony_state_registry/blob/master/README_zh.md) + +[communication_netstack](https://gitee.com/openharmony/communication_netstack/blob/master/README_zh.md) diff --git a/zh-cn/release-notes/OpenHarmony-v3.0-LTS.md b/zh-cn/release-notes/OpenHarmony-v3.0-LTS.md index c12c93cfc16..ded67207788 100644 --- a/zh-cn/release-notes/OpenHarmony-v3.0-LTS.md +++ b/zh-cn/release-notes/OpenHarmony-v3.0-LTS.md @@ -116,7 +116,7 @@ repo forall -c 'git lfs pull' | 编译构建 | - 支持编译arm64形态产品
- 支持编译ohos-sdk | NA | | 用户程序框架 | - 支持ServiceAbility JS开发能力
- 支持DataAbility JS开发能力
- HAP支持多Ability声明
- 本地Ability迁移到远程设备
- 应用任务栈保存与恢复
- JS 利用Zip库实现文件压缩和解压缩 | NA | | 杂散软件服务 | 支持定时器能力，提供定时时区管理能力 | NA | - +| 电话服务 | 新增Http接口用于访问网络 | 小型系统新增Http接口用于访问网络 | ### API变更 -- Gitee