如何在使用WKWebView加载网页时显示「添加到主屏幕」选项？

首先得明确：iOS系统里的「添加到主屏幕」（Add to Home Screen，简称A2HS）功能，核心依赖网页满足PWA可安装条件，再配合WKWebView的配置和交互实现。下面分步骤拆解：

一、确保网页符合PWA可安装要求 #

这是基础，否则系统不会识别为可安装应用：

• 网页必须通过HTTPS协议加载（本地localhost调试除外）
• 根目录下存在manifest.json文件，包含必要字段：

  {
    "name": "你的应用名称",
    "short_name": "短名称",
    "start_url": "/",
    "display": "standalone", // 必须是standalone/fullscreen/minimal-ui中的一种
    "icons": [
      {
        "src": "/icon-192x192.png",
        "sizes": "192x192",
        "type": "image/png"
      },
      {
        "src": "/icon-512x512.png",
        "sizes": "512x512",
        "type": "image/png"
      }
    ]
  }
  

• 网页必须注册Service Worker，并且支持离线缓存（iOS 11.3+支持）

二、WKWebView的配置与权限设置 #

1. 启用必要的WebKit特性 #

在初始化WKWebView时，需要配置WKWebViewConfiguration，确保允许相关特性：

let config = WKWebViewConfiguration()
// 启用JavaScript（默认已启用，但确保没关闭）
config.preferences.javaScriptEnabled = true
// 允许自动播放、弹窗等（根据需求调整，部分PWA需要）
config.mediaTypesRequiringUserActionForPlayback = []
// iOS 16.4+：允许Web App安装提示
if #available(iOS 16.4, *) {
    config.defaultWebpagePreferences.allowsContentJavaScript = true
}

let webView = WKWebView(frame: view.bounds, configuration: config)
view.addSubview(webView)

2. 监听PWA安装触发事件（iOS 16.4+） #

从iOS 16.4开始，WKWebView支持beforeinstallprompt事件，你可以监听这个事件，自定义触发「添加到主屏幕」的按钮：

// 先让WKWebView的导航代理设置为当前ViewController
webView.navigationDelegate = self

// 在WKNavigationDelegate的方法中注入监听脚本
func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
    if #available(iOS 16.4, *) {
        let script = """
        window.addEventListener('beforeinstallprompt', (event) => {
            // 阻止系统默认提示
            event.preventDefault();
            // 将事件保存到全局，供原生调用
            window.deferredPrompt = event;
            // 通知原生可以显示安装按钮
            window.webkit.messageHandlers.installPromptAvailable.postMessage(null);
        });
        """
        webView.evaluateJavaScript(script) { result, error in
            if let error = error {
                print("注入脚本失败：\(error)")
            }
        }
    }
}

接着，设置WKScriptMessageHandler接收网页通知，显示自定义安装按钮：

// 实现WKScriptMessageHandler协议
extension ViewController: WKScriptMessageHandler {
    func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
        if message.name == "installPromptAvailable" {
            // 显示自定义的安装按钮，比如在导航栏或网页底部
            showInstallButton()
        }
    }
}

// 点击安装按钮时，触发网页的安装流程
func installButtonTapped() {
    if #available(iOS 16.4, *) {
        webView.evaluateJavaScript("""
        if (window.deferredPrompt) {
            window.deferredPrompt.prompt();
            window.deferredPrompt.userChoice.then((choiceResult) => {
                if (choiceResult.outcome === 'accepted') {
                    console.log('用户同意安装');
                } else {
                    console.log('用户拒绝安装');
                }
                window.deferredPrompt = null;
            });
        }
        """)
    }
}

三、iOS 16.4之前的替代方案 #

旧版本iOS中WKWebView不支持beforeinstallprompt，只能通过引导方式实现：

• 在网页中添加自定义按钮，引导用户点击系统分享菜单（Safari的分享按钮），选择「添加到主屏幕」
• 在原生App中添加提示，告诉用户可以长按WKWebView导航栏（如果有），或使用系统分享功能完成添加
• 注意：只有网页满足PWA条件时，Safari的分享菜单才会显示「添加到主屏幕」选项

四、常见问题排查 #

如果「添加到主屏幕」选项不出现，检查以下几点：

• 网页是否通过HTTPS加载（本地调试除外）
• manifest.json的字段是否完整，尤其是display和icons
• Service Worker是否正确注册并激活
• iOS版本是否支持对应PWA特性（iOS 11.3+支持Service Worker，iOS 16.4+支持WKWebView的beforeinstallprompt）

内容的提问来源于stack exchange，提问作者Crashalot