跳到正文

Base64 编解码方法 API ​

本文逐项记录 @fast-china/utils 的 Base64 编解码公开函数。

文本 API 统一使用内部 UTF-8 实现,不依赖 TextEncoder / TextDecoder,不修改全局对象。非法 UTF-8 仍抛出 TypeError;解码移除开头的一个 BOM,编码将孤立代理项替换为 U+FFFD。Base64、Base64URL 与 SecureBase64 的持久化格式保持不变。

encodeBase64Bytes 编码 ​

将任意字节编码为标准 Base64。

签名 ​

ts
export function encodeBase64Bytes(bytes: Uint8Array): string;

示例 ​

ts
import { encodeBase64Bytes } from "@fast-china/utils";

const result = encodeBase64Bytes(new Uint8Array([70, 97, 115, 116]));
console.log(result); // "RmFzdA=="

输入 ​

输入值输入值类型必填/默认值输入值说明
bytesUint8Array是不会被修改的字节序列。

返回 ​

返回值返回值类型返回值说明
resultstring带标准 = 填充的 Base64 文本。

decodeBase64Bytes 解码 ​

解码标准 Base64。

签名 ​

ts
export function decodeBase64Bytes(value: string): Uint8Array;

示例 ​

ts
import { decodeBase64Bytes } from "@fast-china/utils";

const result = decodeBase64Bytes("RmFzdA==");

输入 ​

输入值输入值类型必填/默认值输入值说明
valuestring是Base64 文本。

返回 ​

返回值返回值类型返回值说明
resultUint8Array新建的字节数组。

encodeBase64 编码 ​

将 UTF-8 文本编码为标准 Base64。

签名 ​

ts
export function encodeBase64(value: string): string;

示例 ​

ts
import { encodeBase64 } from "@fast-china/utils";

const result = encodeBase64("Fast 文档");

输入 ​

输入值输入值类型必填/默认值输入值说明
valuestring是任意 Unicode 字符串。

返回 ​

返回值返回值类型返回值说明
resultstring带标准填充的 Base64 文本。

decodeBase64 解码 ​

将标准 Base64 解码为 UTF-8 文本。

签名 ​

ts
export function decodeBase64(value: string): DecodedText;

示例 ​

ts
import { decodeBase64 } from "@fast-china/utils";

const result = decodeBase64("RmFzdA==");

输入 ​

输入值输入值类型必填/默认值输入值说明
valuestring是Base64 文本。

返回 ​

返回值返回值类型返回值说明
resultDecodedText可直接使用或显式调用 .parseJson<Value>() 的原始 Unicode 字符串。

encodeBase64UrlBytes 编码 ​

将任意字节编码为无填充 Base64URL。

签名 ​

ts
export function encodeBase64UrlBytes(bytes: Uint8Array): string;

示例 ​

ts
import { encodeBase64UrlBytes } from "@fast-china/utils";

const result = encodeBase64UrlBytes(new Uint8Array([70, 97, 115, 116]));

输入 ​

输入值输入值类型必填/默认值输入值说明
bytesUint8Array是不会被修改的字节序列。

返回 ​

返回值返回值类型返回值说明
resultstring仅使用 URL 安全字母表的文本。

decodeBase64UrlBytes 解码 ​

解码 Base64URL 字节。

签名 ​

ts
export function decodeBase64UrlBytes(value: string): Uint8Array;

示例 ​

ts
import { decodeBase64UrlBytes } from "@fast-china/utils";

const result = decodeBase64UrlBytes("RmFzdA");

输入 ​

输入值输入值类型必填/默认值输入值说明
valuestring是Base64URL 文本。

返回 ​

返回值返回值类型返回值说明
resultUint8Array新建的字节数组。

encodeBase64Url 编码 ​

将 UTF-8 文本编码为无填充 Base64URL。

签名 ​

ts
export function encodeBase64Url(value: string): string;

示例 ​

ts
import { encodeBase64Url } from "@fast-china/utils";

const result = encodeBase64Url("Fast 文档");

输入 ​

输入值输入值类型必填/默认值输入值说明
valuestring是任意 Unicode 字符串。

返回 ​

返回值返回值类型返回值说明
resultstring仅使用 URL 安全字母表的文本。

decodeBase64Url 解码 ​

将 Base64URL 解码为 UTF-8 文本。

签名 ​

ts
export function decodeBase64Url(value: string): DecodedText;

示例 ​

ts
import { decodeBase64Url } from "@fast-china/utils";

const result = decodeBase64Url("RmFzdA");

输入 ​

输入值输入值类型必填/默认值输入值说明
valuestring是带填充或无填充的 Base64URL 文本。

返回 ​

返回值返回值类型返回值说明
resultDecodedText可直接使用或显式调用 .parseJson<Value>() 的原始 Unicode 字符串。

encodeLatin1Base64 编码 ​

把 Latin-1 文本编码为标准 Base64。

签名 ​

ts
export function encodeLatin1Base64(value: string): string;

示例 ​

ts
import { encodeLatin1Base64 } from "@fast-china/utils";

const result = encodeLatin1Base64("Fast");

输入 ​

输入值输入值类型必填/默认值输入值说明
valuestring是每个 UTF-16 码元都必须位于 0–255 的文本。

返回 ​

返回值返回值类型返回值说明
resultstring带标准填充的 Base64 文本。

decodeLatin1Base64 解码 ​

把标准 Base64 解码为 Latin-1 文本。

签名 ​

ts
export function decodeLatin1Base64(value: string): DecodedText;

示例 ​

ts
import { decodeLatin1Base64 } from "@fast-china/utils";

const result = decodeLatin1Base64("RmFzdA==");

输入 ​

输入值输入值类型必填/默认值输入值说明
valuestring是标准 Base64 文本;允许 ASCII 空白和省略尾部填充。

返回 ​

返回值返回值类型返回值说明
resultDecodedText可直接使用或显式调用 .parseJson<Value>() 的 Latin-1 原始字符串。

encodeSecureBase64 编码 ​

使用固定字典和随机前缀编码文本。

默认 6 位字母前缀、固定字典和有效载荷格式保持不变。随机索引异常、无法生成完整前缀时抛出 Error,不返回缺失前缀字符的结果。非法前缀长度抛出 RangeError;输入包含孤立代理项时保留平台的 URIError。

签名 ​

ts
export function encodeSecureBase64(value: string, prefixLength: number = defaultRandomPrefixLength): string;

示例 ​

ts
import { encodeSecureBase64 } from "@fast-china/utils";

const result = encodeSecureBase64("Fast");

输入 ​

输入值输入值类型必填/默认值输入值说明
valuestring是任意可由 encodeURIComponent 处理的 Unicode 文本。
prefixLengthnumber否,默认 defaultRandomPrefixLength随机字母前缀长度;默认 6。

返回 ​

返回值返回值类型返回值说明
resultstring带随机前缀和兼容字典字符的 Base64 文本;空输入返回空字符串。

decodeSecureBase64 解码 ​

解码 生成的 SecureBase64 兼容格式。

签名 ​

ts
export function decodeSecureBase64(value: string, prefixLength: number = defaultRandomPrefixLength): DecodedText;

示例 ​

ts
import { decodeSecureBase64, encodeSecureBase64 } from "@fast-china/utils";

const payload = encodeSecureBase64("Fast");
const result = decodeSecureBase64(payload);

输入 ​

输入值输入值类型必填/默认值输入值说明
valuestring是SecureBase64 文本;必须使用与编码时相同的前缀长度。
prefixLengthnumber否,默认 defaultRandomPrefixLength需要移除的前缀长度;默认 6,传入 0 时不移除字典字符。

返回 ​

返回值返回值类型返回值说明
resultDecodedText可直接使用或显式调用 .parseJson<Value>() 的原始 Unicode 字符串;空输入返回空字符串。

DecodedText.parseJson 解析 ​

显式尝试把解码或解密后的原始字符串解析为 JSON。

签名 ​

ts
parseJson<Value = any>(): Value;

示例 ​

ts
import { decodeBase64 } from "@fast-china/utils";

const text = decodeBase64("eyJpZCI6MX0=");
const result = text.parseJson<{ id: number }>();

输入 ​

该方法没有输入参数。

返回 ​

返回值返回值类型返回值说明
resultValue合法 JSON 的解析结果;无效 JSON 返回原始字符串。泛型不执行运行时校验。