欢迎加入开源鸿蒙 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 语义——归档资产即运行面资产,这是“移植”与“仿写”的分界线。本文完整记录这条移植路线的技术决策、关键代码与真机验收,踩过的坑也一并奉上。

冰鼬浏览器在鸿蒙 PC 上的启动画面:aboutHome 迁移版新标签页

一、先说结论:浏览器移植,不能硬编译

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

在这里插入图片描述

逐一核验后,结论是不可行,四条硬门槛条条致命:

  1. 构建系统起不来。Mozilla 全家使用 mach/bootstrap 构建体系(Python 2.7 + autoconf 2.13 + rust + 自研工具链),configure 阶段就依赖宿主 Python 环境与 GNU 工具链,在鸿蒙工具链上无法闭合。
  2. 没有 OpenHarmony 平台后端。Gecko 只支持 GTK/X11、Win32、Cocoa、Android 四个平台后端。要在鸿蒙上跑 Gecko,等于从零写 widget/ohos/ 全套——窗口、图形、Skia 后端、字体、输入、多进程 IPC、沙箱。这个量级相当于 Mozilla 当年做 Android 后端的全职团队数年工作量。
  3. XUL 自举依赖。浏览器 UI 本身就是 XUL 文档,需要 Gecko 渲染;Gecko 没起来,连界面都没有。
  4. 业界零先例。没有任何团队把 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):

about:robots 页面:上游文案与图标 verbatim 保留

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

地址栏搜索分发到 Bing,多标签并存

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

历史面板:数据来自 places.sqlite 的 moz_places 表

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

about:license:上游 license.html 整页真搬

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,靠的不是编译器奇迹,而是三条务实决策:

  1. 内核换系统 ArkWeb,把"维护一个浏览器引擎"的负担还给操作系统;
  2. 外壳按上游行为规格用 ArkTS 重建,只写 2,034 行平台胶水;
  3. 上游资产 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 移植同行取用踩坑经验。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐