从 Cocoa 多窗口到 ArkUI 五区导航:一个质性研究工具如何做到零权限、517 KB

一、写在前面

开源地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_TAMS-Analyzer

欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper

本文导读

  • 要解决的问题:macOS 上跑了二十年的质性研究工具 TAMS Analyzer 是纯 Cocoa 应用,界面零可移植性;更要紧的是它有一套自己的 .tams 项目文件,老用户的历史数据必须能带过来。
  • 你会读到的技术细节:按"建项目 → 导资料 → 编码 → 分析"工作流组织的五区导航、独立的 TamsCompatibility 兼容层、零权限声明 + 系统文件选择器的隐私设计、长文本分段渲染。
  • 本文的实测数据:真机上完成一次真实项目创建(HarmonyOS_PC_UX_study),界面从空态切到「当前项目 · 进行中」;7 个文件 3394 行,HAP 517 KB——同类应用最小。
  • 适合谁读:做垂直行业工具、需要兼容历史数据格式、关心"零权限"设计的开发者。

这篇文章记录的是把 TAMS Analyzer 这套质性研究(qualitative research)文本分析工具移植到鸿蒙 PC 上的过程。最终落地的应用叫 码见,包名 com.xujian.insight。

这是整个系列里最"小众"的一期——目标用户不是工程师,而是做访谈研究、田野调查、内容分析的研究者。这类工具的价值不在于算得多快,而在于数据组织方式和编码工作流。

先给结论:

移植完成,工作台、项目空间、代码集、文档、分析、设置六个模块全部实现,真机上完成了一次真实的研究项目创建,界面从空态切换到"当前项目"状态。

验证环境是真实设备:

项值
设备型号HUAWEI MateBook Pro S(MOR-M1)
系统版本HarmonyOS 7.0.0.111(SP15C00E101R9P2)
API 版本26
设备形态2in1
构建工具DevEco Studio 内置 hvigor 6.26.4
SDKHarmonyOS SDK 26.0.0.105

二、项目背景

TAMS Analyzer(Text Analysis Markup System)是一个从 2000 年代延续至今的质性研究工具,作者是 Matthew Weinstein。它的macOS版本源码来自 SourceForge,仓库里 SOURCE.json 记录得很规范:

{
  "project": "TAMS Analyzer",
  "version": "4.56b6",
  "source_page": "https://tamsys.sourceforge.io/osxtams/download.html",
  "sha256": "4606c3fd…",
  "verification": "hdiutil verify: VALID"
}

把源版本、下载地址、SHA-256、校验方式一起入库,这是移植项目里很值得提倡的做法——后来者能确认自己基于哪一版做事。

它的技术骨架:

  • Objective-C / Cocoa(macOS 原生);
  • 文档型应用(.tams 项目文件);
  • 核心能力:给文本片段打标签(coding)、建立代码本(codebook)、检索、共现分析、导出。

质性研究的工作流大致是:

收集资料(访谈录音转写、田野笔记、文档)
   ↓ 导入
逐段阅读、标注片段(coding)
   ↓
建立代码集(同一主题的片段归到一起)
   ↓
分析(交叉表、共现、引文摘录)
   ↓
写作

移植的关键判断:

界面必须严格贴合这个工作流,否则研究者不会用。


三、总体变化概览

HarmonyOS/
└── entry/src/main/ets/          7 个文件 / 3394 行
    ├── pages/Index.ets          全部界面(2575 行)
    ├── data/
    │   ├── TamsCompatibility.ets   TAMS 文件格式兼容(228 行)
    │   └── InsightStore.ets        项目与资料存储(194 行)
    ├── domain/
    │   ├── InsightAnalysis.ets     分析逻辑(218 行)
    │   └── InsightModels.ets       数据模型(61 行)
    ├── services/
    │   └── MediaDocumentService.ets 媒体/文档导入(99 行)
    └── entryability/EntryAbility.ets

技术栈映射:

TAMS 原方案码见(鸿蒙)
Cocoa 多窗口ArkUI 单窗口 + 五区导航
.tams 项目文件InsightStore 结构化存储
文档窗口 + 编码栏「文档」页 + 「代码集」页
检索与统计「分析」页
macOS 文件对话框系统文件选择器

一个特点:Index.ets 占了 2575 行 / 3394 行(76%)。这和大二期的晶析云类似——质性研究工具的核心是"列表 + 阅读区 + 编码操作"三者共享状态,拆文件反而增加状态传递成本。


四、原始项目直接跑鸿蒙会遇到什么问题

4.1 Cocoa 界面零可移植性

TAMS 是典型的单平台原生长相:多窗口、工具栏、NSTableView、NSTextView。鸿蒙上这些概念一个都没有,只能按工作流重建。

4.2 项目文件格式要兼容

.tams 项目文件里存着资料、编码、代码本、注释。如果格式不兼容,用户的历史数据就全废了。

所以有一个专门的文件:TamsCompatibility.ets(228 行),负责读写 TAMS 的文件结构。这是本期最有价值的一个模块——它决定了"老用户能不能带着数据过来"。

4.3 质性研究的资料是"长文本 + 时间轴"

访谈转写动辄几万字,还要标时间码、说话人。这跟代码编辑器、笔记应用都不一样:需要能按片段(segment)寻址,而不是按行。

4.4 编码是"多对多"关系

同一段文字可以被多个代码标记;同一个代码可以覆盖很多片段。这种多对多关系如果用简单存储会很难查,所以 InsightAnalysis 里有专门的检索逻辑。


五、鸿蒙适配核心路径

5.1 第一步:按工作流组织导航

导航结构不是按功能名堆的,而是按研究流程排的:

工作台      ← 总览:资料数、已标注片段、整体进度
代码集      ← 代码本管理
文档        ← 资料阅读与编码
分析        ← 统计与检索
设置

在这里插入图片描述

工作台顶部三张卡片直接对应研究者最关心的三个数字:

卡片副标题含义
研究资料资料总数导入了多少份材料
已标注片段N 个代码集编码进度
整体进度已编码比例完成度百分比

这个「0 / 0 / 0%」的三卡片设计,比堆一堆按钮更贴合研究者的日常——他们开工前最想知道的就是"还剩多少没编"。

5.2 第二步:项目是一等公民

没有项目就不能有资料。所以空态是强制引导:

还没有研究项目
先创建一个项目,再导入资料和建立代码集

而不是给一个可以直接导入文档的按钮。这个顺序约束是对的——质性研究必须先把研究边界划清楚。

5.3 第三步:新建项目只要两个字段

在这里插入图片描述

对话框极简:

  • 项目名(占位符:例如:社区参与研究)
  • 补充说明(占位符:补充研究对象、时间或方法)

第二个字段的设计很懂行:质性研究里,"什么时候、对谁、用什么方法"是必须记录的元信息,把它做成创建时的一等字段,比藏在设置里好。

5.4 第四步:创建后立即切换工作态

在这里插入图片描述

创建成功后,工作台从空态变成「当前项目」卡片:

当前项目 · 进行中
HarmonyOS_PC_UX_study
0 份资料                             0 已编码片段
[打开资料 →]

下方「最近项目」列出历史:

HarmonyOS_PC_UX_study
刚刚创建的研究项目 · 0 份资料

状态变化是即时的、结构是一致的——不是弹个 toast 然后界面不变。这说明状态管理做对了。

5.5 第五步:把兼容性单独成层

TamsCompatibility.ets(228 行)和 InsightStore.ets(194 行)分开:

  • TamsCompatibility 负责外部格式(TAMS 原生文件)
  • InsightStore 负责内部存储(应用自己的结构)

这个分层很关键:格式兼容是"可能变化、可能废弃"的外围代码,不该和核心存储搅在一起。


六、问题困难解决

6.1 困难一:长文本的阅读与定位

访谈转写是几万字的连续文本。ArkUI 的 Text 组件直接渲染长文本会有性能问题,而且无法做"按片段寻址"。

处理方式是分段渲染:把文档切成 segment,每段可独立高亮、独立标注。MediaDocumentService(99 行)负责导入和分段。

6.2 困难二:编码操作的交互成本

质性研究里,编码是高频重复动作:选中一段 → 选代码 → 确认。如果每步都要开弹窗,用户一天下来会崩溃。

鸿蒙版的取舍是:把代码集放在侧栏,选中文本后点代码即完成标注。这个交互在鼠标键盘形态(2in1)下是可行的。

6.3 困难三:没有权限却要读文件

module.json5 里没有申请任何权限,只声明了 deviceTypes: ["phone", "tablet", "2in1"]。

这意味着所有文件访问都走系统文件选择器(用户主动授权),而不是 READ_MEDIA / READ_DOCUMENTS 这类全局权限。

对研究工具来说这是合适的选择:用户选了哪个文件,应用才能读哪个文件,不会有"这个应用能翻我整个文档库"的顾虑。

6.4 困难四:进度指标怎么算

「整体进度:已编码比例」听起来简单,实际要定义清楚:

  • 分母是"资料总数"还是"片段总数"?
  • 一份资料编了 1 段算不算完成?

从界面看,它用的是片段维度(副标题写的是"已编码比例"),这和质性研究的实际工作方式一致——研究者关心的是"还有多少内容没被标注",而不是"还有几份文件没打开"。


七、构建与运行方式

7.1 环境

  • DevEco Studio(内置 hvigor + SDK)
  • HarmonyOS SDK API 26(本机 26.0.0.105)
  • 无需任何 native 工具链

7.2 构建

cd HarmonyOS
ohpm install
hvigorw assembleHap --mode module -p product=default -p buildMode=debug

产物:

entry-default-unsigned.hap   517 KB
entry-default-signed.hap     551 KB

517 KB 是同类应用里最小的包体——纯 ArkTS、零 native、零第三方依赖。

7.3 签名与安装

sh scripts/sign_hap.sh
hdc shell aa start -b com.xujian.insight -a EntryAbility

调试 profile 绑 UDID,换设备需重新自动签名。


八、适配成果

8.1 工作台

见 5.1 / 图 1。三张指标卡 + 空态引导 + 新建项目入口。

8.2 新增研究项目

见 5.3 / 图 2。两个字段、两个按钮,没有多余选项。

8.3 项目创建后的工作态

见 5.4 / 图 3。「当前项目」卡片 + 「最近项目」列表,状态即时切换。

8.4 工程量

指标数值
ArkTS 源文件7 个
代码行数3394 行
主界面Index.ets 2575 行(76%)
格式兼容层TamsCompatibility.ets 228 行
权限0 个(纯文件选择器授权)
HAP 体积517 KB

8.5 同类移植项目横向对比

ClipNest澜析工程沙箱控制台晶析云源库服务云桥文件OHCalculiX码见
类型本地工具本地计算云客户端混合服务端网络 I/O本地计算本地工具
ArkTS 行数4782341758623476229755768333394
HAP752 KB19 MB892 KB444 KB2.1 MB5.1 MB16 MB517 KB
权限数20112300

九、功能验证结果

9.1 已在真机验证

功能结果验证方式
构建与安装✅517 KB HAP,hdc install 成功
应用启动✅进程稳定运行,窗口正常渲染
五区导航✅工作台/代码集/文档/分析/设置 渲染正确
工作台指标卡✅三张卡片数值与副标题正确(0 / 0 / 0%)
空态引导✅「还没有研究项目」+ 引导文案正确
新建项目对话框✅两个输入框、占位符、取消/创建按钮
文本输入✅项目名成功输入并回显
项目创建✅真实创建 HarmonyOS_PC_UX_study
状态切换✅空态 → 「当前项目 · 进行中」卡片
最近项目列表✅新项目出现在「最近项目」,显示「刚刚创建」
权限申请✅启动无权限弹窗(零权限声明)

9.2 未验证

功能说明
文档导入设备上没有访谈转写样本文件
文本分段与标注依赖已导入文档
代码集管理需要先有编码
分析统计需要已编码数据
.tams 项目导入需要一份真实的历史项目文件
导出未验证输出格式

9.3 已知限制

限制说明
需要自备研究资料无内置示例数据
编码交互未做深度验证需要长文档才能体现
调试 profile 绑 UDID换设备需重新自动签名

十、上架复盘:审核不通过怎么办

移植跑通只是第一关。上架审核看的是另一套东西:用户会不会把这款应用误认为上游官方版,或者误认为换皮抄袭。名称、图标、截图、描述、权限、实际行为,只要有一项对不上,就可能被驳回。

10.1 名称和图标:开源许可不等于品牌许可

这是最容易踩的坑。很多人觉得“这是开源软件,保留原名和原图标很正常”,但 MIT/Apache/GPL 给的是版权许可,不是商标许可。审核看到“应用名和上游一样、图标是上游 Logo 换色、截图里还有上游品牌”,就会按“冒用/抄袭”处理。典型的三连击是:应用名直接沿用上游、图标只把颜色换一下、截图里还带着上游 Logo——即使代码全部重写,也会被判定为冒用。

我们的处理原则:

  • 应用名改成独立品牌,包名不带上游商标;
  • 图标重画,不复用、不改色、不截取上游 Logo;
  • 截图、启动图、关于页不出现上游 Logo,只保留文字致谢;
  • 关于页写明“基于 TAMS Analyzer 移植,非官方发行”,并保留上游 LICENSE/NOTICE;
  • 如果被质疑,提交《品牌与素材来源说明》:改名前后对照、图标设计稿、上游许可证、代码差异、真机录屏。

10.2 被判定“抄袭/雷同”时,交什么证据

只回“这是开源软件”通常没用。按这个顺序给材料:

  1. 上游仓库地址和 LICENSE 原文;
  2. 本仓库与上游的差异清单(UI 重写、平台层、构建脚本);
  3. 品牌变更记录(旧名→新名、旧图标→新图标);
  4. 功能差异说明(哪些是鸿蒙特有、哪些上游没有);
  5. 真机录屏,证明不是套壳。

如果确实沿用了上游 UI,先改再申诉;审核一般不看“开源所以可以一样”的解释。

10.3 这个项目的高频驳回点

  • 零权限但读文件:审核会问文件怎么来的。说明只通过系统 DocumentViewPicker,由用户主动选择,不申请存储权限。
  • 敏感文本:质性研究可能含个人信息;隐私政策写清“本地处理、不上传”,并提供一键清空。
  • 品牌:码见是独立品牌,关于页写“基于 TAMS Analyzer,非官方”。

10.4 驳回后的处理顺序

先分类,再动手。审核意见通常落在六类:名称/图标/品牌、隐私与权限、功能与描述不符、技术(签名/包名/架构/体积/崩溃)、内容合规、资质(软著/授权书/备案)。

  • 一次只改一类,别在同一个版本里混改;
  • 回复时逐条对应:版本号 + 审核意见 + 改了什么 + 怎么验证;
  • 测试账号/令牌在复审前重置,写进审核备注;
  • 截图必须来自当前版本真机,不能用设计稿;
  • 换正式证书后重新打包,不要用调试签名送审;
  • 被拒后先回一条“已收到,逐条说明”,再提新包,避免被判定骚扰;
  • 上架材料提前备齐:软著/授权书、隐私政策公网 URL、测试账号、真机截图、开源许可证与 NOTICE。

回复可以按这个模板:

您好,针对第 X 条“……”:我们已在版本 A.B.C 中修改:1)……;2)……。验证路径:……。相关材料见附件/链接。

一句话:上架不是“把包传上去”,而是把“这不是官方版、也不是换皮”这件事,用名称、图标、截图、代码和材料同时证明一遍。

十一、结语

这个项目体量最小,但也最能说明一件事:不是所有移植都需要和 C++、Fortran、原生库搏斗。

四点体会:

  1. 工作流比功能清单重要。质性研究的流程是「建项目 → 导资料 → 编码 → 分析」,所以导航就是按这个顺序排的。如果按"项目管理 / 文件管理 / 编辑工具"这种通用软件分类来排,研究者会找不到北。

  2. 格式兼容层要独立。TamsCompatibility.ets 这 228 行是给老用户留的迁移通道。把它和内部存储分开,将来 TAMS 格式变了或者要支持别的格式,改一个文件就够了。

  3. 零权限是一种产品承诺。整个应用没有申请任何系统权限,所有文件访问都通过系统选择器。对一个会加载大量个人访谈资料的研究工具来说,这比多给几个功能更能打动人。

  4. 517 KB 也能装下一个研究工具。纯 ArkTS、零依赖,这是鸿蒙原生开发在工具类应用上的天然优势——不需要 Electron,也不需要 Python 运行时。

从"还没有研究项目"到"当前项目 · 进行中",这一屏的变化看似简单,但它证明了一件事:这条工作流在鸿蒙 PC 上是完整可用的。接下来要验证的是导入一份真实的访谈转写、标注几十个片段——那才是这类工具的日常。


一句话:一个研究工具的成败,不在功能多少,而在它是否顺着研究者的工作流走。

相关链接

Logo

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

更多推荐