前言

Base64编码是将二进制数据转换为ASCII字符串的常用方法，广泛应用于数据传输、图片嵌入、认证令牌等场景。@pura/harmony-utils 的 EncryptUtil 封装了Base64编解码方法。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、Base64核心API

EncryptUtil 提供了以下Base64方法：

方法	说明	返回类型	使用场景
encodeBase64(str)	Base64编码	string	数据编码
decodeBase64(str)	Base64解码	string	数据解码
encodeBase64ToArrayBuffer(str)	编码为ArrayBuffer	ArrayBuffer	二进制处理
decodeBase64FromArrayBuffer(buffer)	从ArrayBuffer解码	string	二进制解码

1.1 核心特性

• 简洁易用：封装复杂逻辑为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 双向转换：支持字符串和ArrayBuffer两种编解码

1.2 Base64编码对照

原文	Base64编码	说明
Hello	SGVsbG8=	基本编码
ABC	QUJD	无填充
你好	5L2g5aW9	中文编码

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 Base64编码

import { EncryptUtil } from '@pura/harmony-utils';

Button('Base64编码')
  .width('100%')
  .onClick(() => {
    try {
      let original = 'Hello harmony-utils!';
      let encoded = EncryptUtil.encodeBase64(original);
      this.result = `原文: ${original}\n编码: ${encoded}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 Base64解码

Button('Base64解码')
  .width('100%')
  .onClick(() => {
    try {
      let encoded = 'SGVsbG8gaGFybW9ueS11dGlscyE=';
      let decoded = EncryptUtil.decodeBase64(encoded);
      this.result = `编码: ${encoded}\n解码: ${decoded}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

import { EncryptUtil } from '@pura/harmony-utils';

@Entry
@Component
struct Base64Demo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('Base64编码').width('100%').onClick(() => {
        let encoded = EncryptUtil.encodeBase64('Hello harmony-utils!');
        this.result = `编码: ${encoded}`;
      });
      Button('Base64解码').width('100%').onClick(() => {
        let decoded = EncryptUtil.decodeBase64('SGVsbG8=');
        this.result = `解码: ${decoded}`;
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 图片Base64嵌入

import { EncryptUtil, ImageUtil } from '@pura/harmony-utils';

async function imageToBase64(pixelMap: PixelMap): Promise<string> {
  let base64 = await ImageUtil.pixelMapToBase64(pixelMap);
  return `data:image/png;base64,${base64}`;
}

4.2 认证令牌

function createBasicAuth(username: string, password: string): string {
  let credentials = `${username}:${password}`;
  return `Basic ${EncryptUtil.encodeBase64(credentials)}`;
}

五、注意事项

1. 编码膨胀：Base64编码后体积增加约33%
2. 非加密：Base64是编码不是加密，不提供安全性
3. 中文处理：中文编码需要先转为UTF-8字节
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 填充字符：Base64编码末尾可能有=填充

六、常见问题

Q1: Base64编码是加密吗？

不是，Base64是编码方式，任何人都可以解码，不能用于保护数据。

Q2: 编码后数据变大多少？

约增大33%，每3个字节编码为4个字符。

Q3: 解码失败会怎样？

安全解码会返回空字符串或抛出可控异常。

Q4: 如何处理大文件的Base64？

大文件建议分块编码，避免内存溢出。

总结

EncryptUtil 的Base64编解码方法为数据编码提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以利用这些方法实现数据编码、图片嵌入等功能。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。