跳到主要内容

窗口交互控制

窗口拖动区域（app-region）​

用途：自己做自定义标题栏时，要告诉系统「这一块区域可以用鼠标拖动窗口」，而按钮区域不要拖动。用 CSS 的 app-region 或 -webkit-app-region（二者等价，选一种即可）。

常用写法：标题条设为 drag，上面的按钮设为 no-drag。

.title-bar {
  -webkit-app-region: drag;
  app-region: drag;
}
.title-bar button {
  -webkit-app-region: no-drag;
  app-region: no-drag;
}
<div class="title-bar" style="-webkit-app-region: drag; app-region: drag;">
  <h1>我的应用</h1>
  <div class="title-bar-buttons">
    <button type="button" style="-webkit-app-region: no-drag; app-region: no-drag;">关闭</button>
  </div>
</div>

和 2.0 创建窗口 API 的配合​

  • 要不要系统标题栏、要不要边框，由 WebViewWindowOptions.frame_style 决定（normal / no-titlebar / borderless / title-overlay），不要再填已删除的旧字段。
  • 需要整块无边框 WebView 壳子时，用 create_borderless_webview_window，见 窗口 API。

内置标题栏按钮覆盖层（title-overlay）​

用途：Windows 专属样式，提供有边框+无标题栏+右上角内置标题栏按钮的效果，无需自行实现窗口控制按钮功能。

特点​

  • 窗口有边框但无系统标题栏
  • 右上角自动绘制最小化、最大化、关闭按钮
  • 使用 Windows 10/11 风格的 Segoe MDL2 Assets 图标
  • 按钮背景透明，悬浮时显示背景色
  • 关闭按钮悬浮时显示红色背景 + 白色图标
  • 完全无需前端实现按钮交互逻辑

使用方式​

创建窗口时设置 frame_style 为 title-overlay：

WebViewWindowOptions options = {0};
options.title = "My App";
options.width = 800;
options.height = 600;
options.frame_style = "title-overlay";
// ... 其他选项

或运行时动态切换：

set_window_frame_style(window_id, "title-overlay");

自定义样式​

通过 set_titlebar_overlay_style 可自定义按钮外观：

// 自定义按钮高度和颜色
set_titlebar_overlay_style(
    window_id,
    32,          // 按钮高度（像素）
    "#FFFFFF",   // 图标颜色（白色）
    "#333333"    // 悬浮背景色（深灰色）
);
信息

title-overlay 样式仅 Windows 平台支持。在其他平台上会回退到 no-titlebar 样式。

右键菜单控制（jade-allow-contextmenu）​

用途：按元素粒度控制右键菜单是否允许弹出。当 WebViewSettings.disable_right_click 全局禁用右键时，可通过此属性为特定元素单独放行。

基本用法​

<!-- 允许弹出右键菜单 -->
<button jade-allow-contextmenu>右键我</button>

<!-- 禁止弹出右键菜单（默认行为） -->
<button>右键我也没用</button>

注意事项​

  • 优先级：元素同时设置了 disabled 属性时，jade-allow-contextmenu 不生效
  • 全局设置：WebViewSettings 中 disable_right_click=0（不全局禁用）时，此属性被忽略，页面任意处都可弹出右键
  • 默认行为：未设置此属性的元素默认不允许弹出右键菜单

动态控制​

const el = document.getElementById('my-element');
el.setAttribute('jade-allow-contextmenu', '');     // 允许
el.removeAttribute('jade-allow-contextmenu');      // 禁止

故障排除​

拖动区域不工作​

  • 确保属性名正确：-webkit-app-region 或 app-region
  • 检查按钮区域是否正确设置了 no-drag，避免嵌套覆盖

右键菜单不弹出​

  • 检查元素是否设置了 disabled 属性
  • 确认 WebViewSettings.disable_right_click 为 1（全局禁用右键），否则 jade-allow-contextmenu 无意义
  • 确保 jade-allow-contextmenu 属性已正确添加到目标元素