LargeImageModel完整API清单：largeImage4cj流式配置指南，一张表看懂全部接口-平芜编程栈

LargeImageModel完整API清单：largeImage4cj流式配置指南，一张表看懂全部接口

【免费下载链接】large-image-cj图像加载库，支持加载、缩放和拖动项目地址: https://gitcode.com/Cangjie-TPC/large-image-cj

largeImage4cj 是一个支持加载、缩放（放大/缩小）和拖动查看的图像加载库，核心由LargeImageModel图片数据封装类驱动。本文用一张表整理它的全部 API 接口，并讲解流式（链式）配置写法，帮助你快速完成缩放比例、拖动边界、事件监听等配置。

为什么要用 largeImage4cj？

普通图片组件放大后容易模糊，largeImage4cj 专为大图浏览设计：

📷 支持 Uri 地址、resources 资源两种图片加载方式
🤏 双指捏合缩放，双击快速放大/还原
👆 放大后单指拖动查看细节，支持惯性滑动
🎛 所有配置接口集中封装在LargeImageModel中，一目了然

库的源码位于 large_image_model.cj 与 large_image.cj，接口说明可参考 doc/feature_api.md。

LargeImageModel 接口清单：一张表看懂全部接口

分类	接口	作用说明	默认值
初始化	`initMatrix()`	初始化渲染矩阵，必须前置调用一次	—
图片源	`setImageURI(src)`	从 Uri 地址加载图片	—
图片源	`setImageResource(src)`	从 resources 包加载图片	—
手势开关	`setZoomEnabled(enabled)`	是否支持缩放	`true`
手势开关	`setPanEnabled(enabled)`	是否支持平移拖动	`true`
缩放控制	`setMaxScale(scale)`	设置最大缩放比例	`4.0`
缩放控制	`setMinimumDpi(dpi)`	按屏幕密度设置最大缩放（DPI 越小放得越大）	屏幕密度
缩放控制	`setMaximumDpi(dpi)`	按屏幕密度设置最小缩放	屏幕密度
拖动边界	`setPanLimit(limit)`	设置图片可拖动的范围（见下表）	`PAN_LIMIT_INSIDE`
外观	`setTileBackgroundColor(color)`	设置 tile 背景颜色（UInt32 色值）	黑色
外观	`setOrientation(degrees)`	设置图片旋转角度	`0.0`
状态查询	`canScroll()`	判断当前是否可拖动	—
状态查询	`getLoadedImageWidth()`/`getLoadedImageHeight()`	获取源图像宽高	—
状态查询	`getMaxScale()`/`getMinScale()`	获取最大/最小缩放比例	—
状态查询	`getOrientation()`	获取当前旋转角度	—
状态操作	`setOffset(x, y)`	设置图片相对视图左上角的偏移	—
状态操作	`resetScaleAndCenter()`	重置缩放比和图片中心点	—
事件监听	`setSingleTapListener(listener)`	单击事件监听	—
事件监听	`setLongPressListener(listener)`	长按事件监听	—
事件监听	`setDoubleTapListener(listener)`	双击事件监听（缩放关闭时生效）	—
事件监听	`setOnStateChangedListener(listener)`	缩放状态切换监听	—
事件监听	`setOnImageEventListener(listener)`	图片加载成功/失败监听	—

流式配置指南：链式调用快速上手

所有set系列接口都会返回LargeImageModel自身，因此支持流式（链式）配置：一行代码串联多个设置，无需反复书写变量名。

model.initMatrix() model.setImageResource(@r(app.media.tiger)) model.setMaxScale(2.0)

上面是 entry/src/main/cangjie/image_display.cj 中的真实配置：初始化矩阵 → 设置图片资源 → 限制最大放大 2 倍，三步完成一张可缩放大图的全部配置。

💡 注意：initMatrix()因@Publish可观测属性触发 UI 更新，必须在其他配置之前调用一次，确保属性全部初始化完成。

拖动边界三常量：PAN_LIMIT 对比表

setPanLimit决定"图片最多能拖到哪"，通过三个常量控制，源码见 large_image_model.cj：

常量	值	行为描述	适用场景
`PAN_LIMIT_INSIDE`	`1.0`	图片只能在视图范围内平移，边界不会超出视图	图片库、相册（推荐）
`PAN_LIMIT_OUTSIDE`	`2.0`	允许图片拖出视图边缘，直到刚好完全移出屏幕	自由浏览型场景
`PAN_LIMIT_CENTER`	`3.0`	以中心为基准平移，任一角到达屏幕中心即停止	需要将任意位置拖到正中心的场景

示例工程中通过 entry/src/main/cangjie/configuration.cj 动态切换三种模式，可以直观感受差异。

事件监听接口速查

5 个监听器接口定义在 largeImage/src/main/cangjie/interfaces.cj：

监听器接口	回调方法	触发时机
`OnSingleTapListener`	`onSingleTapConfirmed(event)`	单击确认时
`OnLongPressListener`	`onLongPress(event)`	长按时
`OnDoubleTapListener`	`onDoubleTap(event)`	双击时（`zoomEnabled`为 false 时生效）
`OnStateChangedListener`	`onScaleChanged(newScale)`	缩放比例变化后
`OnImageEventListener`	`onImageLoaded()`/`onImageLoadError()`	图片加载成功 / 失败

常见配置组合参考

需求场景	推荐配置组合
标准图片库	`setPanLimit(PAN_LIMIT_INSIDE)`（默认值，无需额外配置）
只放大、禁止拖动	`setPanEnabled(false)`，双击仅在中心点放大
高倍放大看图	`setMinimumDpi(50)`，放直到明显像素化为止
快速双击变焦	双击直接跳到`maxScale`，立即响应无动画
居中查看细节	`setPanLimit(PAN_LIMIT_CENTER)`，任意位置拖到屏幕中心