1# 网络共享（仅对系统应用开放）
2
3## 简介
4
5网络共享管理分享设备已有网络给其他连接设备，支持 Wi-Fi 热点共享、蓝牙共享和 USB 共享，同时提供网络共享状态、共享流量查询功能。
6
7> **说明：**
8> 为了保证应用的运行效率，大部分 API 调用都是异步的，对于异步调用的 API 均提供了 callback 和 Promise 两种方式，以下示例均采用 promise 函数，更多方式可以查阅[API 参考](../reference/apis-network-kit/js-apis-net-sharing-sys.md)。
9
10## 基本概念
11
12- WIFI 共享：通过 WIFI 热点共享网络。
13- 蓝牙共享：通过蓝牙共享网络。
14- USB 共享：通过 USB 共享网络。
15
16## 约束
17
18- 开发语言：JS
19- 本模块首批接口从 API version 9 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
20
21## 场景介绍
22
23网络共享的典型场景有：
24
25- 开启网络共享
26- 停止网络共享
27- 获取共享网络的数据流量
28
29以下分别介绍具体开发方式。
30
31## 接口说明
32
33完整的 JS API 说明以及实例代码请参考：[网络共享](../reference/apis-network-kit/js-apis-net-sharing-sys.md)。
34
35| 接口名                                                                   | 描述                                                                                                    |
36| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
37| isSharingSupported(callback: AsyncCallback\<boolean>): void;    | 获取当前系统是否支持网络共享，使用 callback 方式作为异步方法。                                                       |
38| isSharing(callback: AsyncCallback\<boolean>): void;             | 获取当前共享状态，使用 callback 方式作为异步方法。                                                                   |
39| startSharing(type: SharingIfaceType, callback: AsyncCallback\<void>): void;  | 开启共享，type 为共享类型，目前支持 Wifi 热点、蓝牙、USB，使用 callback 方式作为异步方法。                |
40| stopSharing(type: SharingIfaceType, callback: AsyncCallback\<void>): void;  | 停止指定类型共享，type 为共享类型，包括 Wifi 热点、蓝牙、USB，使用 callback 方式作为异步方法。             |
41| getStatsRxBytes(callback: AsyncCallback\<number>): void;         | 获取共享接收数据量，单位 KB，使用 callback 方式作为异步方法。                                                        |
42| getStatsTxBytes(callback: AsyncCallback\<number>): void;         | 获取共享发送数据量，单位 KB，使用 callback 方式作为异步方法。                                                        |
43| getStatsTotalBytes(callback: AsyncCallback\<number>): void;      | 获取共享总数据流量，单位 KB，使用 callback 方式作为异步方法。                                                        |
44| getSharingIfaces(state: SharingIfaceState, callback: AsyncCallback\<Array\<string>>): void;  | 获取指定状态的网卡名称，state 为状态，包括正在共享、可共享、共享错误，使用 callback 方式作为异步方法。 |
45| getSharingState(type: SharingIfaceType, callback: AsyncCallback\<SharingIfaceState>): void;  | 获取指定类型共享状态，type 为类型，目前支持 Wifi 热点、蓝牙、USB，使用 callback 方式作为异步方法。  |
46| getSharableRegexes(type: SharingIfaceType, callback: AsyncCallback\<Array\<string>>): void;  | 获取与指定类型匹配的网卡正则表达式列表，type 为类型，目前支持 Wifi 热点、蓝牙、USB，使用 callback 方式作为异步方法。 |
47| on(type: 'sharingStateChange', callback: Callback\<boolean>): void;        | 注册共享状态改变监听，返回网络共享的状态。                                                                |
48| off(type: 'sharingStateChange', callback?: Callback\<boolean>): void;      | 注销共享状态改变监听，返回网络共享的状态。                                                                |
49| unction on(type: 'interfaceSharingStateChange', callback: Callback\<{ type: SharingIfaceType, iface: string, state: SharingIfaceState }>): void;    | 注册指定网卡共享状态改变监听。    |
50| off(type: 'interfaceSharingStateChange', callback?: Callback\<{ type: SharingIfaceType, iface: string, state: SharingIfaceState }>): void; | 注销指定网卡共享状态改变监听。             |
51| on(type: 'sharingUpstreamChange', callback: Callback\<NetHandle>): void;               | 注册上行网卡改变监听。                                                                         |
52| off(type: 'sharingUpstreamChange', callback?: Callback\<NetHandle>): void;             | 注销上行网卡改变监听。                                                                         |
53
54## 开启网络共享
55
561. 从@kit.NetworkKit 中导入 sharing 命名空间。
572. 注册监听共享状态的改变。
583. 调用 startSharing 方法，来开启指定类型共享。
594. 接收到共享状态开启的回调，开启共享成功。
60
61```ts
62// 从@kit.NetworkKit中导入sharing命名空间
63import { sharing } from '@kit.NetworkKit';
64import { BusinessError } from '@kit.BasicServicesKit';
65
66// 注册监听共享状态的改变
67sharing.on('sharingStateChange', (data: boolean) => {
68  console.log(JSON.stringify(data));
69});
70
71// 调用startSharing方法，来开启指定类型共享
72sharing.startSharing(sharing.SharingIfaceType.SHARING_WIFI).then(() => {
73  console.log('start wifi sharing successful');
74}).catch((error: BusinessError) => {
75  console.log('start wifi sharing failed');
76});
77```
78
79## 停止网络共享
80
81### 开发步骤
82
831. 从@kit.NetworkKit 中导入 sharing 命名空间。
842. 注册监听共享状态的改变。
853. 调用 stopSharing 方法，来停止指定类型共享。
864. 接收到共享状态关闭的回调，停止共享成功。
87
88```ts
89// 从@kit.NetworkKit中导入sharing命名空间
90import { sharing } from '@kit.NetworkKit';
91import { BusinessError } from '@kit.BasicServicesKit';
92
93// 注册监听共享状态的改变
94sharing.on('sharingStateChange', (data: boolean) => {
95  console.log(JSON.stringify(data));
96});
97
98// 调用stopSharing方法，来停止指定类型共享
99sharing.stopSharing(sharing.SharingIfaceType.SHARING_WIFI).then(() => {
100  console.log('start wifi sharing successful');
101}).catch((error: BusinessError) => {
102  console.log('start wifi sharing failed');
103});
104```
105
106## 获取共享网络的数据流量
107
108### 开发步骤
109
1101. 从@kit.NetworkKit 中导入 sharing 命名空间。
1112. 调用 startSharing 方法，来开启指定类型共享。
1123. 调用 getStatsTotalBytes 方法，来获取共享网络数据量。
1134. 调用 stopSharing 方法，来停止指定类型共享，共享网络数据量清零。
114
115```ts
116// 从@kit.NetworkKit中导入sharing命名空间
117import { sharing } from '@kit.NetworkKit';
118import { BusinessError } from '@kit.BasicServicesKit';
119
120// 调用startSharing方法，来开启指定类型共享
121sharing.startSharing(sharing.SharingIfaceType.SHARING_WIFI).then(() => {
122  console.log('start wifi sharing successful');
123}).catch((error: BusinessError) => {
124  console.log('start wifi sharing failed');
125});
126
127// 调用getStatsTotalBytes方法，来获取共享网络数据量
128sharing.getStatsTotalBytes().then((data: number) => {
129  console.log(JSON.stringify(data));
130}).catch((error: BusinessError) => {
131  console.log(JSON.stringify(error));
132});
133
134// 调用stopSharing方法，来停止指定类型共享，共享网络数据量清零
135sharing.stopSharing(sharing.SharingIfaceType.SHARING_WIFI).then(() => {
136  console.log('start wifi sharing successful');
137}).catch((error: BusinessError) => {
138  console.log('start wifi sharing failed');
139});
140
141// 再次调用getStatsTotalBytes方法，共享网络数据量已清零
142sharing.getStatsTotalBytes().then((data: number) => {
143  console.log(JSON.stringify(data));
144}).catch((error: BusinessError) => {
145  console.log(JSON.stringify(error));
146});
147```
148