移动开发跨平台前端UI组件OpenHarmony【免费下载链接】weexA framework for building Mobile cross-platform UI项目地址https://gitcode.com/gh_mirrors/we/weex点击查看免费下载导读本文基于 WebSceneAPI 模块 内置的 js-base64 库位于common/js-base64目录展开系统讲解这一纯 JavaScript Base64 编解码库的安装方式、多端导入方法、完整 API 用法与内部实现原理并结合仓库源码揭示它在本项目中如何支撑「Base64 图片数据落盘相册」这一真实业务场景。读完本文你将掌握在 Web 端、Node.js 端以及鸿蒙 ArkTS 工程中正确选用encode/decode、btoa/atob、fromUint8Array/toUint8Array等 API 的完整技能并理解 URL-safe Base64 与 UTF-8 多字节字符处理的底层细节。一、js-base64 是什么定位与仓库内位置js-base64 是一个用纯 JavaScript 实现的 Base64 转码器transcoder其 package.json 中自我描述为 Yet another Base64 transcoder in pure-JS采用 BSD-3-Clause 开源协议仓库内锁定的版本为3.7.5。在本仓库的鸿蒙化工程中它作为第三方公共代码被放置在ohos/web_api_ohos/WebSceneAPI/src/main/ets/common/js-base64/ ├── LICENSE.md # BSD-3-Clause 许可证 ├── README.md # 本文依据的原始使用文档 ├── base64.d.ts # TypeScript 类型声明ArkTS 工程类型检查依据 ├── base64.js # CommonJS / UMD 版本自动生成 ├── base64.mjs # ES Module 版本由 base64.ts 编译而来 └── package.json # 包元信息与版本号三个发布产物各有分工base64.mjs面向 ES Module 生态base64.js是面向老环境的 UMD/CommonJS 版本base64.d.ts提供完整类型声明——这正是 ArkTS 工程能够以import { Base64 } from .../js-base64/base64方式获得类型提示的基础。二、安装与引入四种加载方式的完整对比2.1 npm 安装在任意支持 Node.js 的工程中一行命令即可安装$ npm install --save js-base642.2 浏览器端传统script标签本地引入script srcbase64.js/script也可以不经过安装直接通过 CDN 引入base64.min.js构建产物。这种传统方式会把Base64挂载到全局对象window上。虽然库提供了Base64.noConflict()用于恢复被占用的全局变量但原文档建议除非必要应优先使用 ES6 Module 方式避免污染window全局作用域。这一点在 base64.js 的 UMD 包装代码中可以得到印证——它检测exports/module/defineAMD都不存在时才把gBase64挂到全局并附带noConflict方法。2.3 ES6 Module推荐本地安装后按需导入import { Base64 } from js-base64;如果不希望引入Base64命名空间可以只导入需要的函数import { encode, decode } from js-base64;也可以直接从 CDN 的base64.mjs文件远程导入注意 jsdelivr 对.mjs不做自动压缩。2.4 Node.jsCommonJSconst {Base64} require(js-base64);与浏览器全局挂载不同CommonJS 方式不会修改任何全局对象。如果习惯import语法还可以借助esm加载器requirerequire(esm)(module); import {Base64} from js-base64;三、API 速览一张表看懂全部核心方法下表整理了 base64.d.ts 中声明的全部公开接口并标注了它们在base64.mjs中的实现位置方法作用参数源码位置base64.mjsencode(src, urlsafe?)UTF-8 字符串 → Base64urlsafetrue时输出 URL-safe 结果L123-L125encodeURI(src)等价于encode(src, true)—L130decode(src)Base64 → UTF-8 字符串兼容普通与 URL-safe 两种输入—L208btoa(bin)二进制字符串 → Base64同浏览器btoa仅接受 Latin-1 字节—L62-L64atob(asc)Base64 → 二进制字符串同浏览器atob—L185-L187fromUint8Array(u8a, urlsafe?)Uint8Array→ Base64 字符串urlsafetrue时输出 URL-safe 结果L81toUint8Array(str)Base64 →Uint8Array—L195isValid(src)校验值是否为合法 Base64 字符串非字符串直接返回falseL213-L218extendString()/extendUint8Array()/extendBuiltins()按需扩展内置原型—L228-L251另有btoaPolyfill、atobPolyfill两个 polyfill 版本以及标注为deprecated、仅供内部使用的utobUTF-16 → UTF-8与btouUTF-8 → UTF-16不建议业务代码直接调用。四、典型用法编码与解码的完整示例4.1 编码方向let latin dankogai; let utf8 小飼弾 let u8s new Uint8Array([100,97,110,107,111,103,97,105]); Base64.encode(latin); // ZGFua29nYWk Base64.encode(latin, true); // ZGFua29nYWk skips padding Base64.encodeURI(latin); // ZGFua29nYWk Base64.btoa(latin); // ZGFua29nYWk Base64.btoa(utf8); // raises exception Base64.fromUint8Array(u8s); // ZGFua29nYWk Base64.fromUint8Array(u8s, true); // ZGFua29nYW which is URI safe Base64.encode(utf8); // 5bCP6aO85by Base64.encode(utf8, true) // 5bCP6aO85by- Base64.encodeURI(utf8); // 5bCP6aO85by-要点解读encode面向 UTF-8 文本小飼弾这类多字节字符会被先转成 UTF-8 字节序列再编码所以encode能正确处理非 Latin-1 内容而btoa遇到超过 255 的码点会抛出TypeError(invalid character found)见 btoaPolyfill 的逐字节校验逻辑。urlsafe参数encode(utf8, true)得到5bCP6aO85by-末尾的填充被去掉、变-、/变_这正是 RFC 4648 §5 定义的 URL 与文件名安全字符集。实现上由_mkUriSafe完成L34-L35。fromUint8Array处理二进制当数据本身是字节数组如图片、文件分片时用它最合适避免字符串中间转换的性能损耗。4.2 解码方向Base64.decode( ZGFua29nYWk);// dankogai Base64.decode( ZGFua29nYWk); // dankogai Base64.atob( ZGFua29nYWk);// dankogai Base64.atob( 5bCP6aO85by);// å°é£¼å¼¾ which is nonsense Base64.toUint8Array(ZGFua29nYWk);// u8s above Base64.decode( 5bCP6aO85by);// 小飼弾 // note .decodeURI() is unnecessary since it accepts both flavors Base64.decode( 5bCP6aO85by-);// 小飼弾关键差异decode输出 UTF-8 文本对5bCP6aO85by解码得到正确的中文小飼弾。它通过_unURI先把 URL-safe 字符-/_还原为//L202因此同时兼容普通与 URL-safe 两种输入无需单独调用decodeURI。atob输出原始二进制字符串用它解码5bCP6aO85by得到的是乱码字节串å°é£¼å¼¾——这是正常现象因为atob不负责 UTF-8 到文本的还原。toUint8Array还原字节数组这是解码二进制数据PNG、音视频的首选入口。4.3 输入合法性校验Base64.isValid(0); // false: 0 is not string Base64.isValid(); // true: a valid Base64-encoded empty byte Base64.isValid(ZA); // true: a valid Base64-encoded d Base64.isValid(Z A); // true: whitespaces are okay Base64.isValid(ZA); // true: padding s can be omitted Base64.isValid(); // true: can be non URL-safe Base64.isValid(--); // true: or URL-safe Base64.isValid(-); // false: cant mix bothisValid的实现L213-L218先剔除空白字符与末尾的填充再分别校验「标准字符集」与「URL-safe 字符集」是否纯净——允许整个输入都是//风格或都是-/_风格但不允许混用两种字符集因此-判定为false。五、内置扩展按需给原型挂方法默认情况下js-base64不会触碰任何内置原型。需要时须显式调用扩展函数// 扩展 String.prototype Base64.extendString(); dankogai.toBase64(); // ZGFua29nYWk 小飼弾.toBase64(); // 5bCP6aO85by 小飼弾.toBase64(true); // 5bCP6aO85by- 小飼弾.toBase64URI(); // 5bCP6aO85by- ab alias of .toBase64(true) 小飼弾.toBase64URL(); // 5bCP6aO85by- an alias of .toBase64URI() ZGFua29nYWk.fromBase64(); // dankogai 5bCP6aO85by.fromBase64(); // 小飼弾 5bCP6aO85by-.fromBase64(); // 小飼弾 5bCP6aO85by-.toUint8Array();// u8s above// 扩展 Uint8Array.prototype Base64.extendUint8Array(); u8s.toBase64(); // ZGFua29nYWk u8s.toBase64URI(); // ZGFua29nYWk u8s.toBase64URL(); // ZGFua29nYWk an alias of .toBase64URI()// 一次扩展全部 Base64.extendBuiltins()实现细节值得注意extendString与extendUint8Array使用Object.defineProperty且设置enumerable: false见 L220-L244这样新增方法不会出现在for...in枚举结果中避免污染常规遍历。toBase64URI与toBase64URL是同一函数的两个别名。六、进阶甄别decode()vsatob()选错会出大事假设你需要处理下面这个 Base64 编码的 1×1 透明 PNGvar pngBase64 iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII;绝对不要用Base64.decode(pngBase64)去解码它。原因Base64.decode()输出的是UTF-8 字符串——它会尝试把解出的字节按 UTF-8 语义还原成文本二进制 PNG 字节流几乎必然产生非法 UTF-8 序列结果被替换或损坏Base64.atob()输出的是原始字节字符串与浏览器内置atob()Node.js 中没有语义兼容适合还原二进制更稳妥的做法是Base64.toUint8Array(pngBase64)直接得到可写入文件、可交给图像解码器的Uint8Array。编码方向同理文本用encode()二进制字节串用btoa()字节数组用fromUint8Array()。七、仓库实战在鸿蒙 WebSceneAPI 中把 Base64 图片落盘相册js-base64 在本仓库并不是摆设WSMedia.ets 在「保存图片到相册」功能中真实使用了它。引入方式import { Base64 } from ../../common/js-base64/base64;在saveImg并发任务函数中L89-L114图片以 Base64 字符串形式传入处理流程为let uri: string await photoAccessHelper.getPhotoAccessHelper(param.context) .createAsset(photoAccessHelper.PhotoType.IMAGE, png); let imageData: string Base64.atob(param.value); // ① 解码为原始字节串 let file: fs.File fs.openSync(uri, fs.OpenMode.WRITE_ONLY); let arrayBuffer: ArrayBuffer new ArrayBuffer(imageData.length); let ia: Uint8Array new Uint8Array(arrayBuffer); for (let i 0; i imageData.length; i) { ia[i] imageData.charCodeAt(i); // ② 字节串 → ArrayBuffer } fs.writeSync(file.fd, ia.buffer); // ③ 写入相册文件 fs.closeSync(file);这段代码堪称上一节结论的教科书式应用处理图片这类二进制数据时选用Base64.atob()而非Base64.decode()得到逐字节无损的原始串后手工填充进ArrayBuffer再落盘。整个过程运行在Concurrent标记的任务池线程中见 saveImg 定义解码耗时不会阻塞 UI 线程。仓库还配套了「保存图片到相册」的权限申请ohos.permission.WRITE_IMAGEVIDEO与失败回滚逻辑可作为 ArkTS 工程中二进制数据处理链路的完整参考。八、版本演进为什么 3.7 特别重要原文档的 Brief History 记录了三个关键节点结合 base64.js 与 base64.mjs 的文件形态可以相互印证3.0 起改用 ES2015 模块规范不再兼容 IE 等老浏览器3.3 起改用 TypeScript 编写构建流程为base64.ts → base64.mjs → base64.js因此仓库中的base64.js文件头部明确标注 THIS FILE IS AUTOMATICALLY GENERATED! DO NOT EDIT BY HAND!base64.js3.7 起重新回归 ES5 兼容进而兼容 IE11同时在本仓库锁定的 3.7.5 版本提供了base64.d.ts类型声明这正是 ArkTS 工程能够无缝import并使用完整类型提示的前提。九、总结js-base64 虽然自称 Yet another Base64 transcoder但凭借纯 JS 零依赖、三端浏览器/CommonJS/ESM产物齐备、URL-safe 支持、Uint8Array桥接与可选的原型扩展等设计成为鸿蒙 WebSceneAPI 工程中值得信赖的编解码底座。实践中只需记住三条铁律文本用encode/decode二进制字节串用btoa/atob字节数组用fromUint8Array/toUint8Array处理图片等二进制请远离decode()。相关源码可在 js-base64 目录 与 WSMedia.ets 中继续深入研读。赞分享移动开发跨平台前端UI组件OpenHarmony【免费下载链接】weexA framework for building Mobile cross-platform UI项目地址https://gitcode.com/gh_mirrors/we/weex点击查看免费下载相关推荐如何轻松掌握Base64编码解码超实用的JavaScript库base64-js完整指南如何轻松掌握Base64编码解码超实用的JavaScript库base64 js完整指南 在Web开发和数据处理中Base64编码解码是一项基础且常用的技术开发工具js-base64JavaScript 中最完整的 Base64 编码解码终极指南js base64JavaScript 中最完整的 Base64 编码解码终极指南 还在为 JavaScript 中的 Base64 编码问题而困扰吗面对复序列化js-base64JavaScript 中最完整的 Base64 编码解码终极指南 js base64JavaScript 中最完整的 Base64 编码解码终极指南 在当今Web开发中Base64编码解码是不可或缺的核心技术而 j序列化上一篇彻底解决fastlane超时难题从构建卡死到精准控制的实战指南下一篇XJoy将任天堂Switch Joy-Con变身高性能PC游戏手柄的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
