企业官网建设流程全解析

• 前端

本文围绕 Beaker 浏览器项目中 app/userland/app-stdlib/readme.md 定义的应用标准库展开：它是一套被 Beaker 全部默认应用（userland apps）复用的 JS 与 Web Components 集合，其核心构建命令node scripts/generate-css-js.js把原始 CSS 编译为 ES Module 形式的*.css.js。读完本文，你将掌握该标准库的目录结构、样式构建/监听脚本的工作原理、可复用的组件与工具 API，以及它们如何通过beaker://app-stdlib协议被 editor、cmd-pkg 等用户态应用消费。

一、什么是 Beaker 应用标准库

在 Beaker 这个实验性 P2P 浏览器中，/app/userland目录存放所有用户态前端应用，每个文件夹在beaker://下拥有独立的域名。为了让这些应用共享统一的样式与交互组件，Beaker 维护了 app/userland/app-stdlib 这个“应用标准库”（Application Standard Library）：

A collection of JS and Web Components which are used across Beaker's default applications.

它主要由三部分构成：

• CSS 体系：以*.css原始文件 + 同名*.css.jsES Module 双轨存在；
• Web Components 组件：基于 LitElement 封装的下拉菜单、Toast 通知、悬浮卡片、图片回退等；
• 纯工具函数：字符串、时间、DOM、剪贴板、emoji、Hyperdrive 文件系统辅助等。

从 app/userland/README.md 可以看到设计意图：beaker://app-stdlib提供被所有 userland 应用复用的组件；在可行的情况下 userland 应用不做打包构建，仅当需要与 Beaker 内部代码共享代码时才引入构建步骤。

二、目录结构总览

标准库根目录（app/userland/app-stdlib）下的六个一级子目录分工明确：

值得注意的还有vendor/（如 app/userland/app-stdlib/vendor/lit-element/lit-element.js），标准库内部自带 LitElement 与 lit-html 运行时；js/vs/下则内嵌了完整的 Monaco Editor 内核（editor.main.js及数十种basic-languages语言支持）。

三、核心构建脚本：generate-css-js.js

readme 中给出的唯一命令是：

node scripts/generate-css-js.js

它负责把css/目录下所有*.css编译为可供 ES Module 直接import的*.css.js文件。其实现位于 app/userland/app-stdlib/scripts/generate-css-js.js，核心流程如下：

1. 递归扫描：handleFolder(cssdir)递归遍历css/及其子目录（如css/com/），凡是以.css结尾的文件都调用handleCSSFile()；
2. 读取原始 CSS：以 UTF-8 读入文件内容；
3. 替换@import：extractAndReplaceImports()用正则^@import "([^"]*)";$（多行模式）逐行匹配 CSS 导入，将其替换为模板字符串插值${varname}，同时把导入语句转换为对应的 JS import；
4. 写出*.css.js：最终文件形如：

import {css} from '<相对路径>/lit-element.js' import resetcss from './reset.css.js' const cssStr = css` ${resetcss} ... ` export default cssStr

cssPathToJsPath()实现了文件名映射：reset.css→reset.css.js（截掉.css后缀再追加.css.js）。变量名则由路径末段去点去连字符生成，例如./reset.less会变成import resetless from './reset.less.js'。

以 app/userland/app-stdlib/css/common.css.js 为例，编译产物把reset、typography、buttons、inputs四份子样式以模板插值聚合，再补充body默认背景与文字色，最终export default cssStr。

开发时监听模式

配套脚本 app/userland/app-stdlib/scripts/css-watcher.js 提供文件监听能力：通过fs.watch(css, {recursive: true})监控css/目录，任何.css变更都会在 500ms 防抖后自动重新执行generate-css-js.js，实现改样式即热更新，适合在开发 Beaker 默认应用时持续使用：

node scripts/css-watcher.js

四、CSS 设计体系：CSS 变量与暗黑模式

标准库的样式以“变量驱动”为设计核心，app/userland/app-stdlib/css/colors.css 在body上定义了一整套--text-color-*、--bg-color-*、--border-color-*语义变量，并通过@media (prefers-color-scheme: dark)提供暗色主题覆盖。例如链接色在亮色下为--text-color--link: #4040e7，暗色下切换为#5d80ff。组件样式（如dropdown.css、toast.css）同样内置暗色分支，因此应用无需额外处理主题切换。

各基础样式文件职责如下：

• reset.css：统一box-sizing: border-box、清除body外边距、按钮与链接的默认样式；
• typography.css：定义--system-font与--code-font两套字体变量并应用到body/code；
• buttons.css：.btn基础按钮，派生.primary（蓝底）、.warning（红底）、.success（绿底）、.transparent、.pressed、.disabled等状态变体；另有 buttons2.css 作为第二套按钮体系；
• inputs.css：input/textarea的圆角、边框、聚焦态与 checkbox/radio/range 的-webkit-appearance处理；
• tooltip.css：纯 CSS 的[data-tooltip]气泡提示，支持tooltip-top/right/left方向与tooltip-nodelay无延迟变体；
• markdown.css.js：.markdown作用域下的排版规则（标题字体、代码字号、引用块、链接色）；
• fontawesome.css 配合 webfonts/ 提供图标字体。

五、可复用 Web Components 组件

js/com/下是标准库的核心组件，全部基于 LitElement 实现并注册为自定义元素：

1. 上下文菜单 beaker-context-menu

app/userland/app-stdlib/js/com/context-menu.js 导出create(opts)API，传入坐标与菜单项即可弹出菜单，返回一个在菜单关闭时 resolve 的 Promise。其选项包括：

• x/y：菜单位置；right/center/top：对齐方式；
• withTriangle：带小三角箭头；roomy/veryRoomy：宽松间距；
• noBorders、rounded、style：外观定制；
• fontAwesomeCSSUrl：图标样式表地址（默认'/vendor/beaker-app-stdlib/css/fontawesome.css'）；
• items：菜单项数组，每项支持{icon, label, click}，'-'表示分隔线，href可渲染为链接，disabled渲染为禁用态，type: 'html'可插入自定义模板；
• 也可用render()完全接管菜单内容，并在内部通过this.destroy关闭。

菜单的关闭逻辑在全局处理：按Esc（keyCode 27）或点击菜单外部（通过findParent判断点击目标是否仍在BEAKER-CONTEXT-MENU内）都会触发destroy()。

2. Toast 通知 beaker-toast

app/userland/app-stdlib/js/com/toast.js 提供create(message, type, time, button)API：

import * as toast from 'beaker://app-stdlib/js/com/toast.js' toast.create('Saved!', 'success', 5000)

type支持success（绿色、✓前缀）、error（红色、!前缀）、primary（蓝色）；默认 5 秒后自动淡出销毁，也支持传入带label与click回调的操作按钮。销毁时先添加.hidden类做透明度过渡再移除节点。

3. 悬浮切换 beaker-hoverable

app/userland/app-stdlib/js/com/hoverable.js 通过两个具名插槽实现“鼠标悬停时替换内容”：

<beaker-hoverable> <button class="btn" slot="default">Hover me!</button> <button class="btn" slot="hover">I'm hovered!</button> </beaker-hoverable>

实现上对mouseleave过快丢失做了 50ms 后二次校验的兼容处理（源码注释标记为// HACK）。

4. 悬浮卡片 beaker-hover-card

app/userland/app-stdlib/js/com/hover-card.js 在悬停时于元素下方弹出浮层（slot="el"为触发元素，slot="card"为卡片内容），卡片样式由组件内css定义（绝对定位、居中、圆角边框）。

5. 图片回退 beaker-img-fallbacks

app/userland/app-stdlib/js/com/img-fallbacks.js 通过多个具名插槽实现“首图加载失败自动切换下一张”：

<beaker-img-fallbacks> <img src="/foo.png" slot="img1"> <img src="/bar.png" slot="img2"> </beaker-img-fallbacks>

当当前插槽图片触发error事件时递增currentImage渲染下一个插槽。

6. 弹窗基座 BasePopup

app/userland/app-stdlib/js/com/popups/base.js 是所有弹窗的抽象基类：构造时注册全局keyup监听以支持Esc关闭，提供shouldCloseOnEscape、shouldCloseOnOuterClick等可覆写的开关；coreCreate/create把弹窗挂到指定父元素并以resolve/reject自定义事件驱动 Promise 完成。基于它派生了 edit-bookmark.js（书签编辑）、edit-cover-photo.js（封面图编辑）、edit-thumb.js（缩略图编辑）三个业务弹窗。

六、工具函数库

js/根目录下是一批与 UI 无关的纯工具模块：

• dom.js：findParent（向上查找匹配祖先，支持类名简写）、on/once（事件绑定）、emit（派发可冒泡、可穿透 Shadow DOM 的CustomEvent）、changeFavicon（动态替换 favicon）；
• strings.js：DRIVE_KEY_REGEX（匹配 64 位十六进制 hyper drive key）、urlToKey、shorten、joinPath、shortenAllKeys（abcd..ef风格缩写）、toNiceDomain/toNiceUrl（自动缩短 key 型域名）、slugify/createResourceSlug、normalizeUrl、changeURLScheme、getDriveTypeIcon（按 drive 类型返回 Font Awesome 图标类）、hashFnv32a（32 位 FNV-1a 哈希，可输出 8 位十六进制字符串）等；
• time.js：shortDate（当年只显示月日、跨年补年份的Intl.DateTimeFormat封装）与timeDifference（"2 minutes ago" 风格相对时间，short参数可切换为2m缩写）；
• clipboard.js：writeToClipboard(str)，通过临时textarea+document.execCommand('copy')实现复制；
• emoji.js：render（追加\uFE0F变体选择符强制以 emoji 渲染）、setSkinTone（叠加肤色）、isSupported（在FULL_LIST中校验支持性）；
• functions.js：debouncer(ms, fallback)，可取消上一次任务的竞态防抖器，被取消的任务以fallback值 resolve，适用于搜索输入等场景；
• query-params.js：setParams(kv, clear, replaceState)与getParam(k, fallback)，基于URLSearchParams读写地址栏查询参数，replaceState控制使用replaceState还是pushState；
• is-ext-binary.js：内置数百个二进制扩展名清单，isFilenameBinary()据此判断文件是否应跳过文本读取；
• fs.js：面向 Hyperdrive 文件系统的高级封装，queryRead（查询并读取文本/JSON 内容）、queryHas、ensureDir/ensureParentDir、ensureMount/ensureUnmount/ensureUnmountByUrl（挂载点与 hyper drive 的联动管理）、getAvailableName（生成不冲突的文件名，如untitled-2.md）；
• const.js：HELP帮助文本集合（files / websites / groups / modules / frontends 五种 drive 类型的说明 HTML）。

七、emoji 数据与 Monaco 编辑器内核

• emoji 数据生成：data/emoji-list.js（约 1600 行）由 scripts/generate-emoji-list.js 从 scripts/emoji-data.txt（基于 Unicode 12.0 的emoji-test.txt快照）生成。脚本会跳过Component分组、剥离肤色修饰符，并显式过滤🔫、🔪、🖕、🗡️等禁用 emoji，最终导出SUGGESTED（常用推荐）、GROUPS（按组归档）与FULL_LIST（扁平全量列表）三个常量；
• Monaco 编辑器内核：js/vs/内嵌完整 VS Code 编辑器（editor.main.js+ 数十种语言basic-languages+css/html/json/typescript四种语言服务），使标准库具备托管代码编辑能力的底座，Beaker 的 editor 应用可在此基础上构建。

八、如何被默认应用消费：beaker://app-stdlib 协议

标准库在浏览器内通过专用协议beaker://app-stdlib对外提供服务。app/bg/protocols/beaker.js 中注册了该请求路由：凡是以beaker://app-stdlib开头的资源请求，都映射到userland/app-stdlib目录下的对应文件。

因此，任何 userland 应用都可以用协议路径直接引入标准库资源，例如 app/userland/cmd-pkg/css/main.css.js：

import {css} from 'beaker://app-stdlib/vendor/lit-element/lit-element.js' import buttonsCSS from 'beaker://app-stdlib/css/buttons2.css.js' import inputsCSS from 'beaker://app-stdlib/css/inputs.css.js' import tooltipCSS from 'beaker://app-stdlib/css/tooltip.css.js'

同样的引用方式还出现在：

• app/userland/editor/css/main.css：@import "beaker://app-stdlib/css/common.css";
• app/userland/editor/css/com/files-explorer.css.js：引入buttons2、spinner等组件样式；
• app/bg/protocols/hyper.js：P2P 页面注入beaker://app-stdlib/css/fontawesome.css提供图标；
• app/userland/cmd-pkg/drive-handler.css：@import "beaker://app-stdlib/css/common.css";

这也印证了 app/userland/README.md 的描述：userland 应用通常不做打包，直接以标准库作为共享层。需要特别说明的是，标准库尚在从“纯内部库”向可独立分发包迁移（edit-bookmark.js 源码注释明确标记了这一阶段，并指出书签“编辑”功能尚未完成）。

九、开发者实践小结

如果你是 Beaker 默认应用（editor、explorer、cmd-pkg、library 等）的开发者，使用标准库的标准姿势是：

1. 改样式：编辑css/下对应的.css源文件，运行node scripts/generate-css-js.js重新生成*.css.js，开发期间可改用node scripts/css-watcher.js自动构建；
2. 引样式：通过beaker://app-stdlib/css/xxx.css.js或@import "beaker://app-stdlib/css/xxx.css"引入；
3. 引组件与工具：importbeaker://app-stdlib/js/com/*.js或beaker://app-stdlib/js/*.js，组件以自定义元素形态（beaker-context-menu、beaker-toast、beaker-hoverable等）直接用于模板；
4. 遵循变量约定：颜色、边框、文本一律使用colors.css定义的语义变量，以自动获得暗色主题支持。

这套“标准库 + 协议路由 + 免构建复用”的架构，使得 Beaker 的全部内置应用在视觉与交互上保持一致，同时把重复逻辑收敛到单一维护点，是理解 Beaker 用户态应用生态的关键入口。

• 前端