桌面应用开发工具【免费下载链接】MooToolHandy tool set for developers项目地址https://gitcode.com/gh_mirrors/mo/MooTool点击查看免费下载MooToolnext-compose是采用 Compose Multiplatform 构建的桌面工具集其系统托盘菜单提供了「屏幕取色」与「区域截图」两个高频入口功能行为需要与既有 Electron 版本next/electron严格对齐。本文以next-compose/docs/fixtures/electron-next-tray-capture-vitest.md为骨架围绕TrayDesktopActionsScreenColorSampler.captureAllScreens()的调用链系统讲解 Compose 端如何完成跨屏屏幕捕获、macOS TCC「屏幕录制」权限的失败重试与隐私设置深链、错误文案映射体系以及自动化测试与产品证据脚本对行为一致性的验证。读完本文你将掌握在 AWT/Compose 桌面应用中正确处理 macOS 屏幕捕获权限的完整工程方案并理解它与 ElectrondesktopCapturer方案的差异。一、对照总览托盘取色 / 截图的 Electron 与 Compose 行为映射原文档以一张对照表给出了四个核心场景的 Electron / Compose 行为映射这是理解整套设计的关键入口完整继承如下场景Electron行为Compose截屏权限被拒系统/主进程错误提示ScreenCaptureFailureMessages.trayCaptureMessageColorException(permission)见 DIFF-527打开系统屏幕录制设置macOS 隐私面板ScreenCaptureAccess.openPrivacySettingsIfNeededcolor.error.permissionSettingsTCC 产品窗证据手工 PNG脚本恢复基线帧prepare-tray-screencapture-evidence.shreference/57-color-baseline.png见 DIFF-528图片工具区域截图失败工具页 error 行ScreenCaptureFailureMessages.imageOperationMessagepermission 与image.error.*同路径表格传达的核心设计原则是托盘取色、托盘区域截图、调色板工具F22取色、图片工具F23区域截图四条入口共享同一条权限处理与错误映射链路而不是各自实现一套。下文的源码分析将围绕这条共享链路展开。原文档同时保留了手工验收要求托盘菜单「屏幕取色」「区域截图」需在未授权与授权后两种状态下各走查一次parity-gap 验收项仍列为未测见 2026-09-14 奇偶差异证据。二、托盘入口与调用链TrayDesktopActions托盘菜单的构建位于 Main.kt通过AppTrayModel将菜单项回调直接绑定到TrayDesktopActionsonColorPicker { TrayDesktopActions.pickColor(container, ::showMain) }, onScreenshot { TrayDesktopActions.captureScreenshot(container, ::showMain) },TrayDesktopActions.kt中两个方法的骨架高度一致可概括为以下步骤showWindow()唤出主窗口并通过container.openTool(...)切到目标工具页ToolId.ColorBoard或ToolId.Image写入会话状态session.picking true、清空error、设置notice为「处理中」提示common.processing并sessionManager.bump()通知 UI 刷新在Dispatchers.Default后台线程执行runCatching { ScreenColorSampler.captureAllScreens() }捕获全屏回到Dispatchers.Swing主线程处理结果成功则弹出取色/区域选择浮层失败则调用ScreenCaptureFailureMessages.trayCaptureMessage(...)把异常翻译成用户可读的错误文案写入session.error。取色路径成功后通过ScreenColorPicker.show(image, copy, onPicked {...}, onCancel {...})展示取色浮层onPicked回调把选定颜色写入session.primary并用ColorEngine.formatColor(color, session.format)按当前格式HEX 大写 / HEX 小写 / RGB生成颜色码。截图路径则用ScreenRegionPicker.show(...)让用户框选区域选中后经container.imageLibrary.save(ImageEngine.timestampName(Screenshot), region, false)以时间戳命名保存到图片库并提示image.imported。三、屏幕捕获核心多屏拼接画布与采样ScreenColorSampler.captureAllScreens()是全部截屏入口共用的底层函数位于 ScreenColorSampler.kt。它并不直接依赖系统 API 的多屏捕获而是用 AWT 实现跨屏拼接通过GraphicsEnvironment.getLocalGraphicsEnvironment().screenDevices枚举所有屏幕设备对所有设备的defaultConfiguration.bounds求并集union得到覆盖全部屏幕的虚拟画布逐设备创建Robot(device)对每个屏幕执行createScreenCapture(Rectangle(0, 0, bounds.width, bounds.height))再按(bounds.x - union.x, bounds.y - union.y)的偏移量把每屏画面绘制到一张BufferedImage.TYPE_INT_RGB拼接图上无屏幕devices.isEmpty()或边界为空union.width 0 || union.height 0时抛出ColorException(picker, ...)捕获过程中抛出任何Exception时统一包装为ColorException(permission, ...)。完成拼接后还有一个关键防御步骤isUniformBlack(mosaic)按 1/32 步长抽样整幅画布若所有采样点均为纯黑getRGB(...) 0xffffff 0则判定权限被拒返回的是黑屏直接抛出ColorException(permission, Screen capture returned a blank image; grant screen recording permission and retry)。这是对 macOS TCC 未授权时截屏行为的一种工程兜底权限被拒时捕获结果往往是一张空/黑帧仅凭异常并不足以可靠区分所有情况。拼接后的ScreenCapture(originX, originY, image)还提供两个采样工具colorAt(capture, screenX, screenY)把屏幕全局坐标减去origin映射到拼接画布坐标读取像素并拆解出RgbColor(r, g, b)zoom(capture, screenX, screenY, radius 5, scale 8)以目标像素为中心取(2*radius1)邻域按scale放大成局部放大图供取色浮层的放大镜预览使用。四、权限失败重试与 macOS TCC 隐私设置深链这是文档对照表中权限被拒与打开系统屏幕录制设置两行所对应的核心实现位于 ScreenColorSampler.kt 的ScreenCaptureAccess与captureAllScreens。4.1 两级重试策略captureAllScreens()的完整流程如下return try { captureAllScreensOnce() } catch (first: ColorException) { if (first.code ! permission) throw first // 非权限错误直接透传 ScreenCaptureAccess.promptIfNeeded() // 第一次被拒尝试触发 TCC 授权弹窗 try { captureAllScreensOnce() // 重试 } catch (retry: ColorException) { val opened ScreenCaptureAccess.openPrivacySettingsIfNeeded() // 仍失败打开系统隐私设置 if (retry.code permission) { throw ColorException(permission, ..., openedSettings opened) } throw retry } }即首次权限失败 → 触发 TCC 授权提示 → 重试一次 → 仍失败则打开 macOS 屏幕录制设置面板并带上openedSettings标记。openedSettings这个标记决定了错误文案是否追加已尝试打开系统设置的第二行提示是整个友好引导用户授权体验的关键状态。4.2 触发 TCC 提示与设置深链ScreenCaptureAccess内部封装了三个 macOS 专属能力macPrivacySettingsUri()返回x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture这是 macOS 的「系统设置 → 隐私与安全性 → 屏幕录制」深链 URIpromptIfNeeded()仅在 macOS 上通过ProcessBuilder(screencapture, -x, -R, 0,0,1,1, tmpPng)捕获一个 1×1 像素的临时区域利用screencapture命令自身触发系统 TCC 授权弹窗随后在finally中删除临时文件openPrivacySettingsIfNeeded()通过ProcessBuilder(open, macPrivacySettingsUri())打开系统隐私设置面板成功返回true。4.3 双行错误文案userMessage(t, error)负责把ColorException翻译为用户提示当异常code为permission或picker时取color.error.permission作为基础文案若openedSettings true再追加换行后的color.error.permissionSettings即已打开系统设置引导文案其余未知异常回退到error.message或color.error.generic。五、错误消息映射体系三条共享路径ScreenCaptureFailureMessages.kt是文档表格第一、四行所涉错误映射的实体提供了三个面向不同入口的消息函数trayCaptureMessage(t, error)供托盘取色与托盘区域截图使用TrayDesktopActions的两个失败分支都调用它。ColorException走ScreenCaptureAccess.userMessageImageException复用imageOperationMessage的映射未知异常回退image.error.capture或异常原文。imageOperationMessage(t, error)供图片工具页使用。先处理ImageException的业务码invalid-base64→image.error.base64、invalid-image/unsupported→image.error.image、watermark-text→image.error.watermark、too-large→image.error.tooLarge、too-many→image.error.tooMany、cancelled→image.cancelled、missing→image.error.missing、exists→image.error.exists当异常是ColorException且 code 为permission/picker时与托盘路径共用ScreenCaptureAccess.userMessage——这正是文档所说permission 与image.error.*同路径。colorPickerMessage(t, error)供调色板工具页的取色入口使用invalid-hex/invalid-rgb映射为color.error.invalid权限错误同样复用userMessage。ColorException定义在 ColorEngine.kt结构为ColorException(code: String, message: String, openedSettings: Boolean false)。调用侧调色板页的pickScreen失败后经notifyColorFailure→colorPickerMessage见 ColorBoardScreen.kt 的pickScreen与messageFor图片工具页的notifyImageFailure→imageOperationMessage见 ImageScreen.kt 的messageFor。六、自动化测试行为一致性的单元级保障权限与错误映射的行为一致性由桌面测试套件保障运行命令为./gradlew :composeApp:desktopTest --offlineJDK 21。ScreenCaptureFailureMessagesTest.kt覆盖四个用例trayCaptureUsesPermissionCopyWhenSettingsOpenedtrayCaptureMessage收到ColorException(permission, ..., openedSettings true)时文案同时包含color.error.permission与color.error.permissionSettingstrayCaptureFallsBackToCaptureKeyForUnknownErrors空消息未知异常回退image.error.capture带消息的未知异常则透传原文imageOperationMapsPermissionAndImageCodes验证missing业务码映射以及ColorException(permission)在imageOperationMessage中走权限路径、openedSettings true时拼接双行文案colorPickerMapsInvalidAndPermission验证invalid-hex→color.error.invalid、picker→color.error.permission。ScreenColorSamplerTest.kt则覆盖坐标与文案两个维度samplesNegativeOriginAndZooms构造originX -10, originY 20的负偏移画布验证colorAt对全局坐标的换算(-9, 20)与(-10, 20)分别取到不同像素并验证zoom输出尺寸为(2*radius1)*scale 12×12、中心像素保持原色permissionCopyOpensMacScreenCapturePane断言macPrivacySettingsUri()包含Privacy_ScreenCapture片段并验证userMessage在openedSettings为true/false时分别产出单行与双行文案。七、TCC 产品证据与手工验收脚本对照表第三行对应产品证据脚本与基线帧。prepare-tray-screencapture-evidence.sh脚本文件以无 GUI 方式准备托盘/TCC 屏幕录制验收环境逻辑如下从docs/evidence/2026-09-15-inspector-screencapture/windows/57-color.png恢复基线帧到docs/evidence/2026-09-17-tray-tcc-screencapture/reference/57-color-baseline.png若不存在才复制保证幂等打印手工验收步骤清单mootool_evidence_print_tray_tcc_hint系统设置 → 隐私 → 屏幕录制取消勾选 MooTool或首次启动时拒绝托盘菜单 → 取色 / 区域截图应出现color.error.permission文案对应ScreenCaptureFailureMessagesTestF22 调色板 / F23 图片助手的屏幕取色同上且可选出现打开系统设置双行文案授予权限后重试应成功并登记结果到docs/evidence/2026-09-17-tray-tcc-screencapture/results.md。该脚本同时被 verify-product-evidence-prep.sh 与ProductEvidencePrepScriptTest.prepareTrayScreencaptureScriptRestoresBaselinePng覆盖校验。验收结果文档 results.md 明确了基线帧是调色板工具页截图非 TCC 系统对话框并列出未执行则标记未测的手工项清单。八、与 Electron 实现的行为差异与对齐要点对照表提及 Electron 侧系统/主进程错误提示其真实实现位于 next/electron/main/index.ts可作为行为对齐的参照Electron 在screen:captureIPC handler 与startScreenCapture中先隐藏所有可见窗口、delay(180)等待画面稳定再调用desktopCapturer.getSources({ types: [screen], thumbnailSize: {...}, fetchWindowIcons: false })枚举屏幕源并按screen.getAllDisplays()的最大缩放分辨率确定缩略图尺寸捕获结束后在finally中恢复隐藏的窗口并重新聚焦空源displays.length 0 || availableSources.length 0时抛出No display is available for capture——与 Compose 端ColorException(picker, No screen is available)的语义对应托盘与工具页通过screen:capture-region、screen-color:pick两条 IPC 通道复用同一个startScreenCapture会话ScreenCaptureSession overlay 记录这与 Compose 端托盘与工具页共享captureAllScreens权限重试路径的设计意图一致关键差异Electron 的截图权限问题会以系统级错误呈现desktopCapturer在 macOS 无屏幕录制权限时的行为由操作系统/主进程提示承担而 ComposeJVM/AWT没有等价的系统对话框因此必须由应用自身实现触发 TCC 提示 → 重试 → 深链打开系统设置的完整引导闭环。这正是 DIFF-527 与 DIFF-528 两个切片的核心工作。九、小结MooTool Compose 桌面端把托盘取色、托盘区域截图、调色板取色、图片工具截图四条入口收敛到一条共享链路TrayDesktopActions入口编排→ScreenColorSampler.captureAllScreens()AWT 多屏拼接捕获 权限两级重试→ScreenCaptureAccessTCC 触发与系统设置深链→ScreenCaptureFailureMessages按入口分派错误映射。对照文档中每一行行为都能在源码、测试或证据脚本中找到落点这为后续手工验收未授权/授权后各走查一次提供了可复现的基线也为其他 JVM 桌面应用处理 macOS 屏幕录制权限提供了一份可直接参考的工程范本。赞分享桌面应用开发工具【免费下载链接】MooToolHandy tool set for developers项目地址https://gitcode.com/gh_mirrors/mo/MooTool点击查看免费下载相关推荐MooTool Next Compose 的 macOS 屏幕录制 TCC 权限处理托盘取色与区域截图的产品验收方案及底层实现MooTool Next Compose 的 macOS 屏幕录制 TCC 权限处理托盘取色与区域截图的产品验收方案及底层实现 本篇技术指南围绕 MooToo桌面应用开发工具MooTool Compose Desktop 屏幕取色实现剖析AWT Robot 冻结截图替代 Electron desktopCapturerMooTool Compose Desktop 屏幕取色实现剖析AWT Robot 冻结截图替代 Electron desktopCapturer 本文基于桌面应用开发工具MooTool Compose 版 JSON Vault「打开目录与刷新」实现机制解析Electron 对齐MooTool Compose 版 JSON Vault「打开目录与刷新」实现机制解析Electron 对齐 JSON Vault 是 MooTool 中用桌面应用开发工具上一篇Civitai 完整指南如何从找到 AI 模型到一键部署下一篇Sunshine游戏串流终极指南5步搭建你的私人云游戏平台创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
