Cordova - 事件

Cordova - 基本事件 (Essential Events)

Cordova 应用可以监听并响应与应用生命周期和设备硬件交互相关的各种事件 (events)。理解和使用这些事件对于构建响应迅速、行为良好的混合应用 (hybrid apps) 至关重要。

常见的 Cordova 事件

以下是 Cordova 核心或常用插件 (plugins) 提供的重要事件列表：

事件名称 (Event Name)	描述 (Description)
`deviceready`	当 Cordova 完全加载并且其 API (应用程序接口) 可用时触发。这是最重要的事件，应作为任何 Cordova 特定初始化代码的入口点。
`pause`	当应用进入后台时触发（例如，用户切换到其他应用或锁定屏幕）。
`resume`	当应用从后台恢复并进入前台时触发。
`backbutton`	当用户按下设备的物理或虚拟返回按钮时触发（主要在 Android 上，但某些其他平台可能也支持）。
`menubutton`	当用户按下菜单按钮时触发（在现代设备上不太常见）。
`searchbutton`	当用户在 Android 上按下搜索按钮时触发。
`volumedownbutton`	当用户按下降低音量硬件按钮时触发。
`volumeupbutton`	当用户按下提高音量硬件按钮时触发。
`online`	当应用变为在线时触发（设备获得网络连接）。
`offline`	当应用变为离线时触发（设备失去网络连接）。（这些是标准的 HTML5 事件，但在 Cordova 中非常相关）

注意：像 startcallbutton 和 endcallbutton 这样的事件在历史上被提及过，但现在不太常见或仅限于特定平台。请务必查阅特定插件的文档，了解它们提供的事件。

使用事件：最佳实践

始终使用 document.addEventListener() 或 window.addEventListener() 附加事件监听器 (event listeners)。避免使用内联事件处理程序 (inline event handlers)（例如 HTML 中的 onclick="..."），因为它们通常不被推荐，并且可能违反内容安全策略 (Content Security Policy - CSP) 规则。

示例：`deviceready`

这是基础事件。您的应用中依赖于 Cordova API 的主要逻辑应从此处开始执行。

// In your main JavaScript file (e.g., www/js/index.js)
// 在您的主 JavaScript 文件中（例如 www/js/index.js）
document.addEventListener('deviceready', onDeviceReady, false);

function onDeviceReady() {
    // Cordova is now initialized. Plugins are ready.
    // Cordova 已初始化。插件已准备就绪。
    console.log('Running cordova-' + cordova.platformId + '@' + cordova.version);
    console.log('Device is ready!');
    // Initialize your app, attach other event listeners, etc.
    // 初始化您的应用，附加其他事件监听器等。
    document.getElementById('app').innerHTML = 'Device is ready!'; // Example update

    // Example: Attach listener for pause event
    // 示例：为 pause 事件附加监听器
    document.addEventListener('pause', onPause, false);
    document.addEventListener('resume', onResume, false);
    document.addEventListener('backbutton', onBackButton, true); // `true` for capture phase if needed, usually false
    // `true` 用于捕获阶段（如果需要），通常为 false
}

示例：`pause` 和 `resume`

当应用进入后台时，这些事件可用于保存状态、暂停活动（如游戏或媒体）或释放资源；当应用恢复时，可用于恢复这些资源。

function onPause() {
    console.log('App paused');
    // TODO: Pause ongoing tasks, save state, release resources (e.g., camera, GPS).
    // TODO: 暂停正在进行的任务，保存状态，释放资源（例如相机、GPS）。
}

function onResume() {
    console.log('App resumed');
    // TODO: Resume tasks, restore state, re-acquire resources if needed.
    // TODO: 恢复任务，恢复状态，如果需要重新获取资源。
    // Example: Check for network status or refresh data.
    // 示例：检查网络状态或刷新数据。
}

示例：处理 `backbutton`（Android）

默认情况下，Android 上的返回按钮会退出应用。您可以重写此行为以实现自定义导航（例如，在应用内返回上一个屏幕、关闭模态框 (modal)）或在退出前请求确认。

function onBackButton(event) {
    console.log('Back button pressed');
    // To prevent the default action (exiting the app), call preventDefault().
    // 为了阻止默认行为（退出应用），调用 preventDefault()。
    event.preventDefault();

    // Example: Simple confirm dialog before exiting
    // 示例：退出前简单的确认对话框
    if (confirm("Are you sure you want to exit?")) {
        // `navigator.app.exitApp()` is a Cordova API to close the app programmatically.
        // `navigator.app.exitApp()` 是一个 Cordova API，用于以编程方式关闭应用。
        if (navigator.app && navigator.app.exitApp) {
            navigator.app.exitApp();
        } else {
            console.warn('navigator.app.exitApp not available. This might be a browser environment or missing plugin.');
            // navigator.app.exitApp 不可用。这可能是在浏览器环境中或缺少插件。
        }
    } else {
        console.log('Exit cancelled by user.');
        // Do nothing, or handle other back navigation logic for your app's UI.
        // 什么也不做，或者处理应用 UI 的其他返回导航逻辑。
    }
}

**重要提示：**如果您重写了 backbutton 事件，则您将负责所有的返回导航逻辑。如果您不调用 event.preventDefault()，则在您的处理程序运行后，默认行为仍然会发生。如果您调用了 preventDefault()，请确保您的应用在适当的时候提供了返回或退出的方式。

示例：硬件音量按钮

您可以监听硬件音量按钮的按下事件，以实现自定义音量控制或其他操作。

// Inside onDeviceReady or another appropriate initialization point
// 在 onDeviceReady 或其他合适的初始化点内
document.addEventListener("volumeupbutton", onVolumeUp, false);
document.addEventListener("volumedownbutton", onVolumeDown, false);

function onVolumeUp() {
    alert('Volume Up Button pressed!');
    // Implement custom logic, e.g., increase app-specific volume
    // 实现自定义逻辑，例如增加应用特定音量
}

function onVolumeDown() {
    alert('Volume Down Button pressed!');
    // Implement custom logic, e.g., decrease app-specific volume
    // 实现自定义逻辑，例如降低应用特定音量
}

注意：重写音量按钮可能会干扰操作系统的原生音量处理。请谨慎使用，主要用于在特定上下文（例如游戏）中，如果默认行为不是您想要的，则进行应用内的音量调整。

关键注意事项

deviceready 至关重要：几乎所有与 Cordova 相关的事件监听器（尤其是硬件按钮或插件事件）都应注册在 deviceready 处理程序内部或之后，以确保 Cordova 环境完全初始化。
平台差异性：并非所有事件都在所有平台上支持。例如，backbutton 主要是一个 Android 概念。请务必在您的目标平台 (target platforms) 上进行测试。
事件传播 (Event Propagation)：理解事件如何传播（冒泡 (bubbling) 和捕获 (capturing)）。addEventListener 的第三个参数（useCapture，默认为 false）可以控制这一点。
移除监听器：如果您添加了事件监听器，尤其是在特定的 DOM 元素上或对于频繁触发的事件，请记住在不再需要时使用 removeEventListener 移除它（例如，当视图被销毁时），以防止内存泄漏 (memory leaks) 或意外行为。
内容安全策略 (CSP)：如前所述，请使用 addEventListener。内联 JavaScript（<button onclick="myFunction()">）通常是不良实践，并可能被您的 CSP 阻止。
插件特定事件：许多 Cordova 插件会触发它们自己的自定义事件。请务必查阅您使用的插件文档，了解它们是否提供了您可以订阅的事件。

通过有效使用 Cordova 事件，您可以创建与设备功能平滑集成的应用程序，并提供更类似原生应用的用户体验 (User Experience - UX)。