更新记录

1.0.0（2026-07-22）

• 首次发布图片毛玻璃虚化组件。
• 支持网络图片、本地图片和 Android file://、content:// 地址。
• 支持模糊强度、降采样、显示模式、圆角、叠色和触摸开关。
• 支持 load、ready、error 事件以及 load、reload、clear 方法。

平台兼容性

uni-app(3.7.11)

uni-app x(3.8.0)

其他

kongbai-filter-image

原生图片毛玻璃虚化组件，基于 UTS 原生 View 实现。组件直接处理图片内容，支持网络图片、本地图片以及 Android file://、content:// 地址。

特性

• iOS 使用 Core Image 高斯模糊。
• Android 12 及以上使用系统 GPU 模糊；低版本使用降采样原生图片处理。
• 支持图片裁剪模式、圆角、叠色和动态调整模糊强度。
• 图片加载和处理在后台执行，完成后通过事件通知页面。

支持平台

组件依赖 App 原生运行环境，请使用自定义基座或云打包后的 App 运行。

安装

通过插件市场安装后，组件会放在项目的 uni_modules/kongbai-filter-image 目录中。安装完成后可以直接在页面模板中使用，无需额外注册组件。

基础用法

<template>
  <view class="page">
    <kongbai-filter-image
      class="image"
      src="/static/demo.jpg"
      :blur="28"
      :downsample="4"
      scaleMode="cover"
      :cornerRadius="20"
      tintColor="#FFFFFF"
      :tintOpacity="0.04"
      @ready="onReady"
      @error="onError"
    />
    <text class="status">{{loadState}}</text>
  </view>
</template>

<script setup lang="uts">
const loadState = ref('loading')

const onReady = () : void => {
  loadState.value = 'ready'
}

const onError = () : void => {
  loadState.value = 'error'
}
</script>

<style>
.page {
  width: 750rpx;
  padding: 24rpx;
}

.image {
  width: 702rpx;
  height: 420rpx;
}

.status {
  margin-top: 16rpx;
  color: #666666;
  font-size: 24rpx;
}
</style>

属性

事件

错误码：

• load_failed：图片无法加载、解码失败或地址不可访问。

方法

通过组件实例调用以下方法：

参数建议

普通图片建议使用：

<kongbai-filter-image
  class="image"
  src="/static/demo.jpg"
  :blur="28"
  :downsample="4"
  :tintOpacity="0.04"
  scaleMode="cover"
/>

需要更明显的虚化时，将 blur 调整到 36-54；大尺寸图片或列表场景建议提高 downsample，并控制同时显示的组件数量。

图片地址与权限

• 加载网络图片需要应用具备网络访问权限，Android 插件已声明 INTERNET 权限。
• 网络图片建议使用 https:// 地址，并确保服务器允许 App 访问。
• 本地图片请确认路径属于当前 App 可访问的资源或文件目录。
• 组件不缓存图片，也不上传图片内容；网络请求仅用于读取调用方传入的地址。

版本

当前版本：1.0.0