企业官网建设流程全解析

1. 先想清楚边界：组件截图和"截屏"不是一回事

1.1 常规截屏在鸿蒙里为什么不通用

接到这个需求的第一反应，不少人会想：直接调截屏不就行了吗？如果只是做一个"帮用户保存当前屏幕"的功能，截屏确实够用。但一旦题目变成"把页面里某一个卡片、某一段滚动列表导出成长图"，系统截屏立刻就不合适了，原因有几个。

第一，系统截屏拿到的是整块屏幕的位图，包含状态栏、导航栏、弹窗，甚至还有别的应用浮层。产品要的往往是"只截内容区"，你事后还得自己去裁切，非常麻烦。第二，系统截屏的触发时机掌握在用户手里，长按音量键、下拉控制中心，这些都不是应用能可靠感知的。做自动化导出时，你根本没法和系统的交互流程对齐。第三，也是最重要的一点：截屏只能截"当前屏上已经绘制出来的部分"。Scroll组件里的内容一旦滚出可视区，它可能就释放了渲染资源，你截不到屏幕外的东西，这直接堵死了滚动长图的路。

所以HarmonyOS上做这类能力，正确的思路是走组件截图，而不是截屏。组件快照的API可以精确拿到某个节点及其子树当前的渲染结果，返回一个内存里的PixelMap对象，然后再由我们自己对这张图做压缩、拼接、落盘。这个概念有点像给网页里的某个DOM元素单独截图，而不是用手机拍屏幕。

1.2 组件截图的典型场景

在我实际做过的项目里，组件截图最常见的用途有三个。

第一个是生成分享卡片。用户在应用里完成一次打卡、一笔缴费、一次运动记录，应用把这段信息渲染成一个精美卡片，然后通过组件截图把卡片转成图片，用户保存或分享出去。这样做的好处是排版完全可控，服务端不需要为了生成图片单独准备模板引擎，前端渲染成什么样，导出就是什么样。

第二个是长列表导出。比如用户的订单列表、笔记列表、学习记录，内容长到需要滚动才能看完。产品希望一次性生成一张长图，方便用户整张保存或分享。这就是典型的滚动长图需求，也是这篇文章标题里"滚动长图"要解决的问题。

第三个是离线报告和凭证。航班值机牌、缴费回执、体检报告，这些内容往往在用户没有网络的环境下也需要能生成图片。应用把数据渲染成组件，截图输出，整个过程不经过网络服务，这就引出了标题里的"离线截图"。

三个场景看似不同，底层技术栈其实是同一个：组件快照 + 分段截取 + 像素拼接 + 文件写入。把这套链路摸透了，后面做任何导出图片的功能都只是换数据源而已。

1.3 组件快照和PixelMap到底是什么关系

PixelMap可以理解成鸿蒙上像素图的统一容器，类似于Android里的Bitmap、iOS里的UIImage。组件截图API返回给你的就是一个PixelMap，后面你可以把它压缩成JPEG/PNG，也可以把多个PixelMap拼到一张图里，还可以直接读取像素数据做分析。

核心调用是这样的：给目标组件设置一个id，然后调用组件快照模块的接口，传入这个id，异步返回PixelMap。听起来很简单，但这里藏着不少细节。快照拿到的是组件在当前渲染管线里的状态，如果组件还没完成布局、或者处于不可见状态、或者正在被某个Surface覆盖，拿到的结果就会偏离预期。这些都是我后面要重点展开的坑。

2. 组件快照API的打开方式：从PixelMap到落盘保存

2.1 核心API的调用姿势

先给一段最基础的可运行代码，把整体链路跑通：

import { componentSnapshot } from '@kit.ArkUI'; import { image } from '@kit.ImageKit'; import { fileIo as fs } from '@kit.CoreFileKit'; @Entry @Component struct SnapshotDemo { async takeSnapshot() { // 拿到目标组件的像素图 const pixelMap: image.PixelMap = await componentSnapshot.get('snapshotCard'); if (!pixelMap) { console.error('快照失败'); return; } // 压缩成JPEG字节流 const packer = image.createImagePacker(); const outBuffer: ArrayBuffer = await packer.packing(pixelMap, { format: 'image/jpeg', quality: 95 }); // 写入应用沙箱文件 const path = `${fs.getFilesDir()}/card_snapshot.jpg`; const file = fs.openSync(path, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); fs.writeSync(file.fd, outBuffer); fs.closeSync(file); // 及时释放内存 pixelMap.release(); } }

注意，不同SDK版本里组件快照的入口可能有差异。有些版本是在componentSnapshot这个模块下暴露get方法，有些版本需要你先拿到UIContext，再通过getComponentUtils()去创建快照。写代码时以你工程里实际可导入的API为准，但思路不变：先拿节点，再要PixelMap。

组件要能被抓到，必须先设置id，这是最容易被新手漏掉的一步：

Row() { Text('这是内容区域') // ... } .id('snapshotCard')

如果页面里存在多个相同节点，id必须是唯一的。快照接口返回的是Promise，所以记得用async/await，或者用.then()处理。

2.2 拿到PixelMap之后的处理链路

拿到PixelMap后，常见处理有三类：压缩成文件、直接展示、继续做拼接。

压缩成文件是最常见的。ImagePacker的packing方法支持format、quality参数。如果要保留透明背景，就用image/png；如果只是普通内容且对体积敏感，用image/jpeg。质量参数一般放在90到95之间，低于85时文字边缘容易出现明显压缩痕迹，长图尤其明显。

直接展示的场景不多，但调试时很有用。你可以把PixelMap通过Image组件显示出来，直观确认快照内容对不对，排查问题会快很多。

继续做拼接就是滚动长图的核心逻辑了。先把每一段的PixelMap放进一个列表，最后统一绘制到目标画布上，我再往下细说。

2.3 文档没讲的边界条件

这部分是我反复踩出来的结论，值得先记住。

组件如果带透明背景，快照结果也可能是透明的。你用JPEG格式保存时，透明通道会被当成黑色填充，导致图片背景发黑。解决办法有两种：要么用PNG格式保存，要么在截图前给组件设置一个不透明的背景色，比如backgroundColor('#FFFFFF')。

组件处于opacity: 0或visibility: Hidden时，快照接口虽然能返回，但内容往往是空的。市面上有些活动页为了隐藏某些元素，会动态把透明度调成0，截图前一定要检查这类状态。更隐蔽的是：如果你在弹窗还没完全消失时就截图，快照内容可能带着半透明的遮罩层。所以截图时机应该放在UI事件稳定之后，而不是点击事件触发瞬间。

还有一点：快照API必须在窗口可见、应用处于前台的状态下调用。应用切到后台再调用，部分版本的实现可能拿不到有效帧，返回空PixelMap。离线截图并不等于后台截图，用户至少要在页面里看到一个正在生成的进度条。

3. 滚动长图的工程实现：让Scroll内容"排队进相机"

3.1 分段思想的由来

组件快照只能截到当前屏幕内渲染出来的那部分，这是硬限制。那滚动长图怎么做？答案是让内容自己"走到镜头前"。

Step by step：把Scroll容器滚动到某个位置，等待一帧渲染完成，快照当前可视区域，再滚动到下一个位置，再快照……最后把所有可视区域的图片沿垂直方向拼接起来。这个思路，本质上是在模拟人眼分屏看长页面，然后手动把每一屏拼成完整长图。

为什么不直接通过某种"离屏渲染整棵组件树"的方式一次性出图？因为ArkUI的滚动容器为了性能和内存考虑，不会把滚出视口的内容都保留在渲染树上。组件树里不存在的节点，自然无从快照。分段截取是最通用、最可靠的方案，尤其适配列表类场景。

分段数量按这个公式估算：

segmentCount = ceil((totalHeight - viewportHeight) / stepHeight) + 1

totalHeight是内容总高度，viewportHeight是Scroll可视区高度，stepHeight是每次滚动的距离。为了拼接时能对齐，我通常让stepHeight略小于viewportHeight，也就是两个相邻片段之间留出重叠区域。这样就算滚动偏移差了几个像素，还能靠重叠区域校准，不会丢内容。

3.2 滚动、对齐与重叠处理

核心循环写成伪代码大概是这个风格：

async function captureScrollShot(options) { const { scroller, targetId, viewportHeight, totalHeight, overlap = 12, onProgress } = options; const stepHeight = viewportHeight - overlap; // 计算需要截多少段 const segmentCount = Math.ceil((totalHeight - viewportHeight) / stepHeight) + 1; const segments: Array<{ pixelMap: PixelMap, offsetY: number }> = []; for (let i = 0; i < segmentCount; i++) { const targetOffset = Math.min(i * stepHeight, totalHeight - viewportHeight); // 瞬间定位，不要带动画 scroller.scrollTo({ offset: targetOffset, animation: { duration: 0 } }); // 等滚动到位并让渲染管线稳定 await waitForScrollDone(scroller, targetOffset); // 截取当前可见区域 const pm = await componentSnapshot.get(targetId); if (pm) { segments.push({ pixelMap: pm, offsetY: targetOffset }); onProgress?.(i + 1, segmentCount); } else { throw new Error(`第 ${i + 1} 段截图失败`); } } return segments; }

waitForScrollDone的实现我推荐用事件驱动。最稳妥的是依赖Scroll的onScrollStop回调，但它在快速连续滚动时可能会漏掉事件，所以我在项目里用了一种"滚动目标值 + 轮询校验"的方式：滚动后先等50ms，然后周期性检查当前滚动偏移是否已经等于目标偏移，连续两次一致再继续。实际用下来，比固定setTimeout(300)要稳得多，也几乎不会出现时序错乱。

对齐这里有个容易被忽略的细节：滚动偏移必须取整数像素。如果滚动容器本身有scrollBar或者内容有margin，相邻两段的边界线可能出现半个像素的偏差，拼接时就会出现一条细缝或一行重复内容。我的做法是先隐藏滚动条，然后统一让内容顶部对齐到0坐标，避免偏移量出现小数。

3.3 离屏拼接与编码输出

分段快照只是拿到了N张屏幕宽的小图，下一步是把它们拼成长图。

我习惯用离屏Canvas来做拼接，而不是直接操作PixelMap。原因是Canvas的drawImage可以把PixelMap作为图像源，按指定的坐标和尺寸绘制，拼接逻辑很直观：

// 目标画布宽度为内容宽度，高度为内容总高度 // 每段的像素从 offsetY 处开始绘制 for (const seg of segments) { ctx.drawImage(seg.pixelMap, 0, seg.offsetY, contentWidth, viewportHeight); seg.pixelMap.release(); // 绘制完这几段就可以释放 }

绘制完之后，把画布内容导出成PixelMap或直接编码。如果你用的是OffscreenCanvas，导出之前要统一处理背景：内容无透明背景时，先填充白色，再逐段绘制，这样后续转JPEG不会发黑。

拼接阶段最需要警惕的是内存。假设屏幕宽度是1080，内容总高度是3000，生成的未压缩Bitmap像素数据大约有1080*3000*4字节，约12.9MB，看起来不大。但如果你同时保留着分段列表里的每一张临时PixelMap，内存峰值会飞快翻倍。分段数量越多，峰值越高。所以我每一段绘制完就立刻release()，绝不在列表里囤积到全部截完。

如果内容总高度特别离谱，比如超过5000像素，建议干脆不要拼单图。可以输出多张分段图，或者等比压缩高度。产品上"一张超长图"的执念，最终往往会让位于"内存不崩"这个底线。

4. 离线截图的关键设计：每个字节都来自本地

4.1 什么叫"离线也能截图"

很多人以为"离线截图"就是指截图功能本身不需要网络，其实没那么简单。

组件截图本质上是端侧渲染能力的调用，不联网完全可以执行。真正的难点在于：你要截图的那个组件，它内部渲染用到的资源是不是也离线可用。如果页面上有一张从CDN加载的头像、一个从服务端动态拉取的模板配置、一种用户手机上根本没安装的字体，当网络不可用时，这些资源就会变成空白、占位图或者回退样式，截出来的图自然就不完整。

所以"离线截图"在工程上要做到的是：截图这一时刻，页面所有可见内容都来自可信的本地资源。这不是一个API，而是一整套资源管理和渲染架构的取舍。

离线场景我推荐一个约定：需要导出图片的内容，单独用一个"导出专用组件"来渲染，不要直接复用复杂的线上页面。原因很简单，线上页面为了交互可以有很多动态状态，截图时这些状态未必处于理想状况；导出专用组件则可以直接绑定一份本地数据，样式固定，资源都走本地，截图输出可控性高得多。

4.2 本地化资源与网络图片兜底

具体到实践，我一般会做三件事。

第一，所有图标和静态底图改用$r('app.media.xxx')或$rawfile引用，确保随应用打包。不要用网络图标URL，尤其不要在截图前才临时去拉图标。产品总是希望"动态换个图"，但从离线截图的角度，所有需要出现在长图里的静态资源，在发布时就必须存在于应用包里。

第二，动态图片要有明确的缓存策略。用户在离线状态下截图，组件里的头像可能来自本地缓存文件。判断逻辑建议这样写：

const imageSrc = this.localCacheUri // 已缓存到沙箱的本地文件 ? this.localCacheUri : tryDownloadAndCache() ?? $r('app.media.default_avatar'); Image(imageSrc) .width(80) .height(80) .borderRadius(40)

注意，不要直接在Image组件里写网络URL然后指望它"等一下加载完再截"。因为加载是异步的，截图时机根本不可控。正确的是在进入截图流程前，先把所有需要的网络图都下载到沙箱并确认文件存在，再开始渲染和快照。

第三，字体的离线处理。中文内容长图最容易翻车的其实是字体。如果目标设备没有你设计稿里指定的字体，系统会用默认字体替代，行高、字宽都会变，长图拼接后可能出现文字错位。稳妥做法是把需要展示的品牌字体打包进应用rawfile，在组件里通过fontFamily显式指定。如果对字体体积敏感，至少把数字和英文子集打包，中文尽量用系统默认字体，并让布局容错。

4.3 文件保存与分享的取舍

离线生成图片之后，文件该写到哪？这里有个优先级。

最省事的是写到应用沙箱目录，不申请任何权限，直接fs.writeSync就能完成。缺点是对用户不可见，用户要拿去分享时，需要通过应用内的分享入口主动操作。

如果希望图片进系统相册，HarmonyOS里有两个选择。一种是在应用配置文件里申请保存图片/视频到相册之类的权限，然后通过PhotoAccessHelper写入；另一种是利用安全控件SaveButton，它是系统级授权控件，用户点击一下就能完成保存，应用不需要申请高敏感权限。离线场景我强烈推荐SaveButton，因为它同时在UI上给用户明确提示，合规性和隐私体验都好很多。

至于在线分享，就交给系统分享组件。图片先在本地生成，再通过Want拉起分享面板，这部分是标准能力，不在本文深挖。

5. 实际项目中绕不开的坑：四条完整的排查链路

5.1 截出来全是白屏

这是我遇到最多的问题，现象是代码没有任何异常，PixelMap也返回了，但导出的图片全白。

排查思路要按顺序走。第一步，先做一个最小复现：页面上放一个固定文本组件，设置id，在按钮点击里直接快照。如果最小的组件能截出来，说明API链路是通的，问题出在组件本身或其状态。如果最小组件也是白屏，检查是不是在aboutToAppear里就调了快照。页面还没完成首帧渲染时，组件节点虽然存在，但纹理内容还没生成，这个时机太快了。

正确的时机应该选在onPageShow之后、或者按钮点击事件里，确保用户已经能看到目标内容。更好的做法是监听目标组件的onAreaChange回调，它代表布局已经计算完成。在这个回调里触发截图，成功率明显更高。

如果页面里有大量异步数据，先保证数据setState完成后再截图。我的经验是：先await图片资源加载，再设置状态，最后调用快照。不要试图在数据还没到位时截"带数据的图"，那只会让你反复调试时序。

5.2 拼接处出现重复行或白边

长图拼完之后，中间出现了明显的接缝，有时是重复了一行内容，有时是有一条白线。这个问题的根因，基本都是"截图区域与滚动偏移没有整数对齐"。

先检查Scroll容器上有没有edgeEffect、阴影、子项margin。这些元素会出现在可视区边缘，第一段截到了卡片的上半部分，第二段又截到了同一张卡片的下半部分，拼接后自然重复。

我的修正方案是给滚动列表去掉margin和阴影类效果，把边距转移到每个ListItem内部。这样滚动区域的边界恰好就是内容的边界，不会出现两个段落同时绘制同一条边线的情况。另外，每段的截图高度要用viewportHeight，不要用快照返回的实际像素高度去推断，因为不同分辨率和缩放比下，快照像素高度可能与逻辑高度不一致。取viewportHeight乘以屏幕密度，得到的才是真正的像素高度。

还有一个小技巧：拼接时故意让相邻两段重叠12像素左右，然后从中间画一条分割线，只用每一段的中间区域拼接，边缘区域丢弃。这样做虽然多截了一些内容，但能彻底消除边缘状态不一致带来的缝隙。

5.3 PixelMap申请失败或OOM

长图拼接过程中最容易崩的环节是创建目标长图PixelMap。宽1080、高8000的图，原始像素数据大约34.5MB，如果设备内存本身紧张，申请就会失败，或者应用崩溃。

遇到这种崩溃，先看日志里的内存错误，再算一下你的目标尺寸。我建议在进入截图流程前，先预估目标图内存：

memory = width * height * 4

如果结果超过设备物理内存的十分之一，就要考虑降级策略。降级方案有两个方向：一是降低输出图片的宽度，比如用逻辑宽度的一半生成长图，画质损失可控；二是把一张超长图拆成多张中等长度的图，每张高不超过3000像素，由用户滑动查看。

同时，拼接过程中每个segment的PixelMap用完立刻release，绝不要积压。很多时候OOM不是目标图太大，而是你同时持有几十张临时图。

5.4 页面里有Web/XComponent时的渲染异常

如果目标区域内嵌了Web组件或者视频类的XComponent，快照结果经常是黑块或空白。原因是这类组件底层用的是独立的Surface渲染，系统合成器未必会把Surface上的内容同步到组件快照的纹理里。

这不是你代码写错了，而是这类组件的天生限制。处理方式是在截图前做"降级替换"：把Web组件区域替换成一个静态图片组件，把视频画面替换成当前帧的缩略图，再执行快照。虽然有点绕，但在离线截图场景下，用户看到的是最终长图里有一张静态内容，接受度很高。

如果产品坚持要截到Web的真实内容，那就不适合用组件快照，应该走Web组件内部的截图或JS桥接方案，技术复杂度会高一个量级。

6. 工程化封装：一个能直接抄的滚动长图工具

6.1 对外接口设计

做成一个独立工具类，不要把滚动、快照、拼接逻辑散落在页面里。我一般这样设计接口：

export interface ScrollShotOptions { targetId: string; scroller: Scroller; viewportHeight: number; totalHeight: number; outputPath: string; overlap?: number; bgColor?: string; maxSingleHeight?: number; compressQuality?: number; onProgress?: (current: number, total: number) => void; } export class SnapshotManager { static async generateScrollShot(options: ScrollShotOptions): Promise<string>; }

页面里使用时只需要关心三件事：目标节点的id、滚动控制器、内容总高度。其余参数都有默认值。totalHeight记得在内容数据变化后重新计算，不要缓存旧值。

6.2 参数与建议默认值

默认值我一般这么设置：

maxSingleHeight是最值得留意的参数，它直接决定了单张图片的内存峰值。宁可多输出几张图，也不要赌设备内存。

6.3 测试验证建议

最后说一下测试。组件截图、滚动长图这类功能，浏览器里调试是一回事，真机上又是另一回事。我通常准备一张包含图片、文字、按钮、列表混合的长页面，分别在高、中、低三档分辨率的设备上跑。每档设备都要测：深色模式下背景是否被正确填充、系统字体缩放比例变化后拼接是否还对齐、飞行模式下资源是否正常显示。

每跑一轮，我会把输出的长图用预览工具放大，专门检查相邻片段接缝处的文字有没有半截字、图片有没有错位。这个检查最好做成每轮发布的固定步骤，不要等到用户反馈才想起来。

自动化的方向，可以尝试在测试用例里模拟滚动和点击，然后用AbilityDelegator或UIAutomator框架把快照流程脚本化。不过坦白说，这类涉及真实渲染输出的功能，自动化脚本只能覆盖主流程，真正细腻的视觉效果还是需要人为看一遍。

最后分享一个我自己长期保留的习惯：做这类功能，先把"固定内容截图"跑通，再碰滚动拼接，最后才处理离线资源。因为组件快照的很多坑（渲染时机、透明背景、Surface限制）一旦混在拼接流程里，定位成本会成倍增加。先把每一层都单独验证到位，再逐层组合，你会发现鸿蒙的组件截图能力其实相当稳定。