UIImage
UIImage 类表示一个图像对象，可用于加载、编码、转换与显示。它支持从文件路径、二进制数据或 Base64 字符串中创建图像，并提供多种格式转换方法（PNG/JPEG）。
UIImage 可直接用于 Image 组件显示，也可与 Data 类配合用于图像存储、上传、加密等操作。
概述
UIImage 是脚本环境中处理图像的核心类，常用于以下场景：
- 从本地文件、二进制数据或 Base64 字符串中加载图像
- 获取图像的像素宽高
- 转换图像格式（如 PNG、JPEG）
- 生成 Base64 字符串
- 在 UI 中通过
<Image> 组件显示图像
- 支持浅色/深色模式切换的动态图像显示
属性
width: number
图像的宽度（单位：像素）。
1const image = UIImage.fromFile("/path/to/image.png")
2console.log(image?.width)
height: number
图像的高度（单位：像素）。
1const image = UIImage.fromFile("/path/to/image.png")
2console.log(image?.height)
实例方法
toJPEGData(compressionQuality?: number): Data | null
将图像转换为 JPEG 格式的二进制数据。
-
参数：
compressionQuality（可选）: 压缩质量，范围为 0 到 1，默认值为 1（无压缩）。
-
返回值：
- 返回
Data 实例；如果转换失败，返回 null。
示例：
1const image = UIImage.fromFile("/path/to/photo.png")
2const jpegData = image?.toJPEGData(0.8)
3if (jpegData) {
4 console.log(`JPEG 数据大小: ${jpegData.length} 字节`)
5}
toPNGData(): Data | null
将图像转换为 PNG 格式的二进制数据。
-
返回值：
- 返回
Data 实例；如果转换失败，返回 null。
示例：
1const image = UIImage.fromFile("/path/to/logo.png")
2const pngData = image?.toPNGData()
toJPEGBase64String(compressionQuality?: number): string | null
将图像转换为 Base64 编码的 JPEG 字符串。
-
参数：
compressionQuality（可选）: JPEG 压缩质量（0–1，默认 1）。
-
返回值：
- 返回 Base64 编码的字符串；如果转换失败，返回
null。
示例：
1const image = UIImage.fromFile("/path/to/avatar.jpg")
2const base64 = image?.toJPEGBase64String(0.7)
3if (base64) {
4 console.log(base64.slice(0, 100) + "...")
5}
toPNGBase64String(): string | null
将图像转换为 Base64 编码的 PNG 字符串。
-
返回值：
- 返回 Base64 编码的字符串；如果转换失败，返回
null。
示例：
1const image = UIImage.fromFile("/path/to/icon.png")
2const base64 = image?.toPNGBase64String()
静态方法
UIImage.fromFile(filePath: string): UIImage | null
从文件路径加载图像。
-
参数：
filePath: 图像文件的绝对路径（支持 PNG、JPG、JPEG）。
-
返回值：
- 成功返回
UIImage 实例，失败返回 null。
示例：
1const image = UIImage.fromFile("/path/to/images/sample.jpg")
2if (image) {
3 console.log(`宽度: ${image.width}, 高度: ${image.height}`)
4}
UIImage.fromData(data: Data): UIImage | null
通过 Data 二进制数据创建图像。
-
参数：
data: 包含 PNG 或 JPEG 数据的 Data 实例。
-
返回值：
- 成功返回
UIImage 实例，失败返回 null。
示例：
1const fileData = Data.fromFile("/path/to/picture.png")
2const image = fileData ? UIImage.fromData(fileData) : null
UIImage.fromBase64String(base64String: string): UIImage | null
通过 Base64 字符串创建图像。
-
参数：
base64String: 图像的 Base64 编码字符串。
-
返回值：
- 成功返回
UIImage 实例，失败返回 null。
示例：
1const base64 = "iVBORw0KGgoAAAANSUhEUgAA..."
2const image = UIImage.fromBase64String(base64)
在 UI 中使用 UIImage
UIImage 可以直接用于 <Image> 组件中显示图像。
组件定义
1declare const Image: FunctionComponent<UIImageProps>
属性定义
1type UIImageProps = {
2 image: UIImage | DynamicImageSource<UIImage>
3}
类型定义
1type DynamicImageSource<T> = {
2 light: T
3 dark: T
4}
用于浅色和深色模式下的动态图像切换。
示例：显示单张图片
1const image = UIImage.fromFile("/path/to/avatar.png")
2<Image image={image} />
示例：适配浅色与深色模式
1const lightImage = UIImage.fromFile("/path/to/light-logo.png")
2const darkImage = UIImage.fromFile("/path/to/dark-logo.png")
3
4<Image image={{ light: lightImage, dark: darkImage }} />
常见用法示例
1. 图像转 Base64
1const image = UIImage.fromFile("/path/to/image.png")
2const base64 = image?.toPNGBase64String()
2. 压缩为 JPEG 数据并保存
1const image = UIImage.fromFile("/path/to/photo.jpg")
2const jpegData = image?.toJPEGData(0.6)
3if (jpegData) {
4 // 写入到本地文件
5}
3. 从 Base64 字符串还原图片并显示
1const base64 = "iVBORw0KGgoAAAANSUhEUgAA..."
2const image = UIImage.fromBase64String(base64)
3<Image image={image} />
4. 将 PNG 图片转换为 JPEG 并上传
1const image = UIImage.fromFile("/path/to/logo.png")
2const jpegData = image?.toJPEGData(0.8)
3if (jpegData) {
4 const response = await fetch("https://example.com/upload", {
5 method: "POST",
6 body: jpegData.toUint8Array()
7 })
8}
总结
UIImage 是 Scripting 脚本环境中图像操作的核心类，具备以下特性：
- 从文件、二进制或 Base64 加载图像
- 读取图像宽高信息
- 支持 PNG/JPEG 格式转换与压缩
- 提供 Base64 编码输出
- 可直接在 UI 中使用，支持浅色/深色模式自动切换
