浏览器（webbrowser）

Y++ / YStudio 开发文档 · 一点滴

选择器： webbrowser · 设计器组件： 浏览器 · 按名称： webbrowser#名称 或 #名称
运行时： WebView2（需本机安装 Edge WebView2 运行时）

硬约束与叠画

控件名来自窗口 XML「名称」；属性赋值无括号（如 标题 = "确定"），方法调用必须带括号（如 刷新()）。
事件写 函数控件名.事件名(参数…)，形参类型以本页事件表为准。
任意控件客户区叠画用支持库绘制类：绘制类 g → g.绑组件(本控件名)（组件名无引号）。画布场景编辑见画布控件。
字体对象见绘制文档中的字体类；置字体(字体类) 将字体应用到本控件。
不要虚构未列出的方法；YSS 键见下文与 YSS.md。

属性

设计器属性面板与代码侧可读可写属性（来源：组件类库）。

属性	类型	读写	说明
`提示`	文本	读写	鼠标悬停时的提示文字
`鼠标指针`	文本	读写	空=默认；可用 arrow/hand/ibeam/cross/wait/no/sizeall 等预设，或.cur/.ani 路径（如资源/press.cur）
`左边`	小数	读写	相对窗体左边的位置（像素）
`顶边`	小数	读写	相对窗体顶边的位置（像素）
`宽度`	小数	读写	控件宽度（像素）
`高度`	小数	读写	控件高度（像素）
`停靠`	整数	读写	0无 1上 2下 3左 4右 5填充；菜单/工具/状态栏仍用专用吸附
`可见`	逻辑	读写	真=显示，假=隐藏
`启用`	逻辑	读写	真=可用，假=禁用
`句柄`	长整数	只读	组件逻辑句柄（1 起，供动画类等绑定；非 HWND）；只读
`网址`	文本	读写	初始/当前导航地址，如 https://example.com；运行时赋值等同导航()
`缩放`	整数	读写	百分比，100=100%，范围约 25～500；也可置缩放/取缩放
`允许新窗口`	逻辑	读写	真=新窗口请求在本页打开（仍触发「新窗口请求」事件）；假=拦截新窗口
`静音`	逻辑	读写	真=页面音频静音；也可置静音()
`圆角`	整数	读写	像素，0=直角（设计期占位外观）
`显示边框`	逻辑	读写	真=显示边框
`边框大小`	整数	读写	像素
`边框颜色`	文本	读写	如 #RRGGBB
`背景色`	文本	读写	如 #1E1E1E（加载前占位底色）

方法

调用必须带括号。多数导航/脚本方法返回逻辑（失败假）。缩放 1.0=100%。脚本对话框类型：0提示 · 1确认 · 2输入。下表为带类型签名。

方法	签名	返回	说明
`导航`	`逻辑导航(文本网址或路径)`	逻辑	http(s) 或本地 html
`置HTML`	`逻辑置HTML(文本内容)`	逻辑
`后退`	`逻辑后退()`	逻辑
`前进`	`逻辑前进()`	逻辑
`重新加载`	`逻辑重新加载()`	逻辑
`强制刷新`	`逻辑强制刷新()`	逻辑
`停止`	`逻辑停止()`	逻辑
`可否后退`	`逻辑可否后退()`	逻辑
`可否前进`	`逻辑可否前进()`	逻辑
`取网址`	`文本取网址()`	文本
`取文档标题`	`文本取文档标题()`	文本
`执行脚本`	`文本执行脚本(文本脚本)`	文本
`取HTML`	`文本取HTML()`	文本
`取选中文本`	`文本取选中文本()`	文本
`打印`	`逻辑打印()`	逻辑
`打开开发者工具`	`逻辑打开开发者工具()`	逻辑
`置缩放`	`逻辑置缩放(小数倍率)`	逻辑	`1.0`=100%
`取缩放`	`小数取缩放()`	小数
`发消息到网页`	`逻辑发消息到网页(文本消息)`	逻辑	网页侧收消息
`注入脚本`	`逻辑注入脚本(文本脚本)`	逻辑
`置Cookie`	`逻辑置Cookie(文本名称, 文本值, 文本域, 文本路径)`	逻辑
`取Cookie`	`文本取Cookie(文本名称, 文本网址)`	文本
`清除Cookie`	`逻辑清除Cookie()`	逻辑
`清除缓存`	`逻辑清除缓存()`	逻辑
`捕获截图`	`逻辑捕获截图(文本文件路径)`	逻辑	PNG
`置静音`	`逻辑置静音(逻辑静音)`	逻辑
`置用户代理`	`逻辑置用户代理(文本代理串)`	逻辑	空串恢复默认
`取用户代理`	`文本取用户代理()`	文本
`是否就绪`	`逻辑是否就绪()`	逻辑	就绪后再导航/脚本更安全
`查找`	`逻辑查找(文本关键词)`	逻辑
`查找下一个`	`逻辑查找下一个()`	逻辑
`停止查找`	`逻辑停止查找()`	逻辑
`调用调试协议`	`文本调用调试协议(文本方法, [文本参数JSON="{}"])`	文本	DevTools
`移动`	`无移动(小数左边, 小数顶边, [小数宽度], [小数高度])`	无	可选同时改宽高
`置焦点`	`无置焦点()`	无
`刷新`	`无刷新()`	无
`显示`	`无显示()`	无	等同 `可见 = 真`
`隐藏`	`无隐藏()`	无	等同 `可见 = 假`
`订阅/取消订阅调试事件`	`逻辑 *(文本事件名)`	逻辑
`置字体`	`逻辑置字体(字体类字体)`	逻辑

如果 (浏览器1.是否就绪()) {
    浏览器1.导航("https://www.example.com")
}
文本 t = 浏览器1.执行脚本("document.title")

事件

在代码中写 函数控件名.事件名(...) 处理。专用：

事件	参数
`开始导航`	`文本网址`
`导航完成`	`文本网址, 逻辑成功, 整数状态码`
`标题改变` / `网址改变`	`文本 …`
`历史改变`	`逻辑可后退, 逻辑可前进`
`新窗口请求` / `下载开始` / `证书错误`	`文本网址`
`收到网页消息`	`文本消息`
`权限请求`	`文本内容, 整数类型`
`脚本对话框`	`文本内容, 整数类型`
`就绪`	无
`全屏改变`	`逻辑全屏`
`收到调试事件`	`文本消息`

其余鼠标/焦点事件见下表。

事件	参数	说明
`单击`	整数 X, 整数 Y	鼠标左键单击控件。
`双击`	整数 X, 整数 Y	鼠标左键双击控件。
`右键单击`	整数 X, 整数 Y	鼠标右键单击控件。
`鼠标按下`	整数 X, 整数 Y, 逻辑按下	鼠标键在控件上按下。按下=真表示当前仍按住。
`鼠标抬起`	整数 X, 整数 Y, 逻辑按下	鼠标键在控件上放开。
`鼠标移动`	整数 X, 整数 Y, 逻辑按下	鼠标在控件上移动。按下表示左键是否按住。
`鼠标进入`	整数 X, 整数 Y	鼠标指针进入控件区域。
`鼠标离开`	整数 X, 整数 Y	鼠标指针离开控件区域。
`鼠标左键单击`	整数 X, 整数 Y	鼠标左键单击（与「单击」同时触发）。
`鼠标左键双击`	整数 X, 整数 Y	鼠标左键双击（与「双击」同时触发）。
`鼠标中间单击`	整数 X, 整数 Y	鼠标中键单击控件。
`鼠标齿轮滚动`	整数 X, 整数 Y, 逻辑向上	在控件上滚动鼠标滚轮。向上=真表示向上滚。
`鼠标右键单击`	整数 X, 整数 Y	鼠标右键单击（与「右键单击」同时触发）。
`鼠标右键双击`	整数 X, 整数 Y	鼠标右键双击控件。
`开始导航`	文本网址	即将导航到新地址时触发（含导航/置HTML/前进后退）。参数：文本网址。
`导航完成`	文本网址, 逻辑成功, 整数状态码	页面导航结束时触发。参数：文本网址, 逻辑成功, 整数状态码（HTTP；失败时可能为 0）。
`标题改变`	文本标题	文档标题变化时触发。参数：文本标题。
`网址改变`	文本网址	当前页 URI 变化时触发（地址栏同步用）。参数：文本网址。
`历史改变`	逻辑可后退, 逻辑可前进	前进/后退可用性变化时触发。参数：逻辑可后退, 逻辑可前进。
`下载开始`	文本网址	开始下载时触发。参数：文本网址。
`权限请求`	文本内容, 整数类型	页面请求权限（相机/麦克风/地理位置等）。参数：文本内容, 整数类型。
`脚本对话框`	文本内容, 整数类型	alert/confirm/prompt。参数：文本内容, 整数类型（0提示/1确认/2输入）。
`就绪`	无	WebView2 控件创建完成、可调用导航/脚本等方法时触发（建议在此再导航）。
`全屏改变`	逻辑全屏	页面全屏元素进入/退出时触发。参数：逻辑全屏。
`证书错误`	文本网址	HTTPS 证书错误时触发。参数：文本网址。

函数 浏览器1.单击 (整数 X, 整数 Y) {
    // …
}

YSS 样式

以下为样式表（.yss）键与示例；写样式前请先读窗体 XML 取控件 名称 与 typeId，见 window-xml.md。

布局与子选择器

设计期为占位绘制（标注「设计预览」）；F5/发布后才创建真实 WebView2。建议在「就绪」事件后再导航或置 HTML。

属性说明（逐键）

浏览器以网页内容为主，YSS 只管控件外壳（加载前底色与边框），不样式化页内 DOM。网址、UA、缩放、静音等用属性面板或代码（见「代码侧」）。

属性	作用	取值 / 范围	说明与注意
`background-color` / `background`	加载前占位底色	颜色，如 `#1E1E1E`	设计期占位与 WebView2 创建前可见
`border-color`	外壳边框色	颜色
`border-width`	外壳边框宽	像素
`border-radius`	外壳圆角	像素	只圆角外壳，不裁剪网页（WebView2 HWND 叠层）
`show-border`	是否画外壳边框	`true`/`false`

嵌入资源 HTML： 导航(":/页.html") 会物化为临时 file://；页内相对路径的 css/图片/脚本可能失效，请内联或改用绝对 :/…。详见 resource-embed.md。

XML / 设计器 ↔ YSS

设计器 / 代码	YSS
外壳底色 / 边框 / 圆角	`background-color`、`border-*`、`show-border`、`border-radius`（不裁剪网页）
网址、UA、缩放、静音、HTML	属性或代码，不是 YSS
页内 CSS / DOM	网页自己写；YSS 管不到 WebView2 内容

使用示例

深色外壳边框：

webbrowser#浏览器1 {
    background-color: #1E1E1E;
    border-color: #5A5A5A;
    border-width: 1;
    border-radius: 4;
    show-border: true;
}

无边框占位底：

webbrowser#内嵌页 {
    background-color: #FFFFFF;
    show-border: false;
}

完整示例

webbrowser {
    background-color: #1E1E1E;
    border-color: #5A5A5A;
    border-width: 1;
    border-radius: 4;
    show-border: true;
}

webbrowser#浏览器1 {
    background-color: #101010;
    border-radius: 6;
}