# @ashetm/ng-network 中文文档
规范地址：https://npmcn.com/package/%40ashetm/ng-network/
版本：1\.0\.1
npm 元数据更新时间：2026-10-31T14:14:59.570Z
中文译文更新时间：2026-10-31T14:22:25.305Z
软件包许可：未声明
本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40ashetm/ng-network
原文对照：https://npmcn.com/package/%40ashetm/ng-network/?lang=original
项目主页：https://github.com/AsheTM/ng-services/tree/main#readme
源码仓库：https://github.com/AsheTM/ng-services#main
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：49.5 kB，19 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：rxjs \>=6\.6\.0，@angular/core \>=16\.0\.0 \<20\.0\.0，@angular/common \>=16\.0\.0 \<20\.0\.0
- 首次发布：2025-01-14T13:59:58.011Z
- 最新版本发布：2026-10-31T14:14:59.417Z
- 已发布版本数：2（近 12 个月 1 个）
## 中文简介
`@ashetm/ng-network` 是一个库，它提供了一个指令、RxJS observable和一个RxJS操作符来跟踪设备的网络状态（在线/离线、连接质量）。
## 安装
```sh
npm install @ashetm/ng-network
```
也可以使用：`pnpm add @ashetm/ng-network`、`yarn add @ashetm/ng-network`、`bun add @ashetm/ng-network`
## README
# @ashetm / ng-network
`@ashetm/ng-network` 是一个库，它提供了一个指令、RxJS observable和一个RxJS操作符来跟踪设备的网络状态（在线/离线、连接质量）。
## 兼容性表
| 角版 | @ashetm / ng-network版本 | RxJS版本 | 支持 |
| --- | --- | --- | --- |
| 角16。X - 19.x | @ashetm / ng-network 1. x | 6.6.X和+ | ✅ |
## 安装
你可以用npm安装它：
```bash
npm install @ashetm/ng-network
```
## API
`@ashetm/ng-network` 暴露以下内容：
### 指令
#### NetworkDirective
- _选择器_： `[ashetmNetwork]`
这个角 **独立的** **结构** 指令监听网络连接状态的变化，并提供有关网络当前状态和连接丢失后经过的时间的可观察数据。它使用 `fromNetworkEvents` 检测在线/离线状态和 `fromNetworkLastTimeConnected` 跟踪自设备上次连接以来经过的时间。
**使用的例子:**
导入独立组件 `NetworkDirective` 在你的组件（或NgModule）中 `imports`：
```ts
@Component({
standalone: true,
imports: [AsyncPipe, NgIf, NetworkDirective],
// ...
})
```
```html
You are online
You are offline
Last connected: {{ lastConnected }} ms ago
```
或者用结构简写：
```html
{{ (network | async) ? 'You are online' : 'You are offline' }}
```
**解释:**
- _网络_：这个可观察对象首先发出当前状态，然后 `true` 当设备上线时 `false` 当它脱机时。
- _lastTimeConnected美元_：当设备处于脱机状态时，这个可观察对象每100毫秒发出一次连接丢失后经过的时间（以毫秒为单位）。它释放 `undefined` 当设备在线时。
### 自定义RXJS可观察对象
#### `fromOfflineEvent()`
```ts
function fromOfflineEvent(): Observable { ... }
```
在设备脱机时发出通知。
返回:
发射空洞的可观测物体
例子:
```tsx
fromOfflineEvent().subscribe(() => {
console.log('Device is offline');
});
```
#### `fromOnlineEvent()`
```ts
function fromOnlineEvent(): Observable { ... }
```
当设备上线时发出通知。
**例子:**
```tsx
fromOnlineEvent().subscribe(() => {
console.log('Device is online');
});
```
#### `fromNetworkEvents()`
```ts
function fromNetworkEvents(): Observable { ... }
```
发出订阅时的当前状态(`navigator.onLine`),然后 `true` 当设备上线时 `false` 当它脱机时。重复的值将被跳过。
**例子:**
```tsx
fromNetworkEvents().subscribe((isOnline: boolean) => {
console.log(`Network status: ${isOnline ? 'Online' : 'Offline'}`);
});
```
#### `fromNetworkLastTimeConnected()`
```ts
function fromNetworkLastTimeConnected(): Observable { ... }
```
当设备处于脱机状态时，每隔100毫秒发出连接丢失后经过的时间（以毫秒为单位）。发出 `undefined` 当设备在线时。
**例子:**
```tsx
fromNetworkLastTimeConnected().subscribe((lastConnected: number | undefined) => {
if(typeof lastConnected === 'number')
console.log(`Last connected: ${lastConnected} ms ago`);
else
console.log(`Last connected: is currently connected`);
});
```
#### `fromNetworkStatus()`
```ts
function fromNetworkStatus(): Observable { ... }
```
这个可观察对象提供了详细的网络状态信息(参见 [`NetworkStatus`](https://npmcn.com/package/%40ashetm/ng-network/#readme-networkstatus))，基于 [网络信息API](https://developer.mozilla.org/en-US/docs/Web/API/Network_Information_API)． 它在订阅时发出当前状态，然后在网络条件发生变化时发出。
它释放 `undefined` 当浏览器不支持网络信息API时。
**例子:**
```tsx
fromNetworkStatus().subscribe((status: NetworkStatus | undefined) => {
if (!status) {
console.log('Network Information API not supported');
return;
}
console.log(`Effective type: ${status.effectiveType}`);
console.log(`Downlink: ${status.downlink} Mbps`);
console.log(`RTT: ${status.rtt} ms`);
console.log(`Data Saver Enabled: ${status.saveData}`);
});
```
### 自定义RXJS操作符
#### `retryUntilOnline()`
```ts
function retryUntilOnline(durationStep: number = 1000, timeIncreasing: boolean = false): MonoTypeOperatorFunction { ... }
```
这个 `retryUntilOnline` 操作符 **实验特征** 当一个可观察操作因为设备离线而失败时，它会重新尝试：
- 如果源故障，而设备处于 **离线**，它会等待设备重新联机，然后重试 `durationStep`.
- 如果源故障，而设备处于 **在线**，错误将通过（这不是网络问题）。
**参数:**
- `durationStep`：设备恢复在线后重试的延迟时间，以毫秒为单位（默认为） `1000 ms`）。
- `timeIncreasing`:当 `true`，延迟乘以尝试次数（1x, 2x, 3x…）(默认为 `false`）。
**例子:**
```tsx
import { of } from 'rxjs';
import { ajax } from 'rxjs/ajax';
import { catchError, tap } from 'rxjs/operators';
import { retryUntilOnline } from '@ashetm/ng-network';
// Mock API endpoint
const apiEndpoint = 'https://jsonplaceholder.typicode.com/posts/1';
// Simulated HTTP request
const httpRequest$ = ajax.getJSON(apiEndpoint).pipe(
tap((response) => console.log('Request successful:', response)),
retryUntilOnline(1000), // If offline, wait for the network, then retry 1 second later
catchError((error) => {
console.error('Request failed:', error);
return of(null); // Handle the error and emit a fallback value
})
);
// Subscribe to the observable
httpRequest$.subscribe({
next: (data) => console.log('Final data:', data),
error: (err) => console.error('Subscription error:', err),
complete: () => console.log('Request completed'),
});
```
### 类型
#### `NetworkStatus`
这个 `NetworkStatus` 对象发出的网络状态对象的结构 `fromNetworkStatus()` 可观察到的。
**参数:**
- `effectiveType`：表示有效网络连接类型的字符串（例如4g、3g、2g或慢速2g）。
- `downlink`：连接的大致带宽，单位为兆比特/秒。
- `rtt`：请求的估计往返时间，单位为毫秒。
- `saveData`：一个布尔值，指示用户是否启用了浏览器的数据保存模式。
## 服务器端呈现
该库可以安全地与服务器端呈现一起使用。在服务器端，没有浏览器：
- `fromOnlineEvent()` 和 `fromOfflineEvent()` 发出。
- `fromNetworkEvents()` 发出 `true` (假设在线)。
- `fromNetworkLastTimeConnected()` 和 `fromNetworkStatus()` 发出 `undefined`.
- `retryUntilOnline` 传递错误。
## 问题
寻找维护者，或者如果有问题或任何想法要添加。请在github存储库中创建问题。
## 常见问题
### @ashetm/ng-network 是什么？
@ashetm/ng-network 是一个库，它提供了一个指令、RxJS observable和一个RxJS操作符来跟踪设备的网络状态（在线/离线、连接质量）。
### 如何安装 @ashetm/ng-network？
在项目目录运行 npm install @ashetm/ng-network，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：rxjs（\>=6\.6\.0）、@angular/core（\>=16\.0\.0 \<20\.0\.0）、@angular/common（\>=16\.0\.0 \<20\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @ashetm/ng-network 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @ashetm/ng-network 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @ashetm/ng-network 可以商用吗？
@ashetm/ng-network 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。
### @ashetm/ng-network 还在维护吗？
最新版本 1\.0\.1 发布于 2026/10/31（2 天前）；至今共发布 2 个版本，其中过去 12 个月发布了 1 个；首次发布于 2025/01/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。