@herongxhr/network-status v0.0.2

@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>

属性

样式属性

所有样式属性（例如 containerStyle、signalBarStyle）接受 CSSProperties 以进行内联 CSS 自定义。

API 参考

useNetworkStatus(options?: NetworkStatusOptions)

选项

返回值

贡献

欢迎贡献！请按照以下步骤操作：

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