更新记录

1.0.0（2026-09-18） 下载此版本

  • 首发版本：H5 网络图片组件，进入视口才加载、切页自动取消在途请求释放同源连接。
  • 完整支持 uni-app image 的 14 种 mode（widthFix/heightFix 为纯 CSS 实现）。
  • 零依赖：loading 为纯 CSS spinner，error 为内联 svg，占位均可用插槽覆盖。
  • /static/ 本地资源自动补 H5 base 前缀。
  • 标准化 uni_modules 结构：components/halt-img/ 目录 + package.json。

平台兼容性

uni-app(4.0)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
- √ √ √ - - - - -
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
- - - - - - - - - - - -

其他

多语言 暗黑模式 宽屏模式
× × √

halt-img

H5 网络图片组件（vue3）。进入视口才真正发起请求；页面切到后台（onHide）时清空 src 取消所有在途请求，回到页面再恢复 —— 专为缓解「同源 HTTP/1.1 6 连接瓶颈」下的图片加载竞争设计。

特性

  • 原生惰性加载：基于浏览器 loading="lazy"（可选 :lazy-load="false" 关闭）。
  • 切页即停：onHide 置空 src，正在进行的请求被浏览器取消，即时释放同源连接；onShow 自动恢复。
  • 14 种 mode：完整支持 uni-app image 的全部 mode（scaleToFill/aspectFit/aspectFill/top/bottom/center/left/right/top left/top right/bottom left/bottom right/widthFix/heightFix）。
  • 宽高自适应：widthFix/heightFix 为纯 CSS 实现，无需 JS 测量尺寸。
  • 接口兼容 wd-img：props/事件/插槽沿用 wot-ui wd-img 的 API，<wd-img> 可直接替换为 <halt-img>。
  • 零依赖：不依赖任何 UI 库，loading/error 占位为纯 CSS + 内联 svg，均可用插槽覆盖。
  • 本地静态图自动补 base 前缀：/static/ 开头的资源会自动拼上 VITE_BASE（如 /mob/）。

平台

仅 H5（uni-app.vue.web 下标注支持，其余平台 -）。内部使用原生 <img>。

安装

  • 从插件市场导入：自动注册，<halt-img> 直接可用。
  • 手动：将 components/halt-img/ 拷入项目（easycom 规则 components/组件名/组件名.vue 自动适配）。

Props

属性 类型 默认值 说明
src string "" 图片地址（网络/相对路径，/static/ 自动补 base）
mode string "scaleToFill" 同 uni-app image 的 mode
width string | number - 宽度
height string | number - 高度
radius string | number - 圆角（设置后内部自动 overflow hidden）
round boolean false 圆形（边框半径最大）
lazyLoad boolean true 是否浏览器惰性加载
showLoading boolean true 加载中是否显示占位
showError boolean true 失败是否显示占位
enablePreview boolean false 点击是否弹预览
previewSrc string "" 预览大图地址（默认取 src）
customClass string "" 根节点自定义 class
customStyle string "" 根节点自定义 style
customImage string "" img 元素自定义 class

CSS 变量可覆盖默认占位颜色/尺寸：--halt-img-loading-bg、--halt-img-loading-icon-color、 --halt-img-error-bg、--halt-img-error-icon-color 等（默认灰底 + 灰色图标）。

事件

事件 回调参数 说明
load event img load
error event img error
click event 根节点点击

插槽

名称 说明
loading 加载中占位（默认 CSS spinner）
error 失败占位（默认 svg 图标）

示例

<template>
  <halt-img
    src="https://example.com/small/xxx.jpg"
    mode="aspectFill"
    width="100%"
    height="180px"
    :enablePreview="true"
    @load="onLoad"
    @error="onError"
  />
</template>

隐私、权限声明

1. 本插件需要申请的系统权限列表：

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

插件不采集任何数据

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

无

许可协议

MIT License

Copyright (c) 2026 bthnly

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

评论列表 撰写评论 向官方投诉
加载更多...