cImage - 图片数据互转类

概述

cImage 提供了 Byte() ↔ Base64 ↔ StdPicture 三种图片数据格式的互转功能，采用链式调用设计，一行代码即可完成复杂转换。

通过 VBMAN.Image 全局静态实例直接使用，无需手动实例化。

核心特性

链式调用: 流畅的 API 设计，一行代码完成转换 + 输出
三种格式互转: 字节数组、Base64 字符串、StdPicture 对象之间自由转换
Data URI 支持: 自动解析 data:image/jpeg;base64,... 格式
MIME 类型检测: 通过文件魔数自动识别 JPEG/PNG/GIF/BMP/WebP/ICO
控件直赋: ShowTo 方法直接将图片显示到 Image/PictureBox 控件
默认成员: Data 方法为默认成员，支持 VBMAN.Image.(base64Str) 简写

调用方式

' 全局静态实例（推荐）
VBMAN.Image.Data(base64Str).ReturnPicture

' 简写法（利用默认成员）
VBMAN.Image.(base64Str).ReturnPicture

' 独立实例
Dim img As New cImage
Set Image1.Picture = img.Data(bytesArr).ReturnPicture

方法总览

链式入口方法

方法	说明	返回
Data	设置数据源（默认成员）	`cImage` (Me)

链式辅助方法

方法	说明	返回
SetMimeType	手动设置 MIME 类型	`cImage` (Me)
ShowTo	将图片显示到目标控件	`cImage` (Me)

输出方法（终结方法）

方法	说明	返回
ReturnBytes	输出为字节数组	`Byte()`
ReturnBase64	输出为 Base64 字符串	`String`
ReturnPicture	输出为 StdPicture 对象	`StdPicture`
ReturnDataUri	输出为 Data URI 字符串	`String`
ReturnMimeType	返回检测到的 MIME 类型	`String`

检查方法

方法	说明	返回
IsValid	检查数据是否有效	`Boolean`

方法详解

Data

链式调用入口，接受三种数据类型。为默认成员，支持简写 VBMAN.Image.(data)。

Public Function Data(ByVal vData As Variant) As cImage

参数:

参数名	类型	说明
`vData`	Variant	数据源，支持 Byte() 数组、Base64 字符串、StdPicture 对象

支持的输入类型:

类型	判断依据	示例
Byte() 数组	`VarType = vbArray Or vbByte`	读取图片文件的字节数据
Base64 字符串	`VarType = vbString`	API 返回的头像 Base64
Data URI 字符串	以 `data:` 开头	`data:image/png;base64,...`
StdPicture 对象	`IsObject(vData)`	`Image1.Picture`

Data URI 自动解析:

传入 data:image/jpeg;base64,xxxxx 格式的字符串时，自动提取 MIME 类型并剥离前缀，仅保留纯 Base64 部分。

返回: cImage (Me)，支持链式调用

示例:

' 从 Base64 字符串
VBMAN.Image.Data("/9j/4AAQ...").ReturnPicture

' 从字节数组
Dim bytes() As Byte
bytes = VBMAN.FileEx.OpenFile("photo.jpg", "R").ReadData.ReturnBytes
VBMAN.FileEx.CloseFile
VBMAN.Image.Data(bytes).ReturnBase64

' 从 StdPicture
VBMAN.Image.Data(Image1.Picture).ReturnBase64

' 简写法（利用默认成员）
VBMAN.Image.("/9j/4AAQ...").ReturnPicture

' Data URI 格式自动解析
VBMAN.Image.("data:image/png;base64,iVBOR...").ReturnPicture

SetMimeType

手动设置 MIME 类型，用于覆盖自动检测结果或补充无法检测的格式。

Public Function SetMimeType(ByVal MimeType As String) As cImage

参数:

参数名	类型	说明
`MimeType`	String	MIME 类型，如 `"image/jpeg"`、`"image/png"`

返回: cImage (Me)，支持链式调用

示例:

' 手动指定 MIME 类型（影响 ReturnDataUri 输出）
VBMAN.Image.Data(bytes).SetMimeType("image/png").ReturnDataUri

' 从 StdPicture 获取时无法自动检测格式，需手动指定
VBMAN.Image.Data(Image1.Picture).SetMimeType("image/bmp").ReturnDataUri

ShowTo

将图片直接显示到目标控件，是最便捷的显示方式。

Public Function ShowTo(ByVal Target As Object) As cImage

参数:

参数名	类型	说明
`Target`	Object	任何拥有 `Picture` 属性的控件对象（Image、PictureBox 等）

返回: cImage (Me)，支持链式调用

示例:

' 传统写法 - 需要 Set 关键字
Set Image1.Picture = VBMAN.Image.Data(base64Str).ReturnPicture

' 简写法 - 一行搞定
VBMAN.Image.(base64Str).ShowTo Image1

' 链式显示后再获取 Base64
Dim b64 As String
b64 = VBMAN.Image.(base64Str).ShowTo(Image1).ReturnBase64

' 显示到 PictureBox
VBMAN.Image.(bytesArr).ShowTo Picture1

' 从 StdPicture 显示到另一个控件
VBMAN.Image.Data(Picture1.Picture).ShowTo Image2

ReturnBytes

将图片数据转换为字节数组输出。

Public Function ReturnBytes() As Byte()

返回: Byte() 字节数组

示例:

' Base64 → 字节数组
Dim bytes() As Byte
bytes = VBMAN.Image.Data(base64Str).ReturnBytes

' StdPicture → 字节数组（可用于保存图片）
Dim picBytes() As Byte
picBytes = VBMAN.Image.Data(Image1.Picture).ReturnBytes

' 将字节数组写入文件
VBMAN.FileEx.SetBufferBytes(bytes).SaveData "C:\output.jpg"

ReturnBase64

将图片数据转换为 Base64 字符串输出。

Public Function ReturnBase64() As String

返回: String - 纯 Base64 字符串（不含 data: 前缀）

示例:

' 字节数组 → Base64
Dim b64 As String
b64 = VBMAN.Image.Data(bytes).ReturnBase64

' StdPicture → Base64
Dim picB64 As String
picB64 = VBMAN.Image.Data(Image1.Picture).ReturnBase64

' 用于 API 请求
Dim json As New cJson
json("avatar") = VBMAN.Image.Data(Image1.Picture).ReturnBase64
Dim resp As String
resp = VBMAN.HttpClient.SetUrl("/api/upload").SetBody(json.Encode).Post

ReturnPicture

将图片数据转换为 StdPicture 对象输出，可直接赋给控件的 Picture 属性。

Public Function ReturnPicture() As StdPicture

返回: StdPicture 对象

示例:

' Base64 → StdPicture
Set Image1.Picture = VBMAN.Image.Data(base64Str).ReturnPicture

' 字节数组 → StdPicture
Set Image1.Picture = VBMAN.Image.Data(bytes).ReturnPicture

' Data URI → StdPicture
Set Image1.Picture = VBMAN.Image.("data:image/png;base64,iVBOR...").ReturnPicture

ReturnDataUri

将图片数据转换为 Data URI 格式字符串输出，适合直接嵌入 HTML/CSS。

Public Function ReturnDataUri(Optional ByVal MimeType As String) As String

参数:

参数名	类型	必填	说明
`MimeType`	String	否	MIME 类型，省略时使用自动检测或默认 `image/jpeg`

返回: String - Data URI 格式字符串，如 data:image/png;base64,iVBORw0KGgo...

示例:

' 自动检测 MIME 类型
Dim uri As String
uri = VBMAN.Image.Data(bytes).ReturnDataUri
' 输出: data:image/jpeg;base64,/9j/4AAQ...

' 手动指定 MIME 类型
uri = VBMAN.Image.Data(bytes).SetMimeType("image/png").ReturnDataUri
' 输出: data:image/png;base64,iVBORw0KGgo...

' 嵌入 HTML
Dim html As String
html = "<img src='" & VBMAN.Image.Data(bytes).ReturnDataUri & "'>"
WebBrowser1.Document.Write html

' 从 Base64 生成 Data URI
uri = VBMAN.Image.Data(base64Str).ReturnDataUri("image/png")

ReturnMimeType

返回自动检测到的图片 MIME 类型。

Public Function ReturnMimeType() As String

返回: String - MIME 类型字符串

支持的检测格式:

格式	魔数 (Hex)	MIME 类型
JPEG	`FF D8 FF`	`image/jpeg`
PNG	`89 50 4E 47`	`image/png`
GIF	`47 49 46`	`image/gif`
BMP	`42 4D`	`image/bmp`
WebP	`52 49 46 46 ... 57 45 42 50`	`image/webp`
ICO	`00 00 01 00`	`image/x-icon`

示例:

' 检测图片类型
Dim mime As String
mime = VBMAN.Image.Data(bytes).ReturnMimeType
Debug.Print mime  ' 输出: image/png

' 判断类型后分别处理
Select Case mime
    Case "image/jpeg"
        ' JPEG 处理逻辑
    Case "image/png"
        ' PNG 处理逻辑
    Case Else
        ' 其他格式
End Select

IsValid

检查数据源是否有效（是否已通过 Data 方法设置了数据）。

Public Function IsValid() As Boolean

返回: Boolean - 数据有效时返回 True

示例:

Dim img As New cImage
img.Data(base64Str)

If img.IsValid Then
    Set Image1.Picture = img.ReturnPicture
Else
    MsgBox "图片数据无效！"
End If

综合示例

示例1: API 头像显示

从 API 获取用户头像 Base64，直接显示到 Image 控件：

Private Sub LoadUserAvatar(userId As Long)
    ' 从 API 获取头像 Base64
    Dim resp As String
    resp = VBMAN.HttpClient.SetUrl("/api/user/" & userId & "/avatar").Get
    
    ' 解析 JSON 获取 avatar 字段
    Dim json As cJson
    Set json = VBMAN.Json.Decode(resp)
    Dim avatarB64 As String
    avatarB64 = json("avatar")
    
    ' 显示到 Image 控件（一行搞定）
    VBMAN.Image.(avatarB64).ShowTo Image1
End Sub

示例2: 图片上传到服务器

将本地图片转为 Base64 后上传到 API：

Private Sub UploadImage(filePath As String)
    ' 读取图片文件为字节数组
    VBMAN.FileEx.OpenFile filePath, "R"
    Dim bytes() As Byte
    bytes = VBMAN.FileEx.ReadData.ReturnBytes
    VBMAN.FileEx.CloseFile
    
    ' 转为 Base64 并检测类型
    Dim img As cImage
    Set img = VBMAN.Image.Data(bytes)
    Dim b64 As String
    b64 = img.ReturnBase64
    Dim mime As String
    mime = img.ReturnMimeType
    
    ' 构建请求 JSON
    Dim json As New cJson
    json("image") = b64
    json("mime_type") = mime
    
    ' 上传
    Dim resp As String
    resp = VBMAN.HttpClient _
        .SetUrl("/api/upload") _
        .SetBody(json.Encode) _
        .Post
End Sub

示例3: 图片 Data URI 嵌入 HTML

将图片转为 Data URI 嵌入 WebBrowser 页面：

Private Sub ShowEmbeddedImage(filePath As String)
    ' 读取图片
    VBMAN.FileEx.OpenFile filePath, "R"
    Dim bytes() As Byte
    bytes = VBMAN.FileEx.ReadData.ReturnBytes
    VBMAN.FileEx.CloseFile
    
    ' 获取 Data URI
    Dim dataUri As String
    dataUri = VBMAN.Image.Data(bytes).ReturnDataUri
    
    ' 嵌入 HTML
    Dim html As String
    html = "<html><body>" & _
           "<img src='" & dataUri & "' style='max-width:300px'>" & _
           "</body></html>"
    WebBrowser1.Document.Write html
End Sub

示例4: 图片格式互转全流程

完整演示三种格式之间的互转：

Private Sub TestImageConversion()
    Dim img As cImage
    
    ' 1. 字节数组 → Base64 + StdPicture + Data URI
    Dim bytes() As Byte
    bytes = VBMAN.FileEx.OpenFile("C:\photo.jpg", "R").ReadData.ReturnBytes
    VBMAN.FileEx.CloseFile
    
    Set img = VBMAN.Image.Data(bytes)
    Debug.Print "MIME: " & img.ReturnMimeType        ' image/jpeg
    Debug.Print "Base64长度: " & Len(img.ReturnBase64)
    Set Image1.Picture = img.ReturnPicture
    
    ' 2. Base64 → 字节数组 + StdPicture
    Dim b64 As String
    b64 = img.ReturnBase64
    
    Set img = VBMAN.Image.Data(b64)
    Dim newBytes() As Byte
    newBytes = img.ReturnBytes
    Set Image2.Picture = img.ReturnPicture
    
    ' 3. StdPicture → Base64 + 字节数组
    Set img = VBMAN.Image.Data(Image2.Picture)
    Dim picB64 As String
    picB64 = img.SetMimeType("image/bmp").ReturnBase64
    Dim picBytes() As Byte
    picBytes = img.ReturnBytes
    
    Debug.Print "转换完成！"
End Sub

示例5: 批量头像显示

从数据库批量获取头像 Base64 并显示到多个控件：

Private Sub LoadAllAvatars()
    ' 查询所有用户头像
    VBMAN.Db.Sql("SELECT id, avatar FROM users").Fetch
    
    Dim i As Long
    For i = 0 To VBMAN.Db.RowCount - 1
        VBMAN.Db.Row i
        
        ' 根据用户 ID 找到对应的 Image 控件
        Dim ctrlName As String
        ctrlName = "imgAvatar" & VBMAN.Db.Field("id")
        
        ' 一行代码显示头像
        VBMAN.Image.(VBMAN.Db.Field("avatar")).ShowTo Me.Controls(ctrlName)
    Next i
End Sub

转换流程图

                    ┌─────────────┐
                    │   Data()    │ ← 链式入口（默认成员）
                    └─────────────┘
                          │
          ┌───────────────┼───────────────┐
          │               │               │
    Byte() 数组      Base64 字符串    StdPicture
          │               │               │
          └───────────────┼───────────────┘
                          │
              ┌───────────┼───────────┐
              │           │           │
        ReturnBytes  ReturnBase64  ReturnPicture
              │           │           │
              │      ReturnDataUri   ShowTo(控件)
              │           │           │
              └───────────┼───────────┘
                          │
                    ┌─────────────┐
                    │ ReturnMimeType │ ← MIME 类型检测
                    └─────────────┘

注意事项

StdPicture → 字节数组: 内部通过 SavePicture 保存临时文件再读取，输出为 BMP 格式
MIME 类型检测: 仅对字节数组输入有效，Base64 和 StdPicture 输入需手动指定
Data URI 格式: ReturnBase64 返回纯 Base64，ReturnDataUri 返回带 data: 前缀的完整格式
GDI+ 初始化: 类内部自动管理 GDI+ 生命周期，首次使用时初始化，类销毁时释放
线程安全: VBMAN.Image 是全局共享实例，如需多个独立转换任务，应创建 New cImage

最佳实践

显示优先用 ShowTo: 比 Set Image1.Picture = ...ReturnPicture 更简洁
简写法: VBMAN.Image.(base64Str) 比完整写法更直观
API 场景: 接收 Base64 图片 → ShowTo 显示；发送图片 → ReturnBase64 编码
HTML 嵌入: 使用 ReturnDataUri 生成可直接嵌入的格式
格式确认: 上传图片时用 ReturnMimeType 获取类型，随请求一起发送
独立实例: 多线程或批量转换场景应 New cImage 创建独立实例

链式CURD

AES

Hash

HMAC

cImage - 图片数据互转类

概述

核心特性

调用方式

方法总览

链式入口方法

链式辅助方法

输出方法（终结方法）

检查方法

方法详解

Data

SetMimeType

ShowTo

ReturnBytes

ReturnBase64

ReturnPicture

ReturnDataUri

ReturnMimeType

IsValid

综合示例

示例1: API 头像显示

示例2: 图片上传到服务器

示例3: 图片 Data URI 嵌入 HTML

示例4: 图片格式互转全流程

示例5: 批量头像显示

转换流程图

注意事项

最佳实践

cImage - 图片数据互转类 ​

概述 ​

核心特性 ​

调用方式 ​

方法总览 ​

链式入口方法 ​

链式辅助方法 ​

输出方法（终结方法） ​

检查方法 ​

方法详解 ​

Data ​

SetMimeType ​

ShowTo ​

ReturnBytes ​

ReturnBase64 ​

ReturnPicture ​

ReturnDataUri ​

ReturnMimeType ​

IsValid ​

综合示例 ​

示例1: API 头像显示 ​

示例2: 图片上传到服务器 ​

示例3: 图片 Data URI 嵌入 HTML ​

示例4: 图片格式互转全流程 ​

示例5: 批量头像显示 ​

转换流程图 ​

注意事项 ​

最佳实践 ​

cImage - 图片数据互转类

概述

核心特性

调用方式

方法总览

链式入口方法

链式辅助方法

输出方法（终结方法）

检查方法

方法详解

Data

SetMimeType

ShowTo

ReturnBytes

ReturnBase64

ReturnPicture

ReturnDataUri

ReturnMimeType

IsValid

综合示例

示例1: API 头像显示

示例2: 图片上传到服务器

示例3: 图片 Data URI 嵌入 HTML

示例4: 图片格式互转全流程

示例5: 批量头像显示

转换流程图

注意事项

最佳实践