@herongxhr/network-status

一个轻量级的 Vue 3 可组合函数和可选模板，用于实时监控网络状态。本包提供了一个灵活的 useNetworkStatus 可组合函数来管理网络检测和信号强度，以及一个基于 Tailwind CSS 样式的可定制 NetworkStatusTemplate 组件，方便快速集成。

特性

• 实时网络检测：使用 fetch 请求监控网络状态，支持自定义检测间隔。
• 信号强度可视化：根据延迟阈值显示 0-4 条信号条。
• 可定制警报：支持离线、弱信号或无信号的自定义警报消息，3 秒自动关闭。
• 延迟格式化：支持自定义延迟显示的小数位数（例如 123.4 毫秒）。
• 定位灵活：支持多种警报位置（top-right、bottom-left、center 等）。
• 无头设计：可自由使用可组合函数构建自定义 UI，或使用提供的 Tailwind 模板。
• TypeScript 支持：提供完整的类型定义，集成无缝。

安装

通过 npm 安装：

npm install @herongxhr/network-status

依赖要求

需要 Vue 3：

npm install vue@3

使用方法

1. 使用 useNetworkStatus 可组合函数

useNetworkStatus 提供网络状态、延迟和警报的响应式状态，可集成到任何 Vue 3 组件中，搭配自定义 UI。

示例：使用普通 CSS 的自定义 UI

<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 的模板

<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 许可证