@herongxhr/network-status

# @herongxhr/network-status ![NPM Version](https://img.shields.io/npm/v/@herongxhr/network-status.svg) ![NPM Downloads](https://img.shields.io/npm/dm/@herongxhr/network-status.svg) ![License](https://img.shields.io/npm/l/@herongxhr/network-status.svg) ![Build Status](https://img.shields.io/github/actions/workflow/status/xai/@herongxhr/network-status/ci.yml) 一个轻量级的 Vue 3 可组合函数和可选模板，用于实时监控网络状态。本包提供了一个灵活的 `useNetworkStatus` 可组合函数来管理网络检测和信号强度，以及一个基于 Tailwind CSS 样式的可定制 `NetworkStatusTemplate` 组件，方便快速集成。 ## 特性 - **实时网络检测**：使用 `fetch` 请求监控网络状态，支持自定义检测间隔。 - **信号强度可视化**：根据延迟阈值显示 0-4 条信号条。 - **可定制警报**：支持离线、弱信号或无信号的自定义警报消息，3 秒自动关闭。 - **延迟格式化**：支持自定义延迟显示的小数位数（例如 `123.4` 毫秒）。 - **定位灵活**：支持多种警报位置（`top-right`、`bottom-left`、`center` 等）。 - **无头设计**：可自由使用可组合函数构建自定义 UI，或使用提供的 Tailwind 模板。 - **TypeScript 支持**：提供完整的类型定义，集成无缝。 ## 安装通过 npm 安装： ```bash npm install @herongxhr/network-status ``` ### 依赖要求需要 **Vue 3**： ```bash npm install vue@3 ``` ## 使用方法 ### 1. 使用 `useNetworkStatus` 可组合函数 `useNetworkStatus` 提供网络状态、延迟和警报的响应式状态，可集成到任何 Vue 3 组件中，搭配自定义 UI。 #### 示例：使用普通 CSS 的自定义 UI ```vue <template> <div class="network-container"> <div class="signal-bars"> <div v-for="(active, index) in signalBars" :key="index" :class="['bar', active ? signalClass : 'bg-gray-300']" :style="{ height: `${(index + 1) * 4}px` }" ></div> </div> <span class="status-text">{{ statusText }}</span> <span class="latency">{{ formattedLatency }} ms</span> <div v-if="showAlert" class="alert" :style="getPositionStyle(alertPosition)" > {{ alertMessage }} <button class="close-btn" @click="closeAlert">×</button> </div> </div> </template> <script setup lang="ts"> import { useNetworkStatus } from "@herongxhr/network-status"; const { networkStatus, formattedLatency, signalBars, statusText, showAlert, alertMessage, closeAlert, alertPosition, } = useNetworkStatus({ checkUrl: "https://your-api-endpoint.com/health", statusTexts: ["无信号", "信号很差", "信号较弱", "信号良好", "信号优秀"], alertMessages: ["离线了！", "信号丢失！", "信号很弱！"], checkInterval: 3000, decimalPlaces: 1, }); const signalClass = computed(() => { const status = networkStatus.value; if (status === 0) return "bg-gray-500"; if (status <= 1) return "bg-red-500"; if (status === 2) return "bg-yellow-500"; if (status === 3) return "bg-green-500"; return "bg-green-700"; }); const getPositionStyle = (position: string) => { const [vertical, horizontal] = position.split("-"); const style: { [key: string]: string } = {}; if (vertical === "top") style.top = "1rem"; else if (vertical === "bottom") style.bottom = "1rem"; if (horizontal === "left") style.left = "1rem"; else if (horizontal === "right") style.right = "1rem"; else if (horizontal === "center") { style.left = "50%"; style.transform = "translateX(-50%)"; } return style; }; </script> <style scoped> .network-container { position: absolute; top: 10px; right: 10px; display: flex; align-items: center; gap: 8px; padding: 6px; background: #fff; border: 1px solid #e2e8f0; border-radius: 4px; } .signal-bars { display: flex; gap: 2px; } .bar { width: 4px; transition: all 0.3s ease; } .status-text { font-size: 12px; color: #2d3748; } .latency { font-size: 12px; color: #4a5568; } .alert { position: fixed; padding: 8px 12px; background: #fef2f2; color: #741a1a; border-radius: 4px; box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1); } .close-btn { margin-left: 8px; border: none; background: none; color: #741a1a; cursor: pointer; } </style> ``` #### 注意事项 - **自定义 `checkUrl`**：提供可靠的健康检查端点以确保延迟检测准确。默认使用当前主机根路径 (`/`) 并附带警告。 - **延迟格式化**：使用 `decimalPlaces` 控制 `formattedLatency` 的精度（例如，`1` 表示 `123.4` 毫秒）。 ### 2. 使用 `NetworkStatusTemplate` 组件 `NetworkStatusTemplate` 组件提供基于 Tailwind CSS 的预构建 UI。 #### 示例：使用 Tailwind CSS 的模板 ```vue <template> <NetworkStatusTemplate position="bottom-right" position-offset="1.5rem" container-class="shadow-md bg-white dark:bg-gray-800" alert-class="bg-red-100 text-red-800" :status-texts="['无信号', '信号很差', '信号较弱', '信号良好', '信号优秀']" :alert-messages="['离线了！', '信号丢失！', '信号很弱！']" check-url="https://your-api-endpoint.com/health" check-interval="5000" decimal-places="2" /> </template> <script setup lang="ts"> import { NetworkStatusTemplate } from "@herongxhr/network-status"; </script> ``` #### 属性 | 属性 | 类型 | 默认值 | 描述 | | -------------------------- | ---------- | ----------------------------- | ---------------------------- | | `position` | `string` | `"top-right"` | 组件位置（`top-right` 等）。 | | `positionOffset` | `string` | `"1rem"` | 定位偏移量（例如 `1rem`）。 | | `containerClass` | `string` | `"h-4 flex ..."` | 主容器的 Tailwind 类。 | | `signalBarsContainerClass` | `string` | `"h-full py-[2px] ..."` | 信号条容器的类。 | | `signalBarClass` | `string` | `"transition-all ..."` | 单个信号条的类。 | | `statusTextContainerClass` | `string` | `"flex flex-col"` | 状态文本容器的类。 | | `statusTextClass` | `string` | `"h-full flex ..."` | 状态文本的类。 | | `latencyTextClass` | `string` | `"text-xs text-gray-600 ..."` | 延迟文本的类。 | | `alertClass` | `string` | `"p-2 rounded"` | 警报框的类。 | | `alertMessageClass` | `string` | `""` | 警报消息的类。 | | `closeButtonClass` | `string` | `"absolute top-1 ..."` | 关闭按钮的类。 | | `statusTexts` | `string[]` | `["无信号", ...]` | 5 个状态文本的数组。 | | `alertMessages` | `string[]` | `["离线了！", ...]` | 3 个警报消息的数组。 | | `checkUrl` | `string` | 当前主机 | 网络检测的 URL。 | | `checkInterval` | `number` | `5000` | 网络检测间隔（毫秒）。 | | `decimalPlaces` | `number` | `0` | 延迟显示的小数位数。 | #### 样式属性所有样式属性（例如 `containerStyle`、`signalBarStyle`）接受 `CSSProperties` 以进行内联 CSS 自定义。 ## API 参考 ### `useNetworkStatus(options?: NetworkStatusOptions)` #### 选项 | 属性 | 类型 | 默认值 | 描述 | | --------------- | ---------- | ------------------- | ------------------------------------------- | | `initialStatus` | `number` | `0` | 初始网络状态（0-4）。 | | `checkUrl` | `string` | 当前主机 (`/`) | 网络检测的 URL。 | | `alertPosition` | `string` | `"bottom-right"` | 警报框位置（`top-right` 等）。 | | `statusTexts` | `string[]` | `["无信号", ...]` | 5 个状态文本的数组。 | | `alertMessages` | `string[]` | `["离线了！", ...]` | 3 个警报消息的数组 [离线, 状态 0, 状态 1]。 | | `checkInterval` | `number` | `8000` | 网络检测间隔（毫秒）。 | | `decimalPlaces` | `number` | `0` | 延迟显示的小数位数。 | #### 返回值 | 属性 | 类型 | 描述 | | -------------------- | ------------------------ | ---------------------------------- | | `networkStatus` | `Ref<number>` | 当前网络状态（0-4）。 | | `latency` | `Ref<number>` | 原始延迟值（毫秒）。 | | `formattedLatency` | `ComputedRef<string>` | 格式化的延迟值，带指定小数位。 | | `signalBars` | `ComputedRef<boolean[]>` | 4 个布尔值的数组，表示信号条状态。 | | `statusText` | `ComputedRef<string>` | 当前状态文本。 | | `showAlert` | `Ref<boolean>` | 是否显示警报。 | | `alertMessage` | `ComputedRef<string>` | 当前警报消息。 | | `checkNetworkStatus` | `() => Promise<void>` | 手动检查网络状态。 | | `closeAlert` | `() => void` | 手动关闭警报。 | | `alertPosition` | `string` | 警报框位置。 | ## 贡献欢迎贡献！请按照以下步骤操作： 1. Fork 仓库。 2. 创建特性分支：`git checkout -b feature/new-feature` 3. 提交更改：`git commit -m 'Add new feature'` 4. 推送分支：`git push origin feature/new-feature` 5. 提交 Pull Request。 ### 开发设置 - 克隆仓库：`git clone https://github.com/xai/@herongxhr/network-status.git` - 安装依赖：`npm install` - 运行测试：`npm run test` - 构建包：`npm run build` ## 许可证 [MIT 许可证](LICENSE)