Network 网络状态

用于展示当前网络质量、离线状态和主动探测结果。

何时使用

• 页面需要提示用户当前网络是否可用、是否较慢。
• 提交、同步等操作依赖网络质量，需要在变差时给出轻量提示。
• 需要用业务自定义探测地址判断服务是否可达。

基础用法

--

<template>
  <x-network />
  <x-network status="poor" />
  <x-network status="offline" />
  <x-network show-metrics ping="/logo.svg" />
</template>

尺寸

<template>
  <x-network size="mini" status="good" />
  <x-network size="small" status="good" />
  <x-network size="medium" status="good" />
  <x-network size="large" status="good" />
</template>

受控状态

<script setup lang="ts">
import { ref } from 'vue';

const status = ref<'good' | 'medium' | 'poor' | 'offline'>('medium');
</script>

<template>
  <x-network :status="status" />
  <x-button @click="status = 'good'">良好</x-button>
  <x-button @click="status = 'offline'">离线</x-button>
</template>

传入 status 后，Network 只负责展示，不会启动浏览器网络监听或主动探测。

状态颜色

<template>
  <x-network status="good" :status-colors="{ good: '#0f766e' }" />
  <x-network status="poor" :status-colors="{ poor: '#dc2626' }" />
  <x-network status="medium" :signal-strength-color="['#2563eb', '#ea580c']" />
</template>

signalStrengthColor 保留旧版强/弱颜色配置；新项目更推荐使用 statusColors 按状态配置。

无障碍与悬浮提示

<template>
  <x-network status="medium" aria-label="当前网络略慢" />
  <x-network
    status="poor"
    show-tooltip
    aria-label="当前网络较差，请稍后提交"
    aria-live="assertive"
  />
</template>

默认不会把状态文案渲染到页面上；需要悬浮提示时再开启 showTooltip，无障碍名称始终可通过 ariaLabel 定制。

主动探测和事件

--

<script setup lang="ts">
import { ref } from 'vue';

const logs = ref<string[]>([]);

const pushLog = (status) => {
  logs.value = [`${status.quality} / ${status.source}`, ...logs.value].slice(0, 4);
};
</script>

<template>
  <x-network
    show-metrics
    ping="/logo.svg"
    :interval="8000"
    :timeout="3000"
    @change="pushLog"
    @probe="pushLog"
  />
</template>

未配置 ping 时，组件会读取 navigator.onLine 和 navigator.connection，并监听 online、offline 与连接变化事件。配置 ping 后，组件会以主动探测结果作为主要质量来源，并可显示本次探测的延迟和该探测资源的下载耗时估算。

探测失败和超时

--

<script setup lang="ts">
import { ref } from 'vue';

const logs = ref<string[]>([]);

const pushLog = (status) => {
  logs.value = [`${status.quality} / ${status.reason}`, ...logs.value].slice(0, 3);
};
</script>

<template>
  <x-network
    show-metrics
    ping="https://probe.invalid/ping"
    :timeout="1000"
    @probe="pushLog"
  />
</template>

主动探测失败会标记为 probe-error、probe-timeout 或 http-error，不会直接等同于浏览器离线。上面示例用 .invalid 保留域名（RFC 2606，永不解析）演示 probe-error；probe-timeout 需要目标地址真实存在但响应超时，不适合放在文档示例里长期依赖。

网络流速

--

<template>
  <x-network
    show-metrics
    ping="/logo.svg"
    :interval="8000"
  />
</template>

开启 showMetrics 后会显示 9ms 42K/s 这种紧凑指标。这里的流速只来自本组件对 ping 资源的主动探测，不能检测用户真实下载任务或整机实时流量。

自定义展示

网络状态：poorinitial

<template>
  <x-network>
    <template #default="{ quality, latency, refresh }">
      <span class="network-card">
        <strong>网络状态：{{ quality }}</strong>
        <span v-if="latency !== undefined">{{ latency }}ms</span>
        <button @click="refresh">重新检测</button>
      </span>
    </template>
  </x-network>
</template>

按需导入

import { Network } from 'x-next';

样式按需引入（base.css 为共享基础层，多个组件只需引入一次）：

import 'x-next/style/base.css';
import 'x-next/style/network.css';

Props

参数	说明	类型	默认值
size	信号图标尺寸	'mini' | 'small' | 'medium' | 'large'	'medium'
status	受控网络质量状态，传入后只展示不探测	'unknown' | 'good' | 'medium' | 'poor' | 'offline'	-
signalStrengthColor	兼容旧版强/弱信号颜色	[string, string]	['var(--x-network-color-good)', 'var(--x-network-color-poor)']
statusColors	按状态配置颜色	Partial<Record<NetworkQuality, string>>	{}
ping	用于主动探测的 URL，需要支持 CORS	string	-
interval	主动探测间隔，单位毫秒	number	-
timeout	主动探测超时时间，单位毫秒	number	5000
showMetrics	是否显示主动探测指标，包含延迟和下载估算，需要配合 ping 使用	boolean	false
showTooltip	是否把状态文案同步到 title	boolean	false
ariaLabel	自定义无障碍文案	string	-
ariaLive	状态变化播报策略	'off' | 'polite' | 'assertive'	'polite'

Events

事件名	说明	回调参数
change	网络状态刷新且语义字段发生变化时触发（quality、source、延迟与测速等一致时不重复派发）	status: NetworkStatus
online	从离线恢复到非离线时触发	status: NetworkStatus
offline	从非离线进入离线时触发	status: NetworkStatus
probe	主动探测完成时触发	status: NetworkStatus

Slots

插槽名	说明	参数
default	自定义网络状态展示	{ status, quality, online, latency, downloadSpeed, speedSource, source, reason, refresh }

Methods

方法名	说明
refresh	主动刷新网络状态；受控状态下只返回当前受控状态

状态对象

type NetworkQuality = 'unknown' | 'good' | 'medium' | 'poor' | 'offline';

interface NetworkStatus {
  online: boolean;
  quality: NetworkQuality;
  latency?: number;
  downloadSpeed?: number;
  speedSource?: 'probe';
  downlink?: number;
  rtt?: number;
  effectiveType?: string;
  source: 'navigator' | 'connection' | 'probe' | 'manual';
  reason?: 'initial' | 'browser-offline' | 'connection-change' | 'probe-timeout' | 'probe-error' | 'http-error' | 'unsupported';
  lastCheckedAt: number;
}

已知限制

• navigator.connection 是非标准能力，不是所有浏览器都支持。完全不支持时会按 navigator.onLine 判定（在线即视为良好）；支持但字段不全时回落到「检测中」，不会误判为网络较差。
• ping 探测 URL 需要允许跨域访问，否则会被记录为 probe-error，不会直接等价为系统离线。
• showMetrics 展示的是本组件主动探测请求推导出的延迟和下载估算值，不能检测用户真实下载任务或整机实时网络流量；未配置 ping 时不会得到完整指标。
• 网络质量是近似判断，适合做用户提示，不应作为安全、计费或强一致业务判断。
• 浏览器只提供 connection.onchange（不支持 addEventListener）时，组件会转发而不是替换已有处理器，并在卸载时归还；但同一时刻只能有一个 onchange 处理器，多个库同时降级到该槽位仍会相互影响。