文档中心

setGameQueryClipboardListener ​

设置小游戏剪切板操作请求监听器 ​

setGameQueryClipboardListener 用于管控小游戏对 系统剪切板（Clipboard） 的访问。

出于隐私保护，当游戏尝试通过 JS API（如 wx.setClipboardData 或 wx.getClipboardData）写入或读取文本时，SDK 会触发此监听器。这允许宿主 App 决定是否允许该操作，或在操作前后添加自定义逻辑（如记录日志、敏感词过滤或弹出原生提示）。

方法声明 ​

java
/**
 * 设置小游戏剪切板操作请求监听器。
 * @param listener 监听器实例。传入 null 则取消监听（默认行为由 SDK 处理）。
 */
void setGameQueryClipboardListener(@Nullable SUDRTGameHandle.GameQueryClipboardListener listener);

内部接口与 Handle ​

java
public interface GameQueryClipboardListener {
    /** 申请设置剪切板数据时调用 */
    void onSetClipboardData(@NonNull SUDRTGameHandle.GameQueryClipboardHandle handle, @NonNull String data);

    /** 申请获取剪切板数据时调用 */
    void onGetClipboardData(@NonNull SUDRTGameHandle.GameQueryClipboardHandle handle, @NonNull String data);
}

public interface GameQueryClipboardHandle {
    /** 允许操作，并返回数据（设置时传 data，获取时由 App 决定返回什么） */
    void success(@NonNull String data);

    /** 拒绝操作 */
    void failure();
}

运行行为 ​

  1. 隐私拦截：在 Android 10+ 及更高版本中，后台应用或未经用户确认的剪切板读取通常受到限制。此监听器让 App 能够在原生层处理这些系统限制。
  2. 数据转换：在 onGetClipboardData 中，App 甚至可以拦截并篡改返回给游戏的数据（例如过滤掉敏感信息后再传给 JS）。
  3. 默认反馈：如果不设置此监听器，SDK 通常会尝试直接操作剪切板并向 JS 返回结果，但在某些机型上可能因为权限问题导致静默失败。

代码示例 ​

java
gameHandle.setGameQueryClipboardListener(new SUDRTGameHandle.GameQueryClipboardListener() {
    @Override
    public void onSetClipboardData(@NonNull SUDRTGameHandle.GameQueryClipboardHandle handle, @NonNull String data) {
        // 1. 小游戏尝试复制文字到剪切板
        Log.d("SUDOP", "Game is copying: " + data);
        
        // 2. App 可以在此进行敏感词过滤或长度限制
        if (data.length() > 1000) {
            handle.failure();
            showToast("内容过长，禁止复制");
            return;
        }

        // 3. 允许写入并反馈成功
        handle.success(data);
        showToast("复制成功");
    }

    @Override
    public void onGetClipboardData(@NonNull SUDRTGameHandle.GameQueryClipboardHandle handle, @NonNull String data) {
        // 4. 小游戏尝试读取剪切板
        // data 参数在这里通常是系统当前的剪切板内容
        
        // 5. 处于隐私考虑，可以在此处弹出原生 Dialog 询问用户
        showConfirmDialog("游戏申请读取您的剪切板内容，是否允许？", new Callback() {
            @Override
            public void onAgree() {
                handle.success(data);
            }
            @Override
            public void onDeny() {
                handle.failure();
            }
        });
    }
});

注意事项 ​

  • 必须回调：无论是调用 handle.success() 还是 handle.failure()，都必须执行其中之一，否则 JS 层的异步 Promise 将永远处于 Pending 状态。
  • 空字符串处理：在调用 success(data) 时，请确保 data 不为 null（根据 @NonNull 约束）。
  • UI 提示：小游戏环境通常无法直接弹出系统级 Toast，建议在 onSetClipboardData 成功后，由 App 弹出原生的“复制成功”提示以提升体验。