企业官网建设流程全解析

• 编程语言
• 语言运行时
• 编译器
• 前端

本篇指南以 Brython 文档中关于browser包（www/doc/en/browser.md）的官方说明为主体，结合 www/src/builtin_modules.js 等源码实现，系统讲解 Brython（Browser Python，运行在浏览器中的 Python 3 实现）为 Python 开发者提供的浏览器内置命名空间与模块。读完本文，你将掌握alert/confirm/prompt对话框、document/window对象、事件绑定bind、动态加载 JavaScript 的load、动态执行 Python 的run_script，以及 Web Worker 上下文下的is_webworker与scope等全部核心 API 的用法与底层原理。

1.browser包是什么

在 Brython 中，browser是一个把浏览器原生能力包装成 Python 风格接口的内置包，它聚合了 Brython 特有的名称与模块。在 Python 脚本中直接from browser import ...即可使用，无需额外安装：

from browser import document, window, alert, console

从实现上看，browser包的初始化逻辑位于 www/src/builtin_modules.js（未压缩的构建产物在 www/src/brython.js）。该初始化会根据运行环境分三条路径处理：

• Node.js 环境（$B.isNode为真）：删除browser.window与browser.win；
• Web Worker 环境（$B.isWebWorker为真）：置browser.is_webworker = True，删除browser.window/browser.win，并把browser.document设置为一个访问即抛出ValueError（提示'document' is not available in Web Workers）的占位对象；
• 普通浏览器页面：注册alert、confirm、prompt、document、load、reload、URLParameter等全部成员。

此外，browser包还包含一系列按功能划分的子模块，位于 www/src/Lib/browser 目录，例如ajax.py、timer.py、local_storage.py、session_storage.py、indexed_db.py、object_storage.py、svg.py、template.py、websocket.py、worker.py、ui.py、markdown.py、highlight.py以及widgets/子包。本文聚焦browser包自身的核心成员。

2. 交互对话框：alert、confirm 与 prompt

2.1browser.alert(message)

在弹窗中打印message，返回None：

from browser import alert alert("Hello Brython!")

源码实现位于 www/src/builtin_modules.js：它调用浏览器原生的window.alert，并把消息强制转换为 Python 字符串（$B.builtins.str.$factory(message || "")），因此传入非字符串对象（如数字、列表）也能被正确转成字符串显示。

2.2browser.confirm(message)

在窗口中打印message并提供 ok/cancel 两个按钮。用户点击 ok 返回True，点击 cancel 返回False：

from browser import confirm if confirm("确定要删除吗？"): # 用户点击了 ok pass

其实现是直接包装原生window.confirm（www/src/builtin_modules.js）。

2.3browser.prompt(message[, default])

打印message并显示一个输入框。返回用户输入的值；如果未输入任何值，返回default（若提供了该参数），否则返回空字符串：

from browser import prompt name = prompt("请输入你的名字：", "匿名用户") print("你好，", name)

实现上它包装了原生window.prompt(message, default_value || '')（www/src/builtin_modules.js），所以第二个参数缺省时等价于传入空字符串作为默认值，与文档所述"未输入则返回空字符串"一致。

这三个函数都是同步阻塞的，会暂停脚本直到用户做出响应，适用于确认流程、简单数据录入等场景；在 Web Worker 中它们不可用。

3. 文档对象模型：document、DOMNode 与 DOMEvent

3.1browser.document

document表示当前浏览器窗口中显示的 HTML 文档，是操作页面的入口对象。文档中说明其接口详见 "Browser interface" 章节，即官方文档的 DOM API 指南 与 属性与样式。典型用法：

from browser import document # 按 id 获取元素并修改文本 document["greeting"].text = "Hello Brython!" # 遍历所有 <p> 标签 for p in document.select("p"): print(p.text)

从实现看，document是$B.DOMNode.$factory(document)的包装（www/src/builtin_modules.js），即把浏览器的document对象包装成 Python 的DOMNode实例。源码中还提供了别名browser.doc，与document等价。

3.2browser.DOMNode与browser.DOMEvent

• DOMNode：DOM 节点的类，document本身以及通过document[...]、document.select(...)取到的元素都是它的实例，封装了属性读写、事件绑定、子节点操作等接口；
• DOMEvent：DOM 事件的类，事件回调函数的第一个参数即DOMEvent实例，携带type、target、坐标等事件信息。

两者在 www/src/builtin_modules.js 中直接暴露给 Python 层，对应 www/src/py_dom.js 中的事件与节点实现。

3.3browser.window

window表示浏览器窗口对象（接口定义参见 MDN 的 Window 文档）。通过它可以访问全局 JavaScript 对象、执行window.setTimeout等，例如：

from browser import window # 调用 window 上的 JavaScript 全局函数 window.console.log("来自 Brython 的日志")

3.4browser.URLParameter(name)与browser.mouseCoords(ev)（源码补充成员）

除文档列出的成员外，www/src/builtin_modules.js 还注册了两个实用函数：

• URLParameter(name)：解析当前页面 URL 查询串，返回名为name的参数值（已做 URL 解码），无匹配时返回空字符串；
• mouseCoords(ev)：从事件对象中提取鼠标坐标。

4. 事件绑定装饰器：browser.bind(target, event)

bind(target, event)是一个用作事件绑定装饰器的函数，用法详见 事件处理指南：

from browser import document, bind @bind(document["mybutton"], "click") def on_click(event): print("按钮被点击了") # 也可以绑定到一组元素或字符串选择器 @bind("#mybutton", "click") # 通过 CSS 选择器 def on_click2(event): print("selector 方式绑定")

从 www/src/brython.js 的实现可见，bind支持多种target：

• 单个DOMNode元素：直接addEventListener；
• CSS 选择器字符串：用document.querySelectorAll遍历绑定；
• 可迭代对象（如元素列表）：逐个绑定。

绑定成功后返回原回调函数，因此可以继续作为装饰器使用，且回调会在事件触发时自动捕获并处理 Python 异常。

5. 浏览器控制台：browser.console

console是用于与浏览器控制台交互的对象，其完整接口随浏览器而异，但至少暴露log(msg)方法，把消息打印到控制台：

from browser import console console.log("调试信息")

实现上（www/src/builtin_modules.js 与 www/src/brython.js）它直接把浏览器的原生console对象包装为 Python 对象（self.console && $B.jsobj2pyobj(self.console)），因此现代浏览器中通常还支持console.warn、console.error等方法，但文档保证的最少接口是log。仓库测试代码中随处可见这一用法，例如 www/tests/console.py 与 www/tests/editor.py 都通过from browser import ... console ...导入。

6. 动态加载 JavaScript 库：browser.load(script_url)

load(script_url)用于加载位于script_url的 JavaScript 库：

from browser import load # 加载第三方 JS 库（例如某个图表库） load("https://example.com/lib.js") # 库注入到全局命名空间的名字，可经 window 对象访问 from browser import window window.LibClass

文档强调两点使用约束：

1. 它使用阻塞式 Ajax 调用。加载完成前脚本会等待，因此适用于"无法在 HTML 页面里通过<script src="prog.js"></script>加载"的场景；
2. 库注入到 JavaScript 全局命名空间的名字，在 Brython 脚本中通过window对象的属性访问。

从 www/src/builtin_modules.js 的源码看，load的实际流程是：用$B.builtins.open(script_url)读取文件内容，然后eval(content)执行——这与文档"阻塞式 Ajax 调用"的描述吻合。

补充：同文件还实现了异步版本load1(script_url, callback)（www/src/builtin_modules.js），它创建<script>标签追加到document.body实现非阻塞加载，并可传入回调函数在加载完成后执行。它未在文档中列出，但属于browser包的可用成员。

7. 动态执行 Python：browser.run_script(src[, name])

run_script(src[, name])执行src中的 Python 源码，可选的name用于标识这段脚本：

from browser import run_script run_script("x = 42\nprint(x * 2)") # 控制台输出 84

它可作为exec()的替代方案，额外的收益是：从标准库导入模块时会使用 indexedDB 缓存，从而加速重复导入。这一特性与 www/src/Lib/browser/indexed_db.py 以及 idbcache 机制（www/src/Lib/browser/idbcache.py）相关。

从实现看（www/src/brython.js），run_script会调用$B.runPythonSource(src, name)，当name缺省时自动生成默认名"script_" + UUID（$B.UUID()）。而 www/src/brython_builtins.js 中的$B.runPythonSource会创建一个模拟 HTML<script>标签（fakeScript）并调用$B.run_script(script, src, script_id, url, true)，从而复用与页面内<script type="text/python">完全相同的编译与执行管线，并返回对应的已导入模块对象。

8. Web Worker 上下文：browser.is_webworker 与 browser.scope

8.1browser.is_webworker

布尔值，指示当前脚本是否在 Web Worker 中执行：

from browser import is_webworker, document if is_webworker: # Worker 中没有 document，访问会抛 ValueError ... else: document["status"].text = "主线程运行中"

结合 www/src/builtin_modules.js 的初始化逻辑，Worker 环境下is_webworker为True，且browser.document访问时会抛出ValueError: 'document' is not available in Web Workers；主线程环境下为False。Brython 的 Web Worker 用法可进一步参考 Web Worker 文档 与 browser.worker 模块。

8.2browser.scope

scope是对浏览器中可用命名空间的引用，无论执行上下文是普通脚本还是 Web Worker都有效，等价于 JavaScript 的globalThis。它用于在两种上下文中统一访问全局对象：

from browser import scope # 在 Web Worker 中也能通过 scope 访问全局 API scope.postMessage("hello")

实现上scope直接映射为globalThis（www/src/brython.js）。

9. 综合示例：把这些 API 串起来

结合仓库测试（如 www/tests/console.py、www/tests/dom.py、www/tests/editor.py）中的常见写法，一个典型的交互页面脚本如下：

from browser import document, alert, confirm, prompt, bind, console, window @bind(document["ask"], "click") def ask(ev): name = prompt("你的名字？", "") if confirm(f"确认名字是 {name} 吗？"): document["result"].text = f"你好，{name}！" alert("欢迎使用 Brython") console.log("用户完成交互，名字:", name) @bind("#reload-lib", "click") def load_lib(ev): window.location.reload()

要点回顾：

• alert/confirm/prompt处理同步交互；
• bind+document完成事件与 DOM 操作；
• console输出调试信息；
• window桥接 JavaScript 全局能力；
• 动态 JS 库用load，动态 Python 代码用run_script；
• 涉及 Worker 时用is_webworker判断环境、用scope访问全局。

更完整的 DOM 操作、属性与样式细节，可继续阅读 DOM API 指南、属性与样式 与 事件处理；browser包下的ajax、timer、local_storage等子模块分别对应 Ajax 文档、Timer 文档、Local Storage 文档 等官方指南。

• 编程语言
• 语言运行时
• 编译器
• 前端