显示图片
这一篇讲怎么用 UIImage 和 UIImageView 显示图片:打包在 App 里的图、系统图标、网络图片、本地文件里的图、动图,以及图片怎么摆、怎么上色、怎么拉伸。每个方法和属性的细节在这两个类的参考页。
推荐的做法
- 显示一张图分两步:先取图,再赋给图片视图。 图片视图不会自己加载图片。取图的四个方法取不到时都返回
null,不抛异常,所以取图之后先判空。 - 图片作为普通文件放在项目的
assets/里,用UIImage.imageNamed('JS/assets/名字')取。命令行工具生成的工程没有往 Asset Catalog 里添加图片的途径。 - 每个图片视图都明确写
contentMode:照片、封面用'scaleAspectFill'加clipsToBounds = true,图标用'scaleAspectFit'。默认的'scaleToFill'会把图片拉伸变形。 - 用约束给图片视图确定大小(固定的宽高,或者固定的宽度加宽高比),不依赖图片的尺寸。网络图片在下载完成之前没有尺寸,不这样做时视图的大小会在图片到达时变化。
- 从网络下载的图片都先
prepareForDisplay()再显示,把解码放到后台。动图也一样。小图标不需要。
第一个图片
从空白 App 开始,在屏幕正中显示一个粉色的星形图标。图标来自 SF Symbols:iOS 自带的图标库,有上千个图标,按名字取,不需要自己准备图片文件。
application.addEventListener('sceneconnect', (e) => {
// 建窗口和页面。每个 App 都要有这几行
const win = new UIWindow(e.scene);
const page = new UIViewController();
page.view.backgroundColor = 'systemBackground';
win.rootViewController = page;
win.makeKeyAndVisible();
// 1. 取一张图。'star.fill' 是 SF Symbols 里的图标名
const star = UIImage.systemImageNamed('star.fill');
// 2. 创建图片视图,把图交给它
const iv = new UIImageView();
iv.image = star;
// 3. 图片比视图小:保持宽高比放大到刚好放进视图
iv.contentMode = 'scaleAspectFit';
// 4. 给图标上色
iv.tintColor = 'systemPink';
// 5. 放到页面上:位置在正中,宽高各 120 pt
iv.translatesAutoresizingMaskIntoConstraints = false;
page.view.addSubview(iv);
NSLayoutConstraint.activateConstraints([
iv.centerXAnchor.constraintEqualToAnchor(page.view.centerXAnchor),
iv.centerYAnchor.constraintEqualToAnchor(page.view.centerYAnchor),
iv.widthAnchor.constraintEqualToConstant(120),
iv.heightAnchor.constraintEqualToConstant(120),
]);
});效果:屏幕正中出现一个粉色的实心五角星,位于 120 × 120 pt 的区域内,没有变形。
这段代码没有作为一个整体在模拟器运行过。其中用到的每个 API 都在验收用例里运行过。
五步分别是:取图、创建视图并赋图、定摆法、上色、放到页面上。下面的每种用法都是在这五步上改,沿用这里的 page 和 iv。单独试某一节时,先写这几行:
const page = new UIViewController();
const iv = new UIImageView();
page.view.addSubview(iv);显示打包在 App 里的图
图片文件放在项目根目录的 assets/ 里,构建时被放进 App 包的 JS/assets/。
const dot = UIImage.imageNamed('JS/assets/dot');
if (dot) {
iv.image = dot;
console.log(dot.size.width, dot.size.height, dot.scale);
}效果
- 图片视图显示项目
assets/目录里的dot图片。 - 控制台输出
10 10 3(在 @3x 屏幕的设备上)。
名字可以不写扩展名。imageNamed() 不会到子目录里搜索,图片在 JS/assets/ 里时只写 'dot' 找不到。目录里有 dot.png、dot@2x.png、dot@3x.png 三个文件时,系统按屏幕选其中一个。完整的规则见 imageNamed()。
显示系统图标
iv.image = UIImage.systemImageNamed('heart.fill');
iv.contentMode = 'scaleAspectFit';效果:图片视图显示一个实心的心形图标,颜色是图片视图的 tintColor。未在模拟器验证。
全部图标名可以在 Apple 提供的 SF Symbols 应用里查。名字不存在时返回 null。
给图标上色
iv.image = UIImage.systemImageNamed('star.fill');
iv.tintColor = '#FF3B30';
console.log(iv.tintColor);效果
- 星形显示为红色。未在模拟器验证。
- 控制台输出
#FF3B30。写入的颜色字符串原样读回。
tintColor 只对模板图起作用:图片里不透明的部分全部显示成 tintColor。SF Symbols 的图标在图片视图里按模板图处理。自己的图片默认显示原来的颜色,要让它也按 tintColor 上色,先转成模板图:
const mark = UIImage.imageNamed('JS/assets/dot');
if (mark) {
iv.image = mark.imageWithRenderingMode('alwaysTemplate');
iv.tintColor = 'systemGreen';
}效果:图片里不透明的部分全部显示为绿色,原来的颜色不显示。未在模拟器验证。
规则见渲染模式和 tintColor。
显示从网络下载的图
async function showRemoteImage() {
const res = await fetch('https://picsum.photos/200/200');
const blob = await res.blob();
const img = UIImage.imageWithData(blob);
if (img === null) {
console.log('下载到的不是图片');
return;
}
// 在后台解码,解完再显示
const ready = await img.prepareForDisplay();
iv.image = ready ?? img;
console.log(img.size.width, img.size.height, img.scale);
}
showRemoteImage();效果
- 下载完成后,图片视图显示这张图。
- 控制台输出
200 200 1。
这是显示网络图片的标准写法。三步分别是:用 fetch 下载并取得 Blob,用 imageWithData() 把 Blob 变成图片,用 prepareForDisplay() 在后台解码。
- 下载要用
res.blob(),不要用res.arrayBuffer():imageWithData()只接受Blob。 - 下载到的内容不是图片时(比如服务器返回了一个错误页面),
imageWithData()返回null,不抛异常。网络不通时fetch会拒绝,要用try…catch处理,见fetch。 prepareForDisplay()的结果可能是null,这时退回使用原图。- 下载期间图片视图是空的。可以先给它设一个
backgroundColor占位。 imageWithData()得到的图片scale是 1:200 × 200 像素的图,size是 200 × 200 pt,在 @3x 屏幕上会被放大显示。要按 @2x 或 @3x 的图处理,传{ scale }。- 下载到的是动图时写法不变:
prepareForDisplay()会把所有帧都解码,赋给image之后自动播放。
缓存下载过的图
运行时不提供图片缓存。imageWithData() 每次都从字节生成一个新的图片对象。需要缓存时有两种做法:
- 在 App 运行期间重复使用:把取到的
UIImage对象保存在一个Map里,按地址查找。 - 下次启动仍然可用:把下载到的内容写进缓存目录,以后从文件读取,见下一节。
显示保存在本地文件里的图
图片先保存成文件,以后从文件读取。文件的读写见文件读写。
async function showCachedImage() {
const fs = application.fileSystem;
const path = fs.caches + '/cover.jpg';
if (!(await fs.exists(path))) {
const res = await fetch('https://picsum.photos/200/200');
await fs.writeBytes(path, await res.blob());
}
const img = UIImage.imageWithContentsOfFile(path);
if (img) {
iv.image = img;
}
}
showCachedImage();效果:第一次运行时下载图片并保存到缓存目录,然后显示。以后运行时直接从文件读取并显示,不再下载。这个例子未在模拟器验证。
imageWithContentsOfFile() 的参数是完整的绝对路径。文件不存在或不是图片时返回 null。
显示动图
假设项目的 assets/ 目录里有一个 anim.gif,4 帧,每帧 0.1 秒,一直循环。
const loading = UIImage.imageNamed('JS/assets/anim.gif');
if (loading !== null) {
iv.image = loading;
console.log(loading.images === null ? 0 : loading.images.length);
console.log(loading.duration.toFixed(1), loading.loopCount);
}效果
- 图片视图里的图开始播放,一直循环。
- 控制台输出
4,然后输出0.4 Infinity:4 帧,播放一遍 0.4 秒,一直循环。
取动图时名字要带扩展名:imageNamed() 在名字不带扩展名时只找 .png 文件。APNG 的扩展名是 .png,可以不写。
播放的规则见动图的播放。表情、加载指示这类小动图直接赋给图片视图;解码后超过 64 MB 的动图只显示第一帧,见动图占多少内存。
让动图停下
loading 是上一节读进来的那张动图,第一行重新读一次:
const loading = UIImage.imageNamed('JS/assets/anim.gif');
const frames = loading === null ? null : loading.images;
if (frames !== null) {
iv.image = frames[0];
}效果:播放停止,图片视图显示第一帧。
images 里的每一帧都是一张静态图,可以单独显示。要显示最后一帧,用 frames[frames.length - 1]。再把 loading 赋回 image,动图从头开始播放。
自己控制动图的播放
图片视图上的动图不能暂停,播完了也没有通知。需要这些时,不用图片视图,把帧交给一个图层,用关键帧动画播放。loading 是播放动图那一节读进来的动图,第一行重新读一次:
const loading = UIImage.imageNamed('JS/assets/anim.gif');
const allFrames = loading === null ? null : loading.images;
const durations = loading === null ? null : loading.frameDurations;
if (loading !== null && allFrames !== null && durations !== null) {
// 1. 一个图层,内容先设成最后一帧:动画播完后显示的是它
const layer = new CALayer();
layer.frame = new CGRect(20, 80, 48, 48);
layer.contents = allFrames[allFrames.length - 1];
page.view.layer.addSublayer(layer);
// 2. 每一帧开始的时刻,写成占总时长的比例。个数比帧数多一个,最后一个是 1
const keyTimes = [];
let elapsed = 0;
for (const seconds of durations) {
keyTimes.push(elapsed / loading.duration);
elapsed += seconds;
}
keyTimes.push(1);
// 3. 关键帧动画:依次显示每一帧,帧与帧之间不过渡
const play = CAKeyframeAnimation.animationWithKeyPath('contents');
play.values = allFrames;
play.keyTimes = keyTimes;
play.calculationMode = 'discrete';
play.duration = loading.duration;
play.repeatCount = 2;
play.addEventListener('stop', (event) => {
console.log('播完了', event.finished);
});
layer.addAnimation(play, { forKey: 'play' });
}效果
- 页面左上方出现一个 48 × 48 pt 的图层,把动图播放 2 遍,然后停在最后一帧。
- 播完时控制台输出
播完了 true。
这段代码没有作为一个整体在模拟器运行过。 验收用例检查了其中的每一步都不报错、动画挂在了图层上,没有等它播完。
repeatCount换成loading.loopCount,遍数就和文件里写的一致。loopCount是Infinity时一直循环。- 中途停下用
layer.removeAnimationForKey('play'),这时stop事件的finished是false。 - 用一组单独的图片做逐帧动画也这样写,把那组图片作为
values。
图片和视图比例不一致时怎么摆
iv.contentMode = 'scaleAspectFill';
iv.clipsToBounds = true;效果:图片保持宽高比放大或缩小,直到盖满整个视图。超出视图的部分不显示。未在模拟器验证。
各个 contentMode 的结果见图片会不会变形。
注意:
contentMode只决定图片怎么摆,不负责裁剪。用'scaleAspectFill'时不设clipsToBounds = true,超出的部分会显示在视图外面,盖住旁边的内容。
让视图的高度跟着图片的比例走
不想让图片变形,也不想留空或裁剪,就让视图的宽高比和图片一致。
const photo = UIImage.imageNamed('JS/assets/dot');
if (photo) {
iv.image = photo;
const width = 200;
const height = width * (photo.size.height / photo.size.width);
iv.frame = new CGRect(20, 100, width, height);
}效果:图片视图宽 200 pt,高度按图片的宽高比算出。图片刚好填满视图,不变形。未在模拟器验证。
用约束给图片视图定大小
这是图片视图配合约束的推荐写法:位置和宽度用约束确定,高度按固定的宽高比跟着宽度走,再用 contentMode 处理图片和视图比例不一致的情况。
const cover = new UIImageView();
cover.contentMode = 'scaleAspectFill';
cover.clipsToBounds = true;
cover.backgroundColor = 'secondarySystemBackground'; // 图片到达之前的占位底色
cover.translatesAutoresizingMaskIntoConstraints = false;
page.view.addSubview(cover);
const safe = page.view.safeAreaLayoutGuide;
NSLayoutConstraint.activateConstraints([
cover.topAnchor.constraintEqualToAnchor(safe.topAnchor, { constant: 16 }),
cover.leadingAnchor.constraintEqualToAnchor(safe.leadingAnchor, { constant: 16 }),
cover.trailingAnchor.constraintEqualToAnchor(safe.trailingAnchor, { constant: -16 }),
// 高度 = 宽度 × 9/16
cover.heightAnchor.constraintEqualToAnchor(cover.widthAnchor, { multiplier: 9 / 16 }),
]);效果:页面顶部出现一块宽高比 16:9 的灰色区域,左右各离屏幕边缘 16 pt。之后把任何比例的图片赋给 cover.image,图片都填满这块区域,不变形,超出的部分不显示,视图的大小不变。这段代码未在模拟器验证。
宽和高都被约束确定之后,图片的尺寸不再影响视图的大小。网络图片到达前后,页面上其他内容的位置不变。
只约束位置、不约束宽高时,视图的大小等于图片的 size。这种写法适合尺寸已知的小图标。
做可拉伸的背景图(九宫格)
气泡、带圆角的边框这类背景图,需要拉伸到任意大小而四个角不变形。做法是指定四条边各留多宽不参与拉伸,只拉伸中间的部分。这种做法叫九宫格。
const frameImage = UIImage.imageNamed('JS/assets/frame'); // 20 × 20 pt 的圆角边框
if (frameImage) {
iv.image = frameImage.resizableImage({
withCapInsets: new UIEdgeInsets(6, 6, 6, 6),
resizingMode: 'stretch',
});
iv.frame = new CGRect(20, 100, 280, 80);
}效果:边框图铺满 280 × 80 pt 的视图。四个角保持原来的大小和形状,四条边只沿自己的方向拉伸,中间的 8 × 8 pt 拉伸填满剩下的区域。未在模拟器验证。
withCapInsets 的四个数依次是上、左、下、右四条边保留的宽度,单位是 pt。
注意:不写
resizingMode时,中间的部分是重复平铺('tile'),不是拉伸。中间是纯色时两种方式看起来一样,有渐变或图案时不一样。
按下态换一张图
图片视图可以存两张图:平常显示 image,isHighlighted 为 true 时显示 highlightedImage。
iv.image = UIImage.systemImageNamed('star');
iv.highlightedImage = UIImage.systemImageNamed('star.fill');
iv.isHighlighted = true;效果:isHighlighted 设成 true 后,图片视图从空心星形换成实心星形。设回 false 换回空心星形。换图的效果未在模拟器验证。
系统不会自动改 isHighlighted。需要「手指按住时自动换图」时,用 UIButton 的 setImage() 给 highlighted 状态单独设一张图。
清除图片
iv.image = null;效果:图片视图不再显示图片,只剩底色(如果设了 backgroundColor)。未在模拟器验证。
生成缩略图
显示尺寸远小于原图时(比如列表里的头像),取一张缩小的图来显示。
async function showThumbnail() {
const big = UIImage.imageNamed('JS/assets/dot');
if (big === null) return;
const thumbnail = await big.prepareThumbnail(new CGSize(5, 5));
if (thumbnail) {
iv.image = thumbnail;
}
}
showThumbnail();效果:图片视图显示一张缩小过的图。缩略图在后台生成。缩略图的实际尺寸未在模拟器验证。
深色模式下换一张图
命令行工具生成的工程里做不到「深色模式下自动换图」。做法是监听 traitchange 事件,在回调里换图,见适配深色模式。