DataConverter

DataConverter是用于数据转换的工具对象，提供编码、压缩、二进制转换、格式桥接和文件类型识别等功能。

类成员(Class members)

属性

方法

addErrorLog

类型

static addErrorLog(error: string|{ message: string; detail?: string },source?: string,info?: string): void

说明

当某个转换方法捕获到异常时，用这个方法统一记录错误并提示用户。与直接console.log不同，它会同时写入errorLog并通过MNUtil.copyJSON把日志复制到剪贴板，方便直接上报。

参数

返回值

• 类型:void
• 语义:方法执行后不返回值。

customBtoa

类型

static customBtoa(str: string): string

说明

使用内置字符表把字符串编码为Base64。该实现不依赖运行环境atob和btoa，适合JSCore兼容场景。

参数

返回值

• 类型:string
• 语义:返回Base64编码结果。

utf8_to_b64

类型

static utf8_to_b64(str: string): string

说明

先按UTF-8处理文本再输出Base64结果。输入含中文等多字节字符时可避免直接编码导致乱码。

参数

返回值

• 类型:string
• 语义:返回按UTF-8处理后的Base64编码结果。

compressAndEncode

类型

static compressAndEncode(jsonObj: object,type?: 'pako'|'lz-string'): string|undefined

说明

把对象序列化后压缩并编码为Base64字符串。压缩或编码失败时返回undefined并记录错误日志。

参数

返回值

• 类型:string|undefined
• 语义:成功返回string，失败返回undefined。

decodeAndDecompress

类型

static decodeAndDecompress(base64: string,type?: 'pako'|'lz-string'): string|undefined

说明

把压缩Base64文本解码并还原为原始字符串。输入格式不合法或算法不匹配时返回undefined并记录错误日志。

参数

返回值

• 类型:string|undefined
• 语义:成功返回string，失败返回undefined。

atob

类型

static atob(base64Str: string): string

说明

Base64解码为字符串。

参数

返回值

• 类型:string
• 语义:返回Base64解码后的字符串。

btoa

类型

static btoa(input: string|Uint8Array): string

说明

字符串或Uint8Array转Base64编码。

参数

返回值

• 类型:string
• 语义:返回Base64编码后的字符串。

rgbaToHex

类型

static rgbaToHex(rgba: { r: number; g: number; b: number; a: number },includeAlpha?: boolean,toUpperCase?: boolean): string

说明

• 把{ r, g, b, a }颜色对象转换成十六进制字符串，适合在UI配置里直接使用。

• 和rgbaArrayToHexArray的区别是这里只处理单个颜色对象。

参数

返回值

• 类型:string
• 语义:返回十六进制颜色字符串，默认包含#前缀。

rgbaArrayToHexArray

类型

static rgbaArrayToHexArray(rgbaArray: Array<{ r: number; g: number; b: number; a: number }>,includeAlpha?: boolean,toUpperCase?: boolean): string[]

说明

• 批量把RGBA数组转换成十六进制颜色数组，常用于一次生成主题色板。

参数

返回值

• 类型:string[]
• 语义:返回与输入顺序一致的十六进制颜色字符串数组。

hexToRgb

类型

static hexToRgb(hex: string): [number,number,number]

说明

• 把#RRGGBB颜色字符串还原为[r,g,b]数组。

• 和parseHexColor相比，它不处理透明度，只读前三个颜色通道。

参数

返回值

• 类型:[number,number,number]
• 语义:返回[r,g,b]数组，每项范围为0到255。

pngToJpg

类型

static pngToJpg(pngData: NSData,quality?: number): NSData

说明

• 把PNG格式的NSData转换为JPEG二进制数据。

• 相比compressImageToJpg，这个方法只接收PNG数据，不做输入类型分派。

参数

返回值

• 类型:NSData
• 语义:返回JPEG格式的NSData二进制数据。

compressImageToJpg

类型

static compressImageToJpg(imageData: string|NSData|UIImage,quality?: number): NSData|undefined

说明

• 把字符串Base64、NSData或UIImage统一压缩成JPEG数据。

• 当你无法确定上游图片类型时优先用它，而不是直接调用pngToJpg。

参数

返回值

• 类型:NSData\|undefined
• 语义:成功返回NSData，失败返回undefined。

imageFromBase64

类型

static imageFromBase64(base64: string,type?: 'png'|'jpg'|'jpeg'|'pdf'): UIImage

说明

• 把Base64字符串转换为UIImage。

• 如果你只需要二进制，不要走这个方法，改用dataFromBase64更直接。

参数

返回值

• 类型:UIImage
• 语义:返回可直接渲染的UIImage对象。

dataFromBase64

类型

static dataFromBase64(base64: string,type?: 'pdf'|'png'|'jpg'|'jpeg'): NSData

说明

• 把Base64文本或DataURL转换为NSData。

• 它会根据type补齐不同MIME前缀，适合统一处理pdf、png、jpeg。

参数

返回值

• 类型:NSData
• 语义:返回解码后的NSData二进制数据。

genFrame

类型

static genFrame(x: number,y: number,width: number,height: number): { x: number; y: number; width: number; height: number }

说明

• 生成{x,y,width,height}结构体供原生接口调用。

参数

返回值

• 类型:{ x: number; y: number; width: number; height: number }
• 语义:返回{ x, y, width, height }矩形对象。

parseWinRect

类型

static parseWinRect(winRect: string): { x: number; y: number; width: number; height: number }

说明

• 把原生窗口矩形字符串解析成标准frame对象。

• 它会把字符串中的花括号和空格清理后再转数值。

参数

返回值

• 类型:{ x: number; y: number; width: number; height: number }
• 语义:返回解析后的{ x, y, width, height }对象。

convertDate

类型

static convertDate(date: string|number|Date|null|undefined): Date|null

说明

• 把字符串、时间戳或Date对象统一转成Date。

• 转换失败返回null，便于调用方显式判断异常数据。

参数

返回值

• 类型:Date|null
• 语义:成功返回Date对象，无法解析时返回null。

convertNsAttrsToFsStats

类型

static convertNsAttrsToFsStats(nsAttrs: Record<string,object|string|number|Date>): {
  dev: number
  ino: number
  mode: number
  nlink: number
  uid: number
  gid: number
  rdev: number
  size: number
  blksize: number
  blocks: number
  atimeMs: number
  mtimeMs: number
  ctimeMs: number
  birthtimeMs: number
  atime: Date
  mtime: Date
  ctime: Date
  birthtime: Date
  _nsFileType?: string
  _nsFileOwnerAccountName?: string
  _nsFileGroupOwnerAccountName?: string
  _nsFileProtectionKey?: string
  _nsFileExtendedAttributes?: object
  isFile: boolean
  isDirectory: boolean
  isSymbolicLink: boolean
  isFIFO: boolean
  isSocket: boolean
  isBlockDevice: boolean
  isCharacterDevice: boolean
}

说明

• 把NSFileManager属性对象映射为接近Node.jsfs.Stats的结构。

参数

返回值

• 类型:{ dev: number; ino: number; mode: number; nlink: number; uid: number; gid: number; rdev: number; size: number; blksize: number; blocks: number; atimeMs: number; mtimeMs: number; ctimeMs: number; birthtimeMs: number; atime: Date; mtime: Date; ctime: Date; birthtime: Date; _nsFileType?: string; _nsFileOwnerAccountName?: string; _nsFileGroupOwnerAccountName?: string; _nsFileProtectionKey?: string; _nsFileExtendedAttributes?: object; isFile: boolean; isDirectory: boolean; isSymbolicLink: boolean; isFIFO: boolean; isSocket: boolean; isBlockDevice: boolean; isCharacterDevice: boolean }
• 语义:返回接近Node.jsfs.Stats格式的文件属性对象。

getFileAttributes

类型

static getFileAttributes(path: string): {
  dev: number
  ino: number
  mode: number
  nlink: number
  uid: number
  gid: number
  rdev: number
  size: number
  blksize: number
  blocks: number
  atimeMs: number
  mtimeMs: number
  ctimeMs: number
  birthtimeMs: number
  atime: Date
  mtime: Date
  ctime: Date
  birthtime: Date
  isFile: boolean
  isDirectory: boolean
  isSymbolicLink: boolean
  isFIFO: boolean
  isSocket: boolean
  isBlockDevice: boolean
  isCharacterDevice: boolean
  path: string
}

说明

• 读取文件属性并返回带path字段的stats对象。

• 相比直接访问NSFileManager，这里已经统一了时间与权限字段格式。

参数

返回值

• 类型:{ dev: number; ino: number; mode: number; nlink: number; uid: number; gid: number; rdev: number; size: number; blksize: number; blocks: number; atimeMs: number; mtimeMs: number; ctimeMs: number; birthtimeMs: number; atime: Date; mtime: Date; ctime: Date; birthtime: Date; isFile: boolean; isDirectory: boolean; isSymbolicLink: boolean; isFIFO: boolean; isSocket: boolean; isBlockDevice: boolean; isCharacterDevice: boolean; path: string }
• 语义:返回带path字段的文件属性对象。

isNSNull

类型

static isNSNull(obj: object): boolean

说明

• 判断对象是否是原生NSNull.new()实例。

• 它用于区分“原生空值对象”和普通null/undefined。

参数

返回值

• 类型:boolean
• 语义:是NSNull实例返回true，否则返回false。

getValidJSON

类型

static getValidJSON(jsonString: string|object,debug?: boolean): object

说明

• 把JSON字符串修复并解析为对象，解析失败返回空对象。

• 相比直接JSON.parse，它会尝试jsonrepair和补括号修复。

参数

返回值

• 类型:object
• 语义:返回解析后的对象，解析失败时返回空对象。

parseHexColor

类型

static parseHexColor(hex: string): { color: string; opacity: number }

说明

• 解析#RRGGBB或#RRGGBBAA并返回颜色与透明度。

• 与hexToRgb不同，它会保留alpha并转成opacity。

参数

返回值

• 类型:{ color: string; opacity: number }
• 语义:返回颜色与透明度对象，其中opacity范围为0到1。

hexColorAlpha

类型

static hexColorAlpha(hex: string,alpha?: number): UIColor

说明

• 把十六进制颜色与透明度组合成UIColor对象。

• 当你已有颜色字符串且只想改透明度时，用它比hexColor更直接。

参数

返回值

• 类型:UIColor
• 语义:返回应用透明度后的UIColor对象。

hexColor

类型

static hexColor(hex: string): UIColor

说明

• 把支持alpha的十六进制字符串转换成UIColor。

参数

返回值

• 类型:UIColor
• 语义:返回解析后的UIColor对象。

genNSURL

类型

static genNSURL(url: string): NSURL

说明

• 当原生接口要求NSURL而你只有字符串时使用它。

参数

返回值

• 类型:NSURL
• 语义:返回可供原生接口直接使用的NSURL对象。

string2data

类型

static string2data(string: string): NSData

说明

• 按UTF-8编码把字符串转成NSData。

• 与dataToString互为逆向转换。

参数

返回值

• 类型:NSData
• 语义:返回UTF-8编码后的NSData数据。

dataToString

类型

static dataToString(data: NSData|string): string

说明

• 把NSData转换成字符串；输入已是字符串时原样返回。

• 这个方法适合处理“可能是字符串也可能是NSData”的混合输入。

参数

返回值

• 类型:string
• 语义:返回UTF-8字符串，输入本身是字符串时原样返回。

stringify

类型

static stringify(object: object): string

说明

• 把对象序列化成带两空格缩进的JSON文本。

• 它用于调试输出，比原生JSON.stringify默认格式更易读。

参数

返回值

• 类型:string
• 语义:返回带两空格缩进的JSON字符串。

xorEncryptDecrypt

类型

static xorEncryptDecrypt(input: string,key: string): string|undefined

说明

• 使用异或算法对字符串做可逆加密或解密。

• 同一key重复调用两次可还原原文。

参数

返回值

• 类型:string|undefined
• 语义:成功返回string，失败返回undefined。

md5FromBase64

类型

static md5FromBase64(base64Str: string): string

说明

• 对Base64表示的原始字节计算MD5摘要。

• 如果你手里是NSData，可先base64Encoding()再调用它。

参数

返回值

• 类型:string
• 语义:返回32位小写MD5摘要字符串。

sha256FromBase64

类型

static sha256FromBase64(base64Str: string): string

说明

• 对Base64字节数据计算SHA-256哈希。

• 与md5FromBase64相比，SHA-256抗碰撞能力更强。

参数

返回值

• 类型:string
• 语义:返回64位十六进制SHA-256摘要字符串。

MD5

类型

static MD5(data: NSData|string): string|undefined

说明

• 计算字符串或NSData的MD5。

• 字符串走CryptoJS.MD5，NSData会先转Base64再计算。

参数

返回值

• 类型:string|undefined
• 语义:成功返回string，失败返回undefined。

parseMNImageURL

类型

static parseMNImageURL(MNImageURL: string): { hash: string; type: 'png'|'jpeg'; ext: 'png'|'jpg' }|undefined

说明

• 解析marginnote4app://markdownimg/...图片地址，提取hash和类型。

• 解析成功会顺带更新MNUtil.imageTypeCache。

参数

返回值

• 类型:{ hash: string; type: 'png'|'jpeg'; ext: 'png'|'jpg' }|undefined
• 语义:成功返回{ hash: string; type: 'png'|'jpeg'; ext: 'png'|'jpg' }，失败返回undefined。

getMNImageURL

类型

static getMNImageURL(hash: string,type?: 'png'|'jpeg'|'jpg'): string

说明

• 根据媒体hash组装MarginNote图片协议URL。

• 若缓存里已有类型，会优先使用缓存类型而不是入参type。

参数

返回值

• 类型:string
• 语义:返回marginnote4app://markdownimg/...格式的图片URL。

getImageDataFromMNImageURL

类型

static getImageDataFromMNImageURL(MNImageURL: string): NSData

说明

• 从MarginNote图片协议URL读取对应媒体二进制。

• 它依赖parseMNImageURL提取hash，再调用MNUtil.getMediaByHash。

参数

返回值

• 类型:NSData
• 语义:返回该图片对应的NSData二进制数据。

getImageFromMNImageURL

类型

static getImageFromMNImageURL(MNImageURL: string): UIImage

说明

• 把MarginNote图片协议URL直接转换为UIImage。

• 相比getImageDataFromMNImageURL，这个方法一步返回可显示图片对象。

参数

返回值

• 类型:UIImage
• 语义:返回可直接显示的UIImage对象。

getImageDataFromURL

类型

static getImageDataFromURL(url: string): NSData|undefined

说明

• 统一处理MarginNote协议URL、DataURL和普通HTTP URL并返回图片数据。

• 当上游URL来源不固定时，优先使用这个入口。

参数

返回值

• 类型:NSData\|undefined
• 语义:成功返回NSData，失败返回undefined。

imageToBase64URL

类型

static imageToBase64URL(imageData: NSData,type?: 'png'|'jpg'|'jpeg'): string

说明

• 把NSData编码为DataURL字符串。

• 当前实现固定返回data:image/png;base64,前缀，即使type传入jpg。

参数

返回值

• 类型:string
• 语义:返回data:image/png;base64,...格式字符串。

imageFromWebURLSync

类型

static imageFromWebURLSync(url: string): UIImage

说明

• 同步下载网络图片并构造UIImage。

• 需要立即得到图片对象时可用，但会阻塞当前线程。

参数

返回值

• 类型:UIImage
• 语义:返回下载并解码后的UIImage对象。

imageDataFromWebURLSync

类型

static imageDataFromWebURLSync(url: string,type?: 'png'|'jpg'|'jpeg',compressionQuality?: number): NSData

说明

• 同步下载网络图片并按指定格式导出数据。

• 当你只需要二进制上传或写文件，这个方法比imageFromWebURLSync更省一步转换。

参数

返回值

• 类型:NSData
• 语义:返回按指定格式导出的图片NSData数据。

NSValue2String

类型

static NSValue2String(v: NSValue): string

说明

• 把NSValue转换为JavaScript可读字符串。

• 这是后续解析CGSize和CGRect的基础步骤。

参数

返回值

• 类型:string
• 语义:返回可读的几何字符串，常见格式为{x,y}或{w,h}。

NSValue2CGSize

类型

static NSValue2CGSize(v: NSValue): { width: number; height: number }

说明

• 把NSValue解析为{ width, height }。

• 与NSValue2CGRect相比，它只处理尺寸不处理坐标。

参数

返回值

• 类型:{ width: number; height: number }
• 语义:返回{ width, height }尺寸对象。

NSValue2CGRect

类型

static NSValue2CGRect(v: NSValue): { x: number; y: number; height: number; width: number }

说明

• 把NSValue解析为{ x, y, height, width }对象。

• 适合把原生几何值喂给纯JS布局逻辑。

参数

返回值

• 类型:{ x: number; y: number; height: number; width: number }
• 语义:返回{ x, y, height, width }矩形对象。

CGRectString2CGRect

类型

static CGRectString2CGRect(str: string): { x: number; y: number; height: number; width: number }

说明

• 把CGRect字符串解析成对象结构。

• 当你已经拿到字符串形态而不是NSValue时用它。

参数

返回值

• 类型:{ x: number; y: number; height: number; width: number }
• 语义:返回解析后的{ x, y, height, width }对象。

stringFromCharCode

类型

static stringFromCharCode(char: number|string): string

说明

• 把数字或数字字符串转换成单字符。

• 适用于处理协议里以码点存储的字符。

参数

返回值

• 类型:string
• 语义:返回输入码点对应的单字符字符串。

fileTypeFromBase64URL

类型

static fileTypeFromBase64URL(content: string): string|undefined

说明

• 根据DataURL前缀快速判断文件类型。

• 前缀是octet-stream时会退回字节头判断。

参数

返回值

• 类型:string|undefined
• 语义:成功返回string，失败返回undefined。

hexHeaderFromData

类型

static hexHeaderFromData(data: NSData): string|undefined

说明

• 读取二进制前16字节并输出十六进制文件头。

参数

返回值

• 类型:string|undefined
• 语义:成功返回string，失败返回undefined。

getFileTypeFromBase64

类型

static getFileTypeFromBase64(base64: string): string

说明

• 把Base64先转数据再按文件头识别类型。

• 当MIME前缀缺失时，这是比字符串猜测更可靠的路径。

参数

返回值

• 类型:string
• 语义:返回根据文件头识别出的文件类型扩展名。

getFileTypeFromhexHeader

类型

static getFileTypeFromhexHeader(hexHeader: string): string

说明

• 按文件头前缀匹配常见格式，如jpg、png、pdf、zip。

• 它按前缀长度从长到短匹配，降低误判。

参数

返回值

• 类型:string
• 语义:返回匹配到的文件类型扩展名。

getFileTypeFromData

类型

static getFileTypeFromData(data: NSData): string

说明

• 直接从NSData识别文件类型。

参数

返回值

• 类型:string
• 语义:返回从二进制头部识别出的文件类型扩展名。

getFileType

类型

static getFileType(data: NSData|string): string

说明

• 统一入口：同时支持NSData和字符串两类输入。

• 字符串输入会先判断是否DataURL，再决定走哪条识别路径。

参数

返回值

• 类型:string
• 语义:返回自动判定后的文件类型扩展名。

base64ToUint8Array

类型

static base64ToUint8Array(base64Str: string): Uint8Array

说明

• 把Base64文本解码为Uint8Array，并自动清理前缀和空白字符。

• 在插件返回值含换行时，这个方法比原生atob更稳定。

参数

返回值

• 类型:Uint8Array
• 语义:返回Base64解码后的Uint8Array。

NSDataToUint8Array

类型

static NSDataToUint8Array(data: NSData): Uint8Array

说明

• 把NSData转换成Uint8Array。

• 处理流程与base64ToUint8Array一致，只是输入源改为NSData。

参数

返回值

• 类型:Uint8Array
• 语义:返回与输入NSData等价的Uint8Array数据。

uint8ArrayToBase64

类型

static uint8ArrayToBase64(input: Uint8Array|ArrayBuffer|number[]): string

说明

• 把Uint8Array、ArrayBuffer或数值数组编码成Base64。

• 当你需要替代浏览器btoa处理二进制时，优先使用它。

参数

返回值

• 类型:string
• 语义:返回Base64编码后的字符串。

changePngColor

类型

static changePngColor(bytes: Uint8Array,hexColor: string,sourceRgb?: [number,number,number]): string|null

说明

• 修改索引色PNG的调色板颜色并返回新的DataURL。

• 它只处理含PLTE块的PNG，不支持真彩PNG逐像素替换。

参数

返回值

• 类型:string|null
• 语义:成功返回调色后的DataURL字符串，无法处理时返回null。

getDotBase64WithColor

类型

static getDotBase64WithColor(hexColor: string): string|null

说明

• 把内置小圆点模板图替换成目标颜色并返回Base64 DataURL。

• 适合快速生成带主题色的标记点素材。

参数

返回值

• 类型:string|null
• 语义:成功返回着色后的DataURL字符串，失败返回null。

getDotImageWithColor

类型

static getDotImageWithColor(hexColor: string): UIImage|undefined

说明

• 基于getDotBase64WithColor直接得到UIImage。

• 当你最终需要的是可绘制图片对象，而不是字符串时使用它。

参数

返回值

• 类型:UIImage|undefined
• 语义:成功返回UIImage，失败返回undefined。

实例成员(Instance members)

无实例成员。

覆盖补全

convertImageBase64ToPdfBase64

类型

static async convertImageBase64ToPdfBase64(pngBase64: string): Promise<string|undefined>

说明

将Base64编码的图片转换为Base64编码的PDF。

参数

返回值

• 类型:Promise<string|undefined>
• 语义:成功返回Base64编码的PDF，失败返回undefined。

convertImageDataToPdfData

类型

static async convertImageDataToPdfData(imageData: NSData): Promise<NSData|undefined>

说明

将图片数据转换为PDF数据。

参数

返回值

• 类型:Promise<NSData|undefined>
• 语义:成功返回PDF数据，失败返回undefined。

imageFromWebURL

类型

static async imageFromWebURL(url: string): Promise<UIImage|undefined>

说明

从网络URL下载图片并转换为UIImage。

参数

返回值

• 类型:Promise<UIImage|undefined>
• 语义:成功返回UIImage对象，失败返回undefined。

imageDataFromWebURL

类型

static async imageDataFromWebURL(url: string): Promise<NSData|undefined>

说明

从网络URL下载图片并返回二进制数据。

参数

返回值

• 类型:Promise<NSData|undefined>
• 语义:成功返回图片数据，失败返回undefined。

extractPDFPage

类型

static async extractPDFPage(path: string,targetPageIndices: number[]): Promise<NSData|undefined>

说明

从PDF中提取指定页并返回新的PDF数据。

参数

返回值

• 类型:Promise<NSData|undefined>
• 语义:成功返回提取的PDF数据，失败返回undefined。