Android UI 组件到 HarmonyOS ArkUI 组件映射评估工具

功能概述

本项目用于评估 Android UI 组件与 HarmonyOS ArkUI 组件之间的映射关系，主要功能包括：

1. 文档爬取与解析：从官方文档爬取 Android UI 和 HarmonyOS ArkUI 的组件说明文档，并提取关键信息
2. 索引构建：为两套文档构建关键词索引，支持快速检索
3. 映射关系评估：基于人工映射表和官方文档，对映射关系进行逐条评估
4. 覆盖完整性检查：统计映射表对 Android UI 组件的覆盖完整性，输出缺失组件清单

目录结构

android_to_harmonyos/
├── main.py                          # 主程序入口，执行映射评估流程
├── query.py                         # 文档检索函数，根据关键词查找组件信息
├── evaluate_mapping.py              # 映射关系评估函数（待完善）
├── cal_uncalled.py                  # 计算未召回组件的统计脚本
├── extract_chapter.py               # 从HTML中提取指定上下文
├── string_similarity.py             # 字符串相似度计算函数
│
├── crawl_ArkTS.py                   # 爬取鸿蒙 ArkUI 文档
├── crawl_android_url.py             # 获取 Android 文档 URL 列表
├── crawl_copy.py                    # 爬取 Android 文档页面
├── crawl_parellel.py                # 并行批量爬取
│
├── extract_page_info_android.py     # 提取 Android HTML 文档关键信息
├── extract_page_info_ark.py         # 提取鸿蒙 HTML 文档关键信息
├── add_inds.py                      # 构建文档索引
│
├── android_html/                    # Android 文档存储目录
│   ├── *.html                       # 爬取的 HTML 文件
│   ├── *_info.json                  # 提取的结构化信息
│   └── master_info_android.json     # Android 文档索引文件
│
├── arkts_components_html/           # 鸿蒙文档存储目录
│   ├── *.html                       # 爬取的 HTML 文件
│   ├── *.json                       # 提取的结构化信息
│   └── master_info_ark.json         # 鸿蒙文档索引文件
│
├── src/
│   └── three_reference_tables/      # 人工映射参考表
│       ├── android-to-harmonyOS-ui-atomic-component-mapping-reference.json
│       ├── android-to-harmonyOS-ui-interaction-mapping-reference.json
│       └── android-to-harmonyOS-ui-layout-mapping-reference.json
│
└── output/                          # 输出结果目录
    ├── android_parts_recalled.json  # Android 召回组件列表
    ├── ark_parts_recalled.json      # 鸿蒙召回组件列表
    ├── android_parts_unrecalled.json # Android 未召回组件清单
    └── ark_parts_unrecalled.json    # 鸿蒙未召回组件清单

环境要求

• Python 3.8+
• 依赖包：
  • beautifulsoup4
  • requests
  • lxml

安装依赖：

pip install beautifulsoup4 requests lxml

快速开始

1. 完整流程（从爬取到评估）

# 步骤1: 爬取鸿蒙文档（可选，如已有文档可跳过）
python crawl_ArkTS.py

# 步骤2: 爬取Android文档（可选，如已有文档可跳过）
python crawl_android_url.py
python crawl_parellel.py

# 步骤3: 提取文档关键信息
python extract_page_info_android.py android_html/
python extract_page_info_ark.py arkts_components_html/

# 步骤4: 构建索引
python add_inds.py

# 步骤5: 执行映射评估
python main.py

# 步骤6: 统计未召回组件
python cal_uncalled.py

2. 仅执行评估（已有完整数据）

# 执行映射评估和召回统计
python main.py

# 统计未召回组件
python cal_uncalled.py

完整参数示例

main.py

python main.py

执行后会：

1. 加载三张人工映射表
2. 对每条映射关系进行检索和评估
3. 输出 android_parts_recalled.json 和 ark_parts_recalled.json

cal_uncalled.py

python cal_uncalled.py

执行后会：

1. 对比官方文档索引与召回列表
2. 输出 android_parts_unrecalled.json 和 ark_parts_unrecalled.json

extract_page_info_android.py

# 处理单个文件
python extract_page_info_android.py android_html/AbsListView.html

# 处理整个目录
python extract_page_info_android.py android_html/

extract_page_info_ark.py

# 处理单个文件
python extract_page_info_ark.py arkts_components_html/Text.html

# 处理整个目录
python extract_page_info_ark.py arkts_components_html/

extract_chapter.py

# 从HTML中搜索关键词并提取上下文
python extract_chapter.py android_html/AbsListView.html addTouchables --length 500

参数说明

映射关系类型

类型	说明
直接映射	有明确、等价或近似等价的对应组件
间接映射	没有完全等价的组件，但可以通过其他相近组件、组合方式或适配封装来实现
组合映射	安卓中的一个组件/功能，需要鸿蒙中多个组件或能力组合才能实现
自定义实现/二次开发	找不到合适对应项，需要自行封装、自定义组件或重写逻辑
不支持/无对应	ArkUI 平台没有对应能力，且难以合理替代
部分映射	有对应组件，但只覆盖部分能力，仍有一些特性需要额外处理

输出文件格式

android_parts_recalled.json / ark_parts_recalled.json

{
  "total_mapping_entries": 100,
  "recalled_count": 85,
  "recalled_components": ["TextView", "EditText", "Button", ...]
}

android_parts_unrecalled.json / ark_parts_unrecalled.json

{
  "total_components_in_docs": 4850,
  "recalled_count": 85,
  "unrecalled_count": 4765,
  "unrecalled_components": [
    {
      "component_name": "SomeComponent",
      "input_path": "android_html/SomeComponent_info.json",
      "description": "组件描述..."
    }
  ]
}

核心函数说明

evaluate_mapping(ind_contents_tuples_android, ind_contents_tuples_ark)

评估安卓组件与鸿蒙组件的映射关系。

输入：

• ind_contents_tuples_android: 安卓组件信息三元组列表 [[路径, 关键词, 介绍], ...]
• ind_contents_tuples_ark: 鸿蒙组件信息三元组列表

输出：

{
    "judgment_result": "映射关系的具体判断结果描述",
    "relation_type": "关系类型",
    "reasoning": "判定依据和理由",
    "android_info_count": 5,
    "ark_info_count": 3
}

cal_android_parts_recalled(data, android_master_info, output_path)

统计映射表中召回的安卓组件。

cal_ark_parts_recalled(data, ark_master_info, output_path)

统计映射表中召回的鸿蒙组件。

cal_uncalled_android(master_info_path, recalled_path, output_path)

计算安卓官方文档中未被召回的组件。

cal_uncalled_ark(master_info_path, recalled_path, output_path)

计算鸿蒙官方文档中未被召回的组件。

注意事项

1. 确保在运行评估前已完成文档爬取和信息提取
2. master_info_android.json 和 master_info_ark.json 是评估的核心依赖
3. 人工映射表位于 src/three_reference_tables/ 目录下
4. 相似度阈值默认为 0.9，可在 query.py 中调整

待完善功能

1. evaluate_mapping(): 当前为 placeholder 实现，需要结合语义分析进行深度评估
2. 自动生成评估报告: 将逐条评估结果汇总为结构化报告
3. 可视化输出: 生成覆盖率和映射类型的统计图表