把 IceWeasel 搬上鸿蒙 PC:冰鼬浏览器的鸿蒙PC移植实录
欢迎加入开源鸿蒙 PC 社区:https://harmonypc.csdn.net/
欢迎在 PC 社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
适配开源地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_IceWeasel
把一个桌面浏览器搬上鸿蒙 PC,最忌讳的是“看起来像”而不是“真的能跑”。这次的主角是 IceWeasel——一个基于 UXP 平台 4.6.0 的 Gecko 系浏览器,上游平台层足足 697 万行 C++,整体交叉编译在鸿蒙工具链上根本无法闭合。于是本工程选择了浏览器移植的行业惯例:内核用系统自带的 ArkWeb,外壳按上游源码的行为规格用 ArkTS 重建,一切可迁移的上游资产逐字入库。最终 ArkTS 只写了 2,034 行胶水,其余 85% 全是上游 verbatim 资产——5,867 行的 license.html、2,620 行的 aboutCredits.html,靠一个 chrome:// 映射器不改一字跑在真机上。书签历史落在 places.sqlite,会话存成 sessionstore.json,搜索引擎清单运行时解析上游 OpenSearch 插件,无痕标签遵守 PrivacyFilter 语义——归档资产即运行面资产,这是“移植”与“仿写”的分界线。本文完整记录这条移植路线的技术决策、关键代码与真机验收,踩过的坑也一并奉上。

一、先说结论:浏览器移植,不能硬编译
IceWeasel-UXP 不是普通桌面应用——它是 Gecko/Firefox 平台的完整 fork:UXP 平台层约 697 万行 C++/H,加上 XUL/JS/CSS 写的浏览器壳。接到这个移植需求时,我们的第一反应和其他所有移植工程一样:能不能整体交叉编译?

逐一核验后,结论是不可行,四条硬门槛条条致命:
- 构建系统起不来。Mozilla 全家使用 mach/bootstrap 构建体系(Python 2.7 + autoconf 2.13 + rust + 自研工具链),
configure阶段就依赖宿主 Python 环境与 GNU 工具链,在鸿蒙工具链上无法闭合。 - 没有 OpenHarmony 平台后端。Gecko 只支持 GTK/X11、Win32、Cocoa、Android 四个平台后端。要在鸿蒙上跑 Gecko,等于从零写
widget/ohos/全套——窗口、图形、Skia 后端、字体、输入、多进程 IPC、沙箱。这个量级相当于 Mozilla 当年做 Android 后端的全职团队数年工作量。 - XUL 自举依赖。浏览器 UI 本身就是 XUL 文档,需要 Gecko 渲染;Gecko 没起来,连界面都没有。
- 业界零先例。没有任何团队把 Gecko 移植到 OpenHarmony。Firefox for iOS 也不是交叉编译 Gecko,而是用系统 WebKit 重写外壳。
第 4 条其实给了答案:浏览器移植的行业惯例,就是"内核用系统自带的,外壳按上游行为规格重建"。
于是本工程的移植策略三句话定死:
- 网页引擎:由系统 ArkWeb(
@ohos.web.webview,Chromium 系内核)承担,随系统更新获得安全补丁; - 浏览器外壳:按上游源码(
browser.js/tabbrowser.xml/urlbarBindings.xml/ downloads 组件 / places 组件 / SessionFile.jsm / PrivacyFilter.jsm)的行为规格用 ArkTS 重建; - 上游资产:一切可 verbatim 迁移的 HTML/CSS/图标/搜索引擎/本地化文件逐字入库,不做改写。
最终代码占比很能说明问题:ArkTS 壳仅 2,034 行(15%),上游资产文本 11,856 行(85%)——ArkTS 只做 UI 壳与平台胶水。
二、迁移分层:T0 / T1 / T2
与 OpenHarmony PC 移植规范的三阶段对应,本工程把改动切成三层,每层有独立验收门:
| 阶段 | 目标 | 关键交付 |
|---|---|---|
| T0 UI 壳层 | ArkUI 重建浏览器全部交互 | 多标签 TabBar+Swiper、地址栏智能分发、导航控制、深色主题、右键菜单 |
| T1 引擎与数据层 | 引擎职责替换 + 数据层按上游存储语义映射 | ArkWeb 多实例、places.sqlite 语义、sessionstore.json、下载状态机、JS 桥、chrome:// 映射器 |
| T2 上游资产 | 可 verbatim 迁移的资产逐字入库 | about 页面族、license.html 整页真搬、10 个 OpenSearch 插件、主题 CSS 13 件、三语本地化 |
T1 有一条铁律:不自创表结构/文件格式。书签历史库文件就叫 places.sqlite,会话文件就叫 sessionstore.json,字段名照抄上游(moz_places / moz_bookmarks / version/selected/tabs)。这不是情怀,而是保证"懂 Firefox 内部结构的人打开数据文件一眼认得出",也为后续深适配保留保真底本。
三、工程结构
ohos_iceweasel/
├── AppScope/ # 应用级配置(bundleName com.iceweasel.ohos)
├── entry/
│ └── src/main/
│ ├── module.json5 # INTERNET 权限、deviceTypes 2in1/tablet
│ ├── ets/
│ │ ├── entryability/EntryAbility.ets # UIAbility + 深色模式 + 窗口初始化
│ │ ├── pages/Index.ets # 主界面:TabBar/Swiper/顶栏/JS 桥/面板挂载
│ │ ├── pages/SettingsPage.ets # 设置页
│ │ ├── components/SidePanel.ets # 书签/历史/下载三合一面板
│ │ ├── services/PlacesStore.ets # places.sqlite 语义(relationalStore)
│ │ ├── services/SessionStore.ets # sessionstore.json 语义(@ohos.file.fs)
│ │ ├── services/DownloadService.ets # 下载状态机(WebDownloadManager)
│ │ ├── services/PrefStore.ets # prefs.js 语义(preferences)
│ │ ├── services/AdBlockService.ets # 静态拦截规则表
│ │ ├── services/SearchPluginService.ets# 上游 searchplugins 运行时解析
│ │ ├── model/BrowserTab.ets # 标签模型
│ │ ├── model/SearchEngine.ets # 引擎模板与 URL 构造
│ │ ├── common/ChromeMapper.ets # chrome:// → rawfile 映射器
│ │ └── common/UrlUtils.ets # URL/搜索判定
│ └── resources/
│ ├── base|zh_CN|en_US/element/string.json # 三语文案(34 键)
│ └── rawfile/
│ ├── newtab.html # 新标签页(aboutHome 迁移版)
│ ├── aboutHome/ # 上游 abouthome 资产
│ ├── about/ # 适配页 + license.html(整页真搬)
│ └── upstream/ # 上游原件 verbatim(about 族/搜索插件/主题 CSS/本地化)
├── build-profile.json5 # SDK 6.0.1(21)
├── LICENSE # MPL-2.0
└── README.OpenHarmony_CN.md
模块配置很克制,浏览器联网只需要一个 normal 级权限:
// entry/src/main/module.json5(节选)
{
"module": {
"name": "entry",
"type": "entry",
"mainElement": "EntryAbility",
"deviceTypes": ["2in1", "tablet", "default"],
"requestPermissions": [
{
"name": "ohos.permission.INTERNET",
"reason": "$string:reason_internet",
"usedScene": { "abilities": ["EntryAbility"], "when": "always" }
}
]
}
}
四、关键实现拆解
4.1 标签模型:每个标签一个 WebviewController
多标签的核心是让每个标签持有独立的 WebviewController,Swiper 承载多 Web 实例,SwiperController.changeIndex() 与 TabBar 点击全状态同步——对应上游 tabbrowser.xml 的标签生命周期:
// model/BrowserTab.ets
import web_webview from '@ohos.web.webview';
export class BrowserTab {
id: number;
title: string;
url: string;
homeNonce: number; // 强制 ForEach 重建本地页的 nonce
localPage: string; // 本地页标识(aboutRobots/aboutNetError/...)
isPrivate: boolean;
canBack: boolean;
canForward: boolean;
isLoading: boolean;
crashUrl: string; // 渲染进程崩溃前的 URL,供恢复
controller: web_webview.WebviewController;
constructor(id: number, url: string) {
this.id = id;
this.url = url;
this.title = '';
this.homeNonce = 0;
this.localPage = '';
this.isPrivate = false;
this.canBack = false;
this.canForward = false;
this.isLoading = false;
this.crashUrl = '';
this.controller = new web_webview.WebviewController();
}
}
homeNonce 值得一提:本地页(新标签页、about 页)不是 loadUrl 加载的,而是 Web 组件的 src 直接给 $rawfile(...)。要让同一张本地页"重新加载",必须让 ForEach 的键变化触发组件重建——我们把键定义为 tab.id + ':' + tab.homeNonce,每次切本地页就 homeNonce + 1。
4.2 地址栏智能分发:URL 还是搜索词?
地址栏输入 baidu.com 要直达,输入"鸿蒙 pc"要搜索——判定逻辑对标上游 urlbarBindings.xml 的输入分类,用四条正则实现:
// common/UrlUtils.ets
const URL_SCHEME_RE: RegExp = new RegExp('^(https?|about|file)://', 'i');
const HOSTNAME_RE: RegExp = new RegExp('^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+(:\\d+)?(/.*)?$', 'i');
const HOSTPORT_RE: RegExp = new RegExp('^[a-z0-9][a-z0-9.-]*(:\\d+)(/.*)?$', 'i');
const TLD_RE: RegExp = new RegExp('\\.[a-z]{2,}$', 'i');
export class UrlUtils {
static isProbablyUrl(input: string): boolean {
const t: string = input.trim();
if (t.length === 0) return false;
if (URL_SCHEME_RE.test(t)) return true; // 显式协议,直接是 URL
if (t.indexOf(' ') >= 0 || t.indexOf(' ') >= 0) return false; // 带空格按搜索词
if (t.indexOf('.') < 0) return false; // 无点按搜索词
const pathStart: number = t.indexOf('/');
const host: string = pathStart >= 0 ? t.substring(0, pathStart) : t;
if (!HOSTNAME_RE.test(host) && !HOSTNAME_RE.test(t)) return false;
return TLD_RE.test(host) || TLD_RE.test(t) || HOSTPORT_RE.test(t);
}
static resolve(input: string, engine: SearchEngine | null): string {
const t: string = input.trim();
if (t.length === 0) return '';
if (UrlUtils.isProbablyUrl(t)) {
if (URL_SCHEME_RE.test(t)) return t;
return 'https://' + t; // 无协议补 https
}
if (engine !== null) return engine.buildSearchUrl(t);
return '';
}
}
判定为搜索词后,URL 由引擎模板构造。SearchEngine.buildSearchUrl 处理了 OpenSearch 的两种语法:{searchTerms} 占位符替换,以及 {xxx?} 可选参数的整段剔除(MozSearch 的 <Param> 子节点则拼接追加):
// model/SearchEngine.ets(节选)
buildSearchUrl(query: string): string {
const q: string = encodeURIComponent(query);
let url: string = this.template.split('{searchTerms}').join(q);
url = url.replace(new RegExp('[?&][A-Za-z0-9_]+=\\{[A-Za-z]+\\?\\}', 'g'), '');
url = url.replace(new RegExp('\\{[A-Za-z]+\\?\\}', 'g'), '');
for (let i = 0; i < this.params.length; i++) {
const v: string = encodeURIComponent(this.params[i].value.split('{searchTerms}').join(q));
url = url + (url.indexOf('?') >= 0 ? '&' : '?') + this.params[i].name + '=' + v;
}
return url;
}
4.3 搜索引擎清单:不硬编码,运行时解析上游 XML
上游的搜索引擎是 10 个 OpenSearch/MozSearch 格式的 XML 插件(searchplugins/*.xml),默认引擎与顺序写在 region.properties。我们没有把这 10 个引擎硬编码成 ArkTS 清单,而是启动时用 xml.XmlPullParser 运行时解析原件——上游文件更新时,替换 rawfile 即可,代码零改动:
// services/SearchPluginService.ets(核心解析段)
const PLUGIN_FILES: string[] = [
'gnusocial', 'hyperbola-packages', 'internet-archive', 'invidious', 'invidious-tor',
'searx', 'searx-tor', 'wikimedia-commons', 'wikipedia-en', 'yacy'
];
const REGION_FILE: string = 'upstream/locales/region.properties';
private static parsePlugin(ctx: common.UIAbilityContext, id: string): SearchEngine | null {
let ab: ArrayBuffer | null = null;
try {
const bytes: Uint8Array = ctx.resourceManager.getRawFileContentSync('upstream/searchplugins/' + id + '.xml');
ab = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
} catch (e) {
return null;
}
if (ab === null) return null;
let shortName: string = '';
const triples: XmlTriple[] = [];
const parser: xml.XmlPullParser = new xml.XmlPullParser(ab, 'utf-8');
parser.parseXml({
ignoreNameSpace: true,
tagValueCallbackFunction: (name: string, value: string): boolean => {
if (SearchPluginService.stripNs(name) === 'ShortName') {
shortName = value.trim();
}
return true;
},
attributeWithTagCallbackFunction: (tagName: string, key: string, value: string): boolean => {
triples.push({ tagName: SearchPluginService.stripNs(tagName), key: key, value: value });
return true;
}
});
// ... 以 <Url type=...> 开新上下文、<Param name=...> 状态机收集参数(略)
// 只挑第一个 GET 型 text/html 的 <Url> 模板
return new SearchEngine(id, shortName, chosen.template, chosen.params);
}
这里有个 ArkTS 特有的坑(后面 QA 详述):<Url> 的属性回调顺序依赖"属性回调参数以当前 tag 开新上下文",连续 <Param> 必须靠 name 属性开新上下文,否则后项覆盖前项。另外挑模板的纯函数 pickUrl 故意不写在闭包里——ArkTS 控制流分析会把"仅闭包赋值"的变量收窄为 never,编译直接报错。
10 个引擎里 8 个 GET 型 text/html 可用;POST 型 SearX / SearX (Tor) 因地址栏导航无 POST 语义而排除,属忠实降级。默认引擎与顺序解析自 region.properties 的 browser.search.defaultenginename / browser.search.order.1-3 键。
4.4 数据层:places.sqlite 与 sessionstore 的语义映射
书签/历史用 relationalStore 实现,库名就叫 places.sqlite,表名就叫 moz_places / moz_bookmarks,浏览记录上报为同 URL visit_count+1 的 upsert:
// services/PlacesStore.ets(核心段)
const DB_NAME: string = 'places.sqlite';
const SQL_HISTORY: string = 'CREATE TABLE IF NOT EXISTS moz_places ('
+ 'id INTEGER PRIMARY KEY AUTOINCREMENT, url TEXT UNIQUE, title TEXT, '
+ 'visit_count INTEGER DEFAULT 1, last_visit_date INTEGER)';
// 对标 moz_places upsert:同 URL 计数 +1 并刷新 last_visit_date,否则新行
recordVisit(url: string, title: string): void {
if (this.store === null || url.length === 0) return;
const now: number = Date.now();
const sel = new relationalStore.RdbPredicates('moz_places');
sel.equalTo('url', url);
this.store.query(sel).then((rs: relationalStore.ResultSet) => {
const exists: boolean = rs.goToNextRow();
const id: number = exists ? rs.getLong(rs.getColumnIndex('id')) : 0;
const cnt: number = exists ? rs.getLong(rs.getColumnIndex('visit_count')) : 0;
rs.close();
if (exists) {
const upd: relationalStore.ValuesBucket = {
'title': title, 'visit_count': cnt + 1, 'last_visit_date': now
};
const p = new relationalStore.RdbPredicates('moz_places');
p.equalTo('id', id);
return this.store!.update(upd, p);
}
const ins: relationalStore.ValuesBucket = {
'url': url, 'title': title, 'visit_count': 1, 'last_visit_date': now
};
return this.store!.insert('moz_places', ins);
}).catch(() => {});
}
会话存储对齐上游 SessionFile.jsm 的格式契约 {version, selected, tabs[{url,title}]},落 filesDir/sessionstore.json;无痕标签不落会话与历史,对标上游 PrivacyFilter.jsm 的语义:
// pages/Index.ets —— persistSession:无痕标签不落会话
private persistSession(): void {
const kept: BrowserTab[] = [];
for (let i = 0; i < this.tabs.length; i++) {
if (!this.tabs[i].isPrivate) {
kept.push(this.tabs[i]);
}
}
this.sessions.save(this.ctx(), kept, this.currentIndex);
}
4.5 chrome:// 映射器:让上游原件"不改一字"跑起来
这是本工程最精巧的一块。上游归档的 aboutCredits.html(2,620 行纯 HTML)里引用的是 chrome://global/skin/about.css 这类 Gecko 专属协议地址。我们做了一个映射器,对标 Gecko 的 nsChromeProtocolHandler,在 onInterceptRequest 里把这些请求拦截并回填包内 verbatim 资产:
// common/ChromeMapper.ets
const CHROME_MAP: ChromeMapEntry[] = [
{ chromeUrl: 'chrome://global/skin/about.css', rawfilePath: 'upstream/themes/about.css' },
{ chromeUrl: 'chrome://global/skin/netError.css', rawfilePath: 'upstream/themes/aboutNetError.css' },
{ chromeUrl: 'chrome://global/skin/in-content/info-pages.css', rawfilePath: 'upstream/themes/info-pages.css' },
{ chromeUrl: 'chrome://global/skin/in-content/common.css', rawfilePath: 'upstream/themes/common.css' },
{ chromeUrl: 'chrome://browser/skin/error-pages.css', rawfilePath: 'upstream/themes/error-pages.css' },
{ chromeUrl: 'chrome://browser/skin/tab-crashed.svg', rawfilePath: 'upstream/themes/tab-crashed.svg' },
{ chromeUrl: 'chrome://browser/content/aboutRobots-icon.png', rawfilePath: 'upstream/about/aboutRobots-icon.png' },
// ... 共 13 条映射
];
static respond(ctx: common.UIAbilityContext, rawfilePath: string): WebResourceResponse {
const resp: WebResourceResponse = new WebResourceResponse();
try {
const data: Uint8Array = ctx.resourceManager.getRawFileContentSync(rawfilePath);
const body: ArrayBuffer = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
resp.setResponseData(body);
resp.setResponseMimeType(ChromeMapper.mime(rawfilePath));
resp.setResponseEncoding('utf-8');
resp.setResponseCode(200);
resp.setReasonMessage('OK');
} catch (e) {
resp.setResponseData('');
resp.setResponseMimeType('text/plain');
resp.setResponseCode(404);
resp.setReasonMessage('Not Found');
}
return resp;
}
由此,aboutCredits.html 无需修改一个字节即可运行,它引到的 aboutNetError.css → error-pages.css → info-pages.css → common.css 完整 CSS 依赖链与 SVG 图标全部 verbatim 接通。
4.6 JS 桥:新标签页的五个入口按钮
内置新标签页 newtab.html 的功能入口(下载/书签/历史/设置/恢复上次会话)调用 window.ohos.launch(id)。ArkTS 侧必须用 javaScriptProxy 注册同名代理对象,且每个 Web 实例都要单独注册(多标签各自持 controller):
// pages/Index.ets —— Web 组件上的注册(在 ForEach 内,每个标签一份)
.javaScriptProxy({
object: this.jsBridge, // { launch: (id: string) => void }
name: 'ohos',
methodList: ['launch'],
controller: tab.controller
})
launch(id) 的分发逻辑覆盖面板打开、设置页、会话恢复,以及崩溃恢复页的 restoreTab/restoreAll/closeTab。注意桥对象字面量必须对应显式 interface(arkts-no-untyped-obj-literals 硬规则):
interface JsBridge {
launch: (id: string) => void;
}
private jsBridge: JsBridge = {
launch: (id: string): void => {
if (id === 'downloads') {
this.openPanel(2);
} else if (id === 'bookmarks') {
this.openPanel(0);
} else if (id === 'history') {
this.openPanel(1);
} else if (id === 'settings') {
this.settingsVisible = true;
} else if (id === 'restorePreviousSession') {
this.restoreSession();
} else if (id === 'restoreTab') {
this.restoreCrashedTab(this.currentTab());
}
// ...
}
};
4.7 错误页与崩溃页接管
网络错误时主帧接管为本地 aboutNetError 迁移页;渲染进程异常退出(onRenderExited)时保存原 URL 并切到 aboutTabCrashed 页,用户点"恢复"按钮经 JS 桥找回:
// pages/Index.ets(节选)
.onErrorReceive((event?) => {
if (event) {
try {
if (event.request.isMainFrame() && tab.localPage.length === 0) {
tab.localPage = 'aboutNetError';
tab.homeNonce = tab.homeNonce + 1;
this.tabs = this.tabs.slice();
}
} catch (e) {}
}
})
.onRenderExited((event?) => {
// 对标上游 about:tabcrashed:渲染进程异常退出时接管为本地崩溃页
try {
if (tab.localPage !== 'aboutTabCrashed') {
if (tab.url.length > 0) {
tab.crashUrl = tab.url;
}
tab.url = LOCAL_HOME;
tab.localPage = 'aboutTabCrashed';
tab.homeNonce = tab.homeNonce + 1;
this.tabs = this.tabs.slice();
}
} catch (e) {}
})
广告拦截复用同一个 onInterceptRequest 通道:命中静态域名规则表(google-analytics/doubleclick 等)返回无参构造的空 WebResourceResponse(),否则 return undefined 放行。
五、代码章:六段最值得抄走的代码
前面按功能模块讲了设计,这一章把最容易被 SDK 文档误导、最值得直接抄走的六段代码集中列出,每段都来自真实构建通过的工程。
5.1 Web 组件的完整事件面
一个浏览器级 Web 实例的事件面长这样(这是 Index.ets 里 ForEach 内的完整 Web 配置,含全部回调与拦截):
Web({ src: this.webSrc(tab), controller: tab.controller })
.width('100%')
.height('100%')
.javaScriptAccess(true)
.zoomAccess(true)
.onPageBegin(() => {
tab.isLoading = true;
})
.onPageEnd(() => {
tab.isLoading = false;
try {
tab.url = this.displayUrl(tab.controller.getUrl());
tab.title = tab.controller.getTitle();
} catch (e) {}
if (tab.url.length > 0 && !tab.isPrivate) {
this.places.recordVisit(tab.url, tab.title); // 历史上报
}
this.persistSession(); // 会话持久化
})
.onDownloadStart((event?) => {
if (event) {
this.downloadSvc.onWebDownloadStart(event.url); // 下载登记
}
})
.onInterceptRequest((event?) => {
if (event) {
try {
const reqUrl: string = event.request.getRequestUrl();
const chromePath: string = ChromeMapper.map(reqUrl);
if (chromePath.length > 0) {
return ChromeMapper.respond(this.ctx(), chromePath); // chrome:// 接管
}
if (this.adblockOn() && AdBlockService.isBlocked(reqUrl)) {
return new WebResourceResponse(); // 空响应 = 拦截
}
} catch (e) {}
}
return undefined; // undefined = 放行
})
.onContextMenuShow((event?) => {
this.menuVisible = true;
return true; // true = 拦截默认菜单
})
.javaScriptProxy({
object: this.jsBridge,
name: 'ohos',
methodList: ['launch'],
controller: tab.controller
})
三个容易踩的细节:
onInterceptRequest返回undefined才是放行,返回空参WebResourceResponse()是"给一个空 body"(即拦截);onErrorReceive里必须先判event.request.isMainFrame(),否则子资源加载失败也会触发错误页接管;onPageEnd里才拿得到最终 URL 与标题(onPageBegin时getUrl()可能还是上一页)。
5.2 导航 API 用的是"API 8 旧名"
WebviewController 的导航方法在该 SDK 上是 backward() / forward() / accessBackward() / accessForward() / stop() / refresh()——浏览器开发者习惯的 goBack()/goForward()/accessBack() 均不存在,编译器只会冷冷提示 Did you mean 'forward'?:
this.NavButton('‹', this.canGoBack, () => {
try {
this.currentTab().controller.backward(); // 不是 goBack()
} catch (e) {}
});
this.NavButton('›', this.canGoForward, () => {
try {
this.currentTab().controller.forward(); // 不是 goForward()
} catch (e) {}
});
可 backButton/backForward 一类的状态查询同样用 accessBackward()/accessForward()。这组旧名在官方文档里藏得很深,建议直接记住。
5.3 页内查找:runJavaScript + JSON.stringify 防注入
页内查找没有原生 API,用 runJavaScript 注入 window.find。查询词必须过 JSON.stringify——否则输入 ");alert(1);// 就是现成的注入点:
private runFind(): void {
const t: BrowserTab = this.currentTab();
if (!t || this.findInput.length === 0) return;
try {
t.controller.runJavaScript('window.find(' + JSON.stringify(this.findInput) + ');');
} catch (e) {}
}
5.4 下载状态机:WebDownloadManager 四回调
下载对接 WebDownloadManager.setDownloadDelegate,四个回调维护状态机(进行中/完成/失败,对标 nsIDownloadManager 的 STATE_*);Web 侧 onDownloadStart 事件负责登记新项:
// services/DownloadService.ets(核心段)
init(): void {
if (this.inited) return;
this.inited = true;
try {
const delegate: web_webview.WebDownloadDelegate = new web_webview.WebDownloadDelegate();
delegate.onBeforeDownload((item?) => { this.setState(item, DL_STATE_IN_PROGRESS); });
delegate.onDownloadUpdated((item?) => { this.setState(item, DL_STATE_IN_PROGRESS); });
delegate.onDownloadFinish((item?) => { this.setState(item, DL_STATE_COMPLETED); });
delegate.onDownloadFailed((item?) => { this.setState(item, DL_STATE_FAILED); });
web_webview.WebDownloadManager.setDownloadDelegate(delegate);
} catch (e) {}
}
5.5 会话恢复:启动即还原 + 手动再恢复
启动时 aboutToAppear 自动恢复上次会话;新标签页上"恢复上次会话"按钮可手动再恢复。文件读取用 fs.openSync → readSync → closeSync,解码用 TextDecoder:
// services/SessionStore.ets(核心段)
restore(context: common.UIAbilityContext): SessionData | null {
try {
const path: string = this.filePath(context);
if (!fs.accessSync(path)) return null;
const fd: fs.File = fs.openSync(path, fs.OpenMode.READ_ONLY);
const stat = fs.statSync(path);
const buf: ArrayBuffer = new ArrayBuffer(stat.size);
fs.readSync(fd.fd, buf);
fs.closeSync(fd);
const decoder: util.TextDecoder = util.TextDecoder.create('utf-8');
const json: string = decoder.decodeToString(new Uint8Array(buf));
const parsed: SessionData = JSON.parse(json) as SessionData;
if (parsed.version !== FORMAT_VERSION) return null;
return parsed;
} catch (e) {
return null;
}
}
5.6 窗口初始化:深色模式 + 物理像素换算
PC 应用窗口初始化有个容易忽略的坑:win.resize 收的是物理像素(px),而设计稿通常是 vp,要乘 display.densityPixels:
// entryability/EntryAbility.ets(核心段)
onWindowStageCreate(windowStage: window.WindowStage): void {
windowStage.loadContent('pages/Index', (err) => {
if (err.code) return;
try {
const win = windowStage.getMainWindowSync();
win.setWindowBackgroundColor('#1E1E28');
const d = display.getDefaultDisplaySync();
let density = d.densityPixels;
if (density <= 0) density = 1;
win.resize(Math.round(1280 * density), Math.round(800 * density)).catch(() => {});
} catch (e) {}
});
}
setColorMode(COLOR_MODE_DARK) 放在 onCreate 里并 try-catch 包裹——它失败不该拖垮应用启动。
六、构建与真机验收
6.1 构建
hvigorw assembleHap
或 DevEco Studio 打开仓库根目录直接构建 entry 模块。产物:entry/build/default/outputs/default/entry-default-signed.hap(需配置签名)。
6.2 真机安装与启动
hdc install -r entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.iceweasel.ohos -m entry
6.3 验收实拍
启动后桌面出现「冰鼬(From IceWeasel)」窗口,新标签页是上游 aboutHome 的暗色迁移版:冰鼬 logo、中央搜索框、底部五个入口(下载/书签/历史/设置/恢复上次会话),"会话已在启动时自动恢复"的提示条说明 sessionstore.json 链路工作正常。

地址栏输入 about:robots,走 about 协议分发到本地迁移页——“Welcome Humans!” 的文案与机器人图标正是上游 aboutRobots 的原文原图标(DTD 实体展开为上游字面文案,样式与图标 verbatim):

地址栏输入搜索词"鸿蒙 pc",智能分发到搜索引擎(截图里是 Bing,引擎清单可随时切换),多标签、标签关闭、新建标签全部正常:

点工具栏历史按钮,侧边面板打开。历史列表里每条记录正是 moz_places 表的 title/url 字段——包括刚才 Bing 搜索的 URL(search?q=%E9%B8%BF%E8%92%99pc):

右键菜单 →「许可信息」直达 about:license——这是上游 base/content/license.html(5,867 行)逐字迁入的整页,MPL-2.0 与各组件许可清单一字未改:

6.4 功能状态清单
| 功能 | 状态 | 说明 |
|---|---|---|
| 多标签(增/切/关) | ✅ | 自绘 TabBar + Swiper |
| 导航(后退/前进/刷新/停止/主页) | ✅ | API 8 旧名集合 |
| 地址栏 URL/搜索智能分发 | ✅ | 8 个 GET 型引擎运行时解析 |
| 新标签页(aboutHome 迁移版) | ✅ | launcher 五入口经 JS 桥 |
| 恢复上次会话 | ✅ | sessionstore.json |
| 历史上报与历史面板 | ✅ | places.sqlite(moz_places) |
| 书签面板(增/删/打开) | ✅ | places.sqlite(moz_bookmarks) |
| 下载面板 | ✅ | WebDownloadManager 状态机 |
| 设置页 | ✅ | 引擎/远程调试/拦截/清除数据 |
| 错误页接管 | ✅ | 主帧错误 → 本地 aboutNetError |
| 许可页 | ✅ | 上游 license.html 整页 |
| about 页族 | ✅ | DTD 展开适配层 + credits verbatim 直载 |
| chrome:// 资源映射 | ✅ | ChromeMapper 13 条映射 |
| 渲染进程崩溃接管 | ✅ | onRenderExited → aboutTabCrashed |
| 广告拦截 | ✅(静态规则) | onInterceptRequest + isMainFrame |
| 页内查找 | ✅ | runJavaScript 注入 |
| 无痕标签 | ⚠️ 降级 | PrivacyFilter 语义;内核 privacyMode 缺失 |
| 清除浏览数据 | ⚠️ 降级 | 不含 Cookie(WebCookieManager 无删除 API) |
| XUL 扩展体系 | ❌ 不可保留 | 以 JS 注入 + 请求拦截近似 |
七、QA 章:十个高频问题
以下 Q/A 全部来自本工程的真实构建日志与真机验证,供后续鸿蒙 PC 移植工程直接规避。
Q1:为什么不用 Gecko 内核本身?别的内容浏览器都这么移植吗?
A:见第一节四条硬门槛。浏览器移植的行业惯例是"内核用系统自带的,外壳按上游行为规格重建"——Firefox for iOS 用 WebKit,Edge 曾用 Blink。鸿蒙上系统自带 ArkWeb(Chromium 系),安全补丁随系统更新,比背一个 697 万行的 Gecko fork 靠谱得多。
Q2:编译报 arkts-no-untyped-obj-literals,对象字面量哪里不合法?
A:ArkTS 禁止"裸"对象字面量,必须对应显式 interface/class。JS 桥对象、事件参数、配置项均如此。例如桥对象先声明 interface JsBridge { launch: (id: string) => void },再 private jsBridge: JsBridge = { launch: ... }。
Q3:window.ohos.launch() 在网页里点了没反应,也没有编译错误?
A:JS 桥未注册或未对该 Web 实例注册。javaScriptProxy 是 Web 组件级的——多标签场景每个标签各持一个 controller,javaScriptProxy 必须写在 ForEach 内的每个 Web 上。未注册时 window.ohos 为 undefined,点击静默失败,编译期无任何信号。排查方法:在网页控制台看 typeof window.ohos。
Q4:goBack() 方法不存在?
A:该 SDK 的 WebviewController 用 API 8 旧名集合:backward()/forward()/accessBackward()/accessForward()/stop()/refresh()。goBack/goForward/accessBack 均不存在。
Q5:import { WebResourceResponse } from '@ohos.web.webview' 编译报错?
A:WebResourceResponse 是全局环境类,由 component/web.d.ts 的 declare class 提供,不从 @ohos.web.webview 导出。直接 new WebResourceResponse() 用全局名即可。另外 setResponseData 收 ArrayBuffer——getRawFileContentSync 返回的 Uint8Array 须先 data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) 取拷贝再传入。
Q6:UI 正常但所有点击都没反应?
A:大概率是恒挂载的透明覆盖层吃掉了全部 hit-test。面板/设置页/弹层必须 if (visible) 条件渲染——恒挂载的 100%×100% 透明根容器构建全绿但拦截一切点击(连 Web 右键都收不到)。本工程右键菜单、侧面板、设置页全部走条件渲染。
Q7:aboutToAppear 里初始化一堆服务,挂一个全崩?
A:aboutToAppear 内每个初始化必须独立 try-catch。getContext(this) 等调用一旦抛异常会中断组件初始化、事件系统不绑定——表现为 UI 正常渲染但交互全死。本工程 aboutToAppear 里 prefs/下载/搜索引擎/会话/places 五路初始化各自 try-catch,互不拖累。
Q8:Text.onClick 有时点击完全无反应?
A:真机上验证过 Text.onClick 存在不可靠的情况。可点击控件优先用 Button——本工程导航按钮、标签关闭钮、菜单项容器点击均用 Button 或 Row 容器兜底。
Q9:XmlPullParser 解析 XML,属性总是串位/被覆盖?
A:attributeWithTagCallbackFunction 的参数是 (tagName, key, value),且属性回调不会自动告诉你属于哪个开始标签上下文。做法是把所有属性先收集成 {tagName, key, value} 三元组列表,事后再跑一个小状态机:<Url type=...> 开新 UrlContext、<Param name=...> 开新参数上下文——连续 <Param> 必须靠 name 属性开新上下文,否则后项覆盖前项。另外 ignoreNameSpace: true 消除 os: 等命名空间前缀;构造器吃 ArrayBuffer,Uint8Array 同 Q5 转拷贝。
Q10:还有哪些"静态语言化"的坑?
A:三个最常见的:
arkts-no-standalone-this:独立函数与 static 方法内均禁this,须类名调用;arkts-no-func-apply-call:Function.apply/call被禁,字节流转文本用util.TextDecoder.create('utf-8').decodeToString(...);arkts-no-any-unknown:禁止any/unknown,SDK 声明里的any字段须在调用点显式收窄。
另有一条编译器行为:仅闭包赋值的局部变量会被控制流分析收窄为never(5.1 节pickUrl纯函数化的原因)。
八、总结
把一个 697 万行的 Gecko fork 搬上鸿蒙 PC,靠的不是编译器奇迹,而是三条务实决策:
- 内核换系统 ArkWeb,把"维护一个浏览器引擎"的负担还给操作系统;
- 外壳按上游行为规格用 ArkTS 重建,只写 2,034 行平台胶水;
- 上游资产 verbatim 入库 + chrome:// 映射器接管引用,让 5,867 行的 license.html、2,620 行的 aboutCredits.html 不改一字运行。
数据层严格对齐上游存储语义(places.sqlite / sessionstore.json),搜索引擎清单运行时解析上游 OpenSearch 插件——归档资产即运行面资产,这是"移植"而不是"仿写"的分界线。
遗留的降级项也很清楚:无痕标签缺内核级 Cookie 隔离(Web.privacyMode 不存在),清除数据不含 Cookie(WebCookieManager 无删除 API),XUL 扩展体系不可保留。这些是平台能力边界,等待系统 ArkWeb 演进补齐。
工程已开源(MPL-2.0),仓库含完整 README.OpenHarmony_CN.md 移植论述,欢迎鸿蒙 PC 移植同行取用踩坑经验。
更多推荐



所有评论(0)