HarmonyOS浏览器应用功能需求规格说明

目录

1. 管理面板功能
2. 网址管理
3. 隐私网址功能
4. 用户代理(User Agent)设置
5. 服务器代理配置
6. 收藏夹管理
7. 主题模式切换
8. 沉浸模式设置

1. 管理面板功能

1.1 功能概述

管理面板是用户访问和控制浏览器所有设置的中心界面，提供统一的配置入口，确保良好的用户体验。

1.2 基础需求

• 面板布局: 清晰分类的设置项，包含常用设置和高级设置
• 即时生效: 设置更改后立即应用，无需重启
• 状态记忆: 保存用户的设置选择并在下次启动时应用
• 动画过渡: 面板打开/关闭时提供平滑动画

1.3 交互逻辑

graph TD
    A[用户点击设置按钮] --> B[打开设置面板]
    B --> C[显示当前设置状态]
    C --> D[用户更改设置]
    D --> E[实时应用更改]
    E --> F[保存设置]
    F --> G[关闭面板]

1.4 详细技术规格

操作	动作	效果
打开面板	点击设置图标	滑入动画，状态栏保持可见
关闭面板	点击返回按钮/面板外区域	滑出动画，恢复原有界面状态
应用设置	切换开关/输入数据	实时保存并应用

1.5 HarmonyOS API参考

• 首选项存储:
  dataPreferences

  API	说明	参数	返回值
  getPreferences(context, name)	获取首选项实例	context: 上下文对象 name: 首选项名称	Promise\<Preferences>
  put(key, value)	存储键值对	key: 键名 value: 值	Promise\<void>
  get(key, defValue)	获取值	key: 键名 defValue: 默认值	Promise\<ValueType>
  flush()	将缓存中的数据写入文件	无	Promise\<void>

• 动画效果:
  animatorProperty

  API	说明	参数	返回值
  animation.createAnimator()	创建动画实例	无	AnimatorResult
  animation.animate(value)	执行动画	value: 动画配置	void
  transition(value)	定义过渡动画	value: 过渡配置	void

// 面板实现参考
@Component
struct SettingsPanel {
  @Link settings: SettingsObject;  
  // 面板内容
}

2. 网址管理

2.1 功能概述

提供网址输入、访问和管理功能，支持历史记录和智能提示，是浏览器的核心功能之一。

2.2 基础需求

• 网址输入: 支持直接输入URL或搜索词
• 默认网址: 提供默认主页设置
• URL格式化: 自动补全https://等前缀
• 历史记录: 记住访问过的网址
• 域名提示: 输入时提供匹配建议

2.3 交互逻辑

场景	行为
输入网址	提供自动补全和建议
无协议头	自动添加https://
输入搜索词	识别非URL格式，使用默认搜索引擎
地址变更	自动更新地址栏显示

2.4 详细技术规格

网址格式规范

• 有效URL: 自动加载
• 无协议头: 添加https://前缀
• 无效URL: 使用搜索引擎处理
• 特殊网址: 支持about:协议和本地文件

2.5 HarmonyOS API参考

• WebView控制:
  webview

  API	说明	参数	返回值
  WebviewController.loadUrl()	加载指定URL	url: 网址字符串	void
  WebviewController.loadData()	加载HTML内容	data: HTML内容 mimeType: MIME类型 encoding: 编码方式	void
  Web.onPageBegin()	页面开始加载回调	callback: 回调函数	void
  Web.onPageEnd()	页面加载完成回调	callback: 回调函数	void
  Web.onErrorReceive()	页面加载错误回调	callback: 回调函数	void

• URI处理:
  uri

  API	说明	参数	返回值
  URI.parse(uri)	解析URI字符串	uri: URI字符串	URI对象
  URI.toString()	转换为字符串	无	string
  URI.getScheme()	获取协议	无	string
  URI.getHost()	获取主机名	无	string
  URI.getPath()	获取路径	无	string

// 加载URL
loadUrl(url: string): void {
  // URL格式化处理
  const formattedUrl = this.formatUrl(url);
  this.controller.loadUrl(formattedUrl);
}

3. 隐私网址功能

3.1 功能概述

隐私网址功能允许用户快速访问预设的私密网址，不留下历史记录，为用户提供额外的隐私保护。

3.2 基础需求

• 单键访问: 通过专用按钮快速访问隐私网址
• 自定义设置: 允许用户自定义隐私网址
• 无痕访问: 不记录在常规历史记录中
• 临时存储: 仅在内存中保存会话数据

3.3 交互逻辑

graph TD
    A[用户点击隐私网址按钮] --> B{是否已设置隐私网址?}
    B -->|是| C[加载隐私网址]
    B -->|否| D[提示用户设置]
    D --> E[打开设置面板]
    C --> F[标记为隐私模式浏览]
    F --> G[会话结束时清除数据]

3.4 详细技术规格

数据类型	常规浏览	隐私网址浏览
历史记录	保存	不保存
Cookie	持久保存	仅会话有效
缓存数据	保存	会话结束清除

3.5 HarmonyOS API参考

• 文件存储:
  fileio

  API	说明	参数	返回值
  fileio.open(path, mode)	打开文件	path: 文件路径 mode: 打开模式	Promise\<number>
  fileio.readText(fd)	读取文本内容	fd: 文件描述符	Promise\<string>
  fileio.writeText(fd, text)	写入文本内容	fd: 文件描述符 text: 文本内容	Promise\<void>
  fileio.close(fd)	关闭文件	fd: 文件描述符	Promise\<void>
  fileio.rmdir(path)	删除目录	path: 目录路径	Promise\<void>

• WebView配置:
  WebviewController

  API	说明	参数	返回值
  WebviewController.clearCache()	清除缓存	无	void
  WebviewController.clearSiteData()	清除站点数据	无	void
  Web.domStorageAccess()	设置DOM存储访问权限	allow: 布尔值	Web组件链式调用
  Web.fileAccess()	设置文件访问权限	allow: 布尔值	Web组件链式调用

// 隐私浏览实现
async visitPrivacyUrl(): Promise<void> {
  const privacyUrl = await this.settingsManager.getPrivacyUrl(context);
  // 设置临时标记
  TempStorage.SetOrCreate('isPrivacyVisit', true);
  this.loadUrl(privacyUrl);
}

4. 用户代理(User Agent)设置

4.1 功能概述

允许用户自定义浏览器的User Agent字符串，以适应不同网站的兼容性需求或模拟特定设备访问。

4.2 基础需求

• 默认UA: 提供基于设备信息的默认UA
• 自定义配置: 允许用户完全自定义UA字符串
• 快速切换: 支持预设UA配置的快速切换
• 网站特定: 支持针对特定网站使用不同UA

4.3 交互逻辑

设置项	作用
默认UA	使用系统生成的标准UA
移动设备UA	模拟手机浏览器
桌面UA	模拟桌面浏览器
自定义UA	用户输入的完全自定义字符串

4.4 详细技术规格

UA字符串构成

常用预设

设备类型	UA示例
默认	系统自动生成
桌面	Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.45 Safari/537.36
移动设备	Mozilla/5.0 (Linux; Android 12) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.45 Mobile Safari/537.36

4.5 HarmonyOS API参考

• 用户代理设置:
  userAgent

  API	说明	参数	返回值
  WebviewController.userAgent	设置User-Agent	string: UA字符串	void
  Web.userAgent()	设置Web组件的UA	string: UA字符串	Web组件链式调用

• 设备信息:
  deviceInfo

  API	说明	参数	返回值
  deviceInfo.getDeviceType()	获取设备类型	无	DeviceType
  deviceInfo.getManufacture()	获取制造商	无	string
  deviceInfo.getMarketName()	获取产品名	无	string
  deviceInfo.getProductModel()	获取产品型号	无	string
  deviceInfo.getDeviceInfo()	获取完整设备信息	无	DeviceInfo

// 设置用户代理
setUserAgent(userAgent: string): void {
  if (this.controller) {
    this.controller.userAgent = userAgent;
  }
}

5. 服务器代理配置

5.1 功能概述

允许用户配置HTTP代理服务器，为网络请求提供中转，适用于特定网络环境或访问限制内容的场景。

5.2 基础需求

• 代理开关: 允许快速启用/禁用代理
• 代理配置: 支持设置代理服务器地址和端口
• 排除列表: 配置不使用代理的域名
• 身份验证: 支持需要用户名密码的代理(可选)

5.3 交互逻辑

graph TD
    A[用户启用代理] --> B[输入代理配置]
    B --> C[应用代理设置]
    C --> D[WebView应用代理]
    C --> E[系统连接验证]
    E -->|成功| F[显示成功状态]
    E -->|失败| G[显示错误提示]

5.4 详细技术规格

设置项	说明	默认值
启用代理	开关代理功能	关闭
服务器地址	代理服务器主机名/IP	空
端口	代理服务器端口	8080
例外网址	不使用代理的域名列表	localhost, 127.0.0.1

5.5 HarmonyOS API参考

• 网络请求:
  request

  API	说明	参数	返回值
  http.createHttp()	创建HTTP请求对象	无	HttpRequest
  http.request(url, options)	发送HTTP请求	url: 请求URL options: 请求配置	Promise\<HttpResponse>
  HttpRequest.request(url, options)	发送请求	url: 请求URL options: 请求配置	Promise\<HttpResponse>
  HttpRequest.setProxy(host, port)	设置代理	host: 代理主机 port: 代理端口	void

• 网络配置:
  connection

  API	说明	参数	返回值
  connection.getDefaultNet()	获取默认网络	无	Promise\<NetHandle>
  connection.hasDefaultNet()	检查默认网络	无	Promise\<boolean>
  connection.getNetCapabilities(netHandle)	获取网络能力	netHandle: 网络句柄	Promise\<NetCapabilities>
  connection.getConnectionProperties(netHandle)	获取连接属性	netHandle: 网络句柄	Promise\<ConnectionProperties>

// 通过JavaScript注入方式配置代理
configureProxy(enabled: boolean, server: string, port: number): void {
  if (!this.controller) return;

  const script = `
    (function() {
      window.__proxyEnabled = ${enabled};
      window.__proxyServer = "${server}";
      window.__proxyPort = ${port};
    })();
  `;
  this.controller.runJavaScript(script);
}

6. 收藏夹管理

6.1 功能概述

允许用户保存、组织和快速访问常用网站，提供收藏夹的创建、编辑、删除和同步功能。

6.2 基础需求

• 收藏操作: 一键收藏当前网页
• 收藏分类: 支持文件夹组织收藏内容
• 批量操作: 支持多选、批量移动/删除
• 导入导出: 支持标准书签格式导入导出
• 搜索功能: 快速查找已保存的收藏

6.3 交互逻辑

操作	动作	结果
添加收藏	点击收藏按钮	保存当前页面到收藏夹
管理收藏	长按收藏项	显示上下文菜单
编辑收藏	选择编辑	打开编辑对话框
删除收藏	选择删除	确认后移除收藏

6.4 详细技术规格

收藏项数据结构

{
  "id": "唯一标识符",
  "title": "网页标题",
  "url": "完整URL",
  "favicon": "图标URL或Base64",
  "folder": "所属文件夹",
  "createTime": "创建时间戳",
  "lastVisitTime": "最后访问时间戳"
}

6.5 HarmonyOS API参考

• 数据存储:
  relationalStore

  API	说明	参数	返回值
  relationalStore.getRdbStore(context, config)	获取关系型数据库	context: 上下文 config: 数据库配置	Promise\<RdbStore>
  RdbStore.insert(table, values)	插入数据	table: 表名 values: 数据对象	Promise\<number>
  RdbStore.update(values, conditions, args)	更新数据	values: 数据对象 conditions: 条件 args: 参数	Promise\<number>
  RdbStore.delete(conditions, args)	删除数据	conditions: 条件 args: 参数	Promise\<number>
  RdbStore.query(table, columns, conditions, args)	查询数据	table: 表名 columns: 列名 conditions: 条件 args: 参数	Promise\<ResultSet>

• UI组件:
  List

  API	说明	参数	返回值
  List()	创建列表组件	无	List组件实例
  List.listDirection()	设置列表方向	Axis	List组件链式调用
  List.divider()	设置分隔线	{ strokeWidth, color, startMargin, endMargin }	List组件链式调用
  List.editMode()	设置编辑模式	boolean	List组件链式调用
  List.onItemDelete()	设置项删除回调	callback	List组件链式调用

// 添加收藏
async addBookmark(title: string, url: string): Promise<boolean> {
  const bookmark = {
    id: generateUUID(),
    title: title,
    url: url,
    createTime: Date.now()
  };
  return await this.bookmarkStore.add(bookmark);
}

7. 主题模式切换

7.1 功能概述

提供浅色、深色和跟随系统三种主题模式，确保在不同光线环境下的视觉舒适度。

7.2 基础需求

• 基础主题: 支持浅色/深色模式
• 自动切换: 跟随系统主题设置
• 计划切换: 根据时间自动切换主题
• 网页适配: 网页内容随主题调整
• WebView主题: 同步更改WebView的色彩模式

7.3 交互逻辑

graph TD
    A[用户选择主题模式] --> B{选择类型?}
    B -->|浅色| C[应用浅色主题]
    B -->|深色| D[应用深色主题]
    B -->|跟随系统| E[监听系统主题]
    E --> F{系统主题?}
    F -->|浅色| C
    F -->|深色| D
    C --> G[应用到UI和WebView]
    D --> G

7.4 详细技术规格

主题模式	UI颜色	状态栏颜色	WebView设置
浅色	背景:#FFFFFF 文本:#000000	背景:#FFFFFF 图标:#000000	darkMode:0
深色	背景:#121212 文本:#FFFFFF	背景:#000000 图标:#FFFFFF	darkMode:1

7.5 HarmonyOS API参考

• 系统主题:
  ColorMode

  API	说明	参数	返回值
  context.getColorMode()	获取当前色彩模式	无	Promise\<ColorMode>
  context.setColorMode(mode)	设置色彩模式	mode: 色彩模式 （0: 浅色, 1: 深色, 2: 跟随系统）	Promise\<void>
  context.on('colorModeChange')	监听色彩模式变化	callback: 回调函数	void

• WebView主题:
  darkMode

  API	说明	参数	返回值
  Web.darkMode()	设置Web组件深色模式	mode: 0(浅色)或1(深色)	Web组件链式调用
  WebviewController.runJavaScript()	执行JavaScript	script: 脚本 callback: 回调函数	Promise\<string>

// 应用主题模式
applyColorMode(mode: ColorMode): void {
  this.colorMode = mode;
  // 更新WebView
  if (this.controller) {
    this.controller.darkMode = mode === ColorMode.DARK ? 1 : 0;
  }
  // 更新系统栏
  this.applySystemBarProperties();
}

8. 沉浸模式设置

8.1 功能概述

沉浸式模式是指应用UI与系统状态栏和导航栏融合的一种显示方式，通过透明化或隐藏系统栏，为用户提供更大的内容显示区域和更沉浸的视觉体验。

8.2 基础需求

支持的沉浸式模式

模式类型	状态栏	导航栏	应用场景
全局沉浸	透明	透明	全屏内容浏览，如视频、阅读
仅导航栏沉浸	不透明	透明	需要状态栏信息但希望最大化纵向空间
无沉浸	不透明	不透明	默认状态，信息密集的页面浏览

8.3 交互逻辑

场景	行为
设置面板打开	强制状态栏不透明，确保UI可见
页面滚动	状态栏沉浸模式下动态调整网页顶部内边距
应用切换前台	重新应用沉浸式设置
屏幕旋转	重新计算安全区域并应用样式
主题切换	更新系统栏颜色

8.4 详细技术规格

状态栏属性

属性	沉浸状态	非沉浸状态
背景色	rgba(0,0,0,0)	深色模式: #000000 浅色模式: #FFFFFF
内容色	深色模式: #FFFFFF 浅色模式: #000000	深色模式: #FFFFFF 浅色模式: #000000
动画	启用	启用

8.5 HarmonyOS API参考

• 窗口管理:
  window

  API	说明	参数	返回值
  window.getLastWindow(context)	获取最近一个窗口	context: 上下文	Promise\<Window>
  Window.setWindowLayoutFullScreen(isFullScreen)	设置全屏模式	isFullScreen: 是否全屏	Promise\<void>
  Window.getWindowAvoidArea(type)	获取窗口避让区域	type: 避让区域类型	AvoidArea
  Window.getWindowProperties()	获取窗口属性	无	WindowProperties
  Window.on('windowSizeChange')	监听窗口尺寸变化	callback: 回调函数	void

• 系统栏属性:
  SystemBarProperties

  API	说明	参数	返回值
  Window.setWindowSystemBarProperties(properties)	设置系统栏属性	properties: 系统栏属性	Promise\<void>
  Window.getWindowSystemBarProperties()	获取系统栏属性	无	SystemBarProperties
  Window.setWindowSystemBarEnable(names)	启用系统栏	names: 系统栏名称数组	Promise\<void>

// 应用沉浸模式
async applySystemBarProperties(): Promise<void> {
  const windowInstance = await window.getLastWindow(this.context);

  const systemBarProps = {
    statusBarColor: this.statusBarImmersive ? 'rgba(0, 0, 0, 0)' : '#FFFFFF',
    navigationBarColor: this.navigationBarImmersive ? 'rgba(0, 0, 0, 0)' : '#FFFFFF',
    statusBarContentColor: this.colorMode === ColorMode.DARK ? '#FFFFFF' : '#000000',
    navigationBarContentColor: this.colorMode === ColorMode.DARK ? '#FFFFFF' : '#000000',
    enableStatusBarAnimation: true,
    enableNavigationBarAnimation: true
  };

  await windowInstance.setWindowSystemBarProperties(systemBarProps);
}

附录：功能交互关系图

graph TD
    Settings[管理面板] --> URL[网址管理]
    Settings --> Privacy[隐私网址]
    Settings --> UA[用户代理]
    Settings --> Proxy[服务器代理]
    Settings --> Bookmark[收藏夹]
    Settings --> Theme[主题模式]
    Settings --> Immersive[沉浸模式]

    Theme --> Immersive
    URL --> Bookmark
    URL --> Privacy

参考资料

1. HarmonyOS应用开发文档
2. Window管理开发指南
3. WebView开发指南
4. 首选项数据管理