tmui4x 2.0(Vapor)

主题

TMUI4x2026-09-21
1071
4.2m

x-screentgrey-s 应用置灰 ​

哀悼日等场景把界面置灰。标准 -s API 插件，对齐 DCloud success / fail / complete。

整 App 与当前页是两套函数：

  • setAppGrey / removeAppGrey：作用在窗口根层，翻到其它页也保持灰色（微信除外）。
  • setPageGrey / removePageGrey：只灰当前页，其它页不受影响。

旧写法 setWindowGrey / removeWindowGrey 已移除，请改用上面两套函数。

兼容性 ​

能力AndroidiOSHarmonyOSWEB微信小程序
整 App 置灰支持（Activity 根视图 ColorMatrix）支持（窗口饱和度叠加层，iOS 13+）支持（setWindowGrayScale）支持（documentElement filter）仅当前页，需传 ele，翻页不保持
当前页置灰支持（页面根 View）支持（当前页 UIView 叠加层）支持（节点 grayscale，否则当前页作用域窗口灰阶）支持（当前页 HTML 节点）支持，需传 ele
amount 0–1支持不支持，大于 0 即全灰支持支持支持

Android / iOS 请打自定义基座。iOS 在 Mac 本机编译可不打包；Windows 开发 iOS 需要打包基座。

调用 ​

ts
import {
  setAppGrey,
  removeAppGrey,
  setPageGrey,
  removePageGrey,
  getScreenGreyState,
  getScreenGreyCapabilities,
  XScreenGreyOptions,
  XScreenGreyFailInfo,
  XScreenGreyResult
} from "@/uni_modules/x-screentgrey-s"

const caps = getScreenGreyCapabilities()

setAppGrey({
  success: (res : XScreenGreyResult) => {
    console.log(res.appGrey)
  },
  fail: (err : XScreenGreyFailInfo) => {
    console.log(err.errCode, err.errMsg)
  }
} as XScreenGreyOptions)

setPageGrey({
  ele: pageRoot, // 微信必传；其它端可省略，自动取当前页根节点
  amount: 1
} as XScreenGreyOptions)

removePageGrey({} as XScreenGreyOptions)
removeAppGrey({} as XScreenGreyOptions)

方法 ​

名称说明
setAppGrey整 App 置灰。建议在启动页或需要全站哀悼时调用一次
removeAppGrey取消整 App 置灰
setPageGrey仅当前页置灰
removePageGrey取消当前页置灰
getScreenGreyState查询当前开关状态
getScreenGreyCapabilities同步返回平台能力

参数 ​

XScreenGreyOptions

字段说明默认
ele目标节点。单页置灰可不传；微信整 App / 单页都建议传当前页根节点-
amount灰度 0–1。iOS 只能全灰或关闭1
success成功，带 appGrey / pageGrey-
fail失败-
complete结束，成功带结果，失败为 null-

错误码：1001 系统错误，1002 参数错误，1003 找不到目标节点，1008 当前平台不支持。

平台差异 ​

Android

  • 整 App：对当前 Activity decorView 以及栈内每个页面的 getAndroidView() 做 ColorMatrix.setSaturation(1 - amount) + LAYER_TYPE_HARDWARE。新页面往往自带硬件层，不会继承窗口根滤镜，因此会拦截路由并在 Activity onResume 时重新套上。
  • 当前页：对 UniPage.getAndroidView() 或传入节点的原生 View 做同样处理；取消单页置灰时若整 App 仍开着，该页保持 App 灰色。
  • 取消时恢复 LAYER_TYPE_NONE。

iOS（deploymentTarget 12，置灰需 iOS 13+）

  • 使用 saturationBlendMode 浅灰叠加层，不拦截触摸。
  • 整 App 加在 keyWindow 上，翻页仍盖住新页面。
  • 当前页加在当前页根 UIView 上。
  • amount 不生效，大于 0 即全灰。低于 iOS 13 返回 1008。

HarmonyOS

  • 整 App：Window.setWindowGrayScale(amount)，窗口级，翻页保持。
  • 当前页：鸿蒙 ucss 不支持 CSS filter，写 filter: grayscale() 不会生效。实现上会尽量给页面节点加 ArkUI grayscale，并以当前页作用域的 setWindowGrayScale 保证看得见；跳转离开时恢复彩色，返回该页时再置灰。redirectTo / reLaunch 或返回后页面已销毁则清除单页状态。

Web

  • 整 App：document.documentElement 的 CSS filter。
  • 当前页：当前页 HTML 根节点的 CSS filter。

微信小程序

  • 没有窗口级滤镜。setAppGrey 与 setPageGrey 都作用在传入的 ele 上。
  • appGreyPersist 为 false：新开页面不会自动变灰，需要在该页再调一次。

版本 ​

版权归 https://xui.tmui.design 你不得修改及二次开发，仅供 TMUI4 会员商用使用。不得转给非 VIP 会员使用，一经查实数倍赔偿，并追究法律责任。

更新日志 ​

1.1.2（2026-08-20） ​

  • 修复 Android 整 App 置灰只作用于当前页：翻页后新页不再继承 decorView 硬件层滤镜。现会记住灰度并在每个页面 View、新 Activity 恢复时重新套上。

1.1.1（2026-08-20） ​

  • 修复 HarmonyOS 当前页置灰无效：鸿蒙 ucss 不支持 CSS filter，改为节点 grayscale；找不到节点时用当前页作用域的窗口灰阶，跳转时恢复彩色。

1.1.0（2026-08-20） ​

  • 改为 DCloud 风格 options + success/fail/complete，五端 API 对齐。
  • 拆成整 App 置灰 setAppGrey 与当前页置灰 setPageGrey 两套函数。
  • 补齐 HarmonyOS 窗口灰阶、Web / 微信滤镜，以及状态与能力查询。
  • 旧 API setWindowGrey / removeWindowGrey 已移除。

1.0.0（2024-08-31） ​

首次发布

最近更新