base64-cj 快速开始：HarmonyOS 中 Base64 编解码的最简实战指南

base64-cj 是一个让 ArkTS 直接调用 Cangjie 版 Base64 编解码算法的 HarmonyOS 开源库，只需一行安装命令 + 几行导入代码，就能在你的应用里实现字符串与二进制数据的 Base64 快速转换。本指南面向新手，带你 5 分钟跑通第一个示例。

项目简介：它能解决什么问题？

在 HarmonyOS 应用开发中，Base64 编解码经常出现在文件上传、Token 处理、图片传输等场景。base64-cj 把 Cangjie 语言的 Base64 算法封装成 ArkTS 可调用的接口，特点如下：

特性	说明
🧩 开箱即用	ohpm 中心仓安装，一行命令引入
⚡ 高性能	算法由 Cangjie 编译为动态库，ArkTS 侧直接调用
📦 全类型覆盖	支持 string / Uint8Array 的编码与解码
🔓 开源免费	Apache License 2.0 协议

项目目录结构清晰，示例与源码分离，方便学习：

• entry/ —— 完整示例代码（含 ArkTS 侧与 Cangjie 侧的对比页面）
• library/ —— 库源码，其中 index.cj 是 Cangjie 算法核心，MainPage.ets 是对外 ArkTS 接口

快速安装：两种引入方式

方式一：ohpm 中心仓安装（推荐）

在项目根目录执行：

ohpm install @cangjie-tpc/base64

方式二：本地模块引入

1. 克隆项目：git clone https://gitcode.com/Cangjie-TPC/base64-cj
2. 将 library 模块拷贝到你的应用项目下
3. 在 entry 的 oh-package.json5 的 dependencies 中添加：

{
  "dependencies": {
    "@cangjie-tpc/base64": "file:../library"
  }
}

一键导入 API：5 个接口速查

安装完成后，从 @cangjie-tpc/base64cj 导入即可，接口一览：

接口	功能	入参 → 出参
encode_String	字符串编码	string → string
decode_string	Base64 解码为字符串	string → string
encode_Uint8Array	二进制编码	Uint8Array → string
decode_String_toUint8Array	Base64 解码为二进制	string → Uint8Array
decode_Uint8Array	二进制解码	Uint8Array → Uint8Array

最简实战：3 行代码完成编码

以字符串编码为例，核心逻辑只需三行：

import { encode_String, decode_string } from "@cangjie-tpc/base64cj"

this.encodeResult = encode_String(this.data)      // 编码
this.decodeResult = decode_string(this.encodeResult)  // 解码

完整可运行的界面示例见 CangjieBase64Example.ets，它用两个按钮演示了点击编码、点击解码的完整交互流程；二进制（UTF-8）版本可参考 CangjieBase64Utf8Example.ets。

💡 小贴士：项目首页 Index.ets 同时提供了系统原生 Base64、base64-js、Cangjie 版三种方案的对比入口，方便你做性能选型。

运行环境要求

在以下版本验证通过，请确保工具链匹配：

• DevEco Studio 5.0.13.210
• Cangjie Support Plugin 5.0.13.210

构建配置详见 cjpm.toml，它定义了 aarch64 / x86_64 各平台的编译参数，一般无需改动。

常见问题 FAQ

Q：ArkTS 里已有 Base64 工具，为什么还要用它？ A：base64-cj 底层由 Cangjie 编译为本地动态库执行，在大量数据处理场景下可作为性能备选方案，示例工程内置了对比页面供你实测。

Q：解码失败会报错吗？ A：不会抛出异常。非法 Base64 输入时，Cangjie 侧返回空结果（空字符串或空数组），业务层需自行校验，参考 index.cj 中的 match 处理逻辑。

写在最后

base64-cj 用最少的代码成本，把 Cangjie 的高性能 Base64 能力接入到 HarmonyOS 应用。只需记住三步：ohpm 安装 → 导入模块 → 调用 5 个接口。更多细节可查看 library/README.md 与 CHANGELOG.md。

项目基于 Apache License 2.0 开源（见 LICENSE），欢迎提交 Issue 或参与贡献。