# Tencent Qian H5 容器 — HarmonyOS (ArkTS)

腾讯电子签 H5 容器 SDK 的 HarmonyOS NEXT 实现，基于 ArkWeb，提供容器模式 / 组件模式 / 配置模式三种集成方式。

## 工具链

- DevEco Studio 5.0+
- HarmonyOS SDK API 12+（HarmonyOS NEXT 5.0+）
- ArkTS（严格模式）
- 包管理：ohpm（DevEco Studio 内置）
- 构建工具：hvigor 6.x（DevEco Studio 内置）

[`scripts/build-harmony.sh`](../scripts/build-harmony.sh) 会自动从 DevEco Studio 安装目录定位 `hvigorw` / `node` / `ohpm` / `DEVECO_SDK_HOME`，也可通过环境变量（`DEVECO_HOME` / `HVIGOR` / `NODE_HOME` / `OHPM`）显式指定。

## 1. 用 DevEco Studio 打开

直接用 DevEco Studio 打开 `harmonyos-arkts/` 目录。首次打开会自动执行 `ohpm install` 拉取依赖。

选 `entry` 模块，运行到 HarmonyOS NEXT 设备 / 模拟器。

## 2. 命令行构建 / 测试

```bash
bash scripts/build-harmony.sh sdk     # 构建 tencentqianwebview HAR
bash scripts/build-harmony.sh demo    # 构建 entry Demo HAP（unsigned）
bash scripts/build-harmony.sh all     # SDK + Demo 全量
bash scripts/test-harmony.sh          # 跑单元测试
```

构建产物路径：

- SDK HAR：`harmonyos-arkts/dist/tencentqianwebview-<version>.har`
- Demo HAP：`harmonyos-arkts/dist/demo/entry-<version>-unsigned.hap`

## 3. 最小集成代码

```typescript
import {
  TencentQianWebView,
  TencentQianWebViewConfig,
  SignResult,
} from 'tencentqianwebview';
import common from '@ohos.app.ability.common';

TencentQianWebView.open(
  context,                                  // common.UIAbilityContext
  signUrl,
  new TencentQianWebViewConfig(),
  (result: SignResult) => {
    // result.action / result.result / result.flowId / result.extras
  },
);
```

更多集成方式（容器模式 / 组件模式 / 配置模式 / 自行适配）详见 [`tencentqianwebview/README.md`](./tencentqianwebview/README.md) 与 [`docs/`](../docs/)。

## 目录结构

```
harmonyos-arkts/
├── tencentqianwebview/          # SDK 模块（HAR Static Library）
├── entry/                       # Demo 模块（HAP Application）
├── AppScope/                    # App 级公共配置
├── hvigor/                      # hvigor 构建配置
├── build-profile.json5          # 工程级构建配置
├── code-linter.json5            # ArkTS 代码规范
├── oh-package.json5             # 工程级 ohpm 配置
├── hvigorfile.ts                # 工程级构建脚本
└── README.md                    # 本文件
```
