单图片管理(只读模式)
本文介绍如何在 tio-boot-admin + tio-boot-admin-react 体系下,实现单张图片的管理与展示。 该方案仅用于浏览与查询,不支持图片上传、编辑或删除操作,适用于 OCR 结果缓存、日志快照、第三方图片引用等只读业务场景。
一、使用场景说明
本方案适合以下场景:
- 每条记录只对应 一张图片
- 图片已由其他系统或流程生成
- 当前系统只负责 展示与查询
- 不需要在后台进行图片编辑或替换
例如:
- OCR 识别结果缓存
- 第三方接口返回的图片结果
- 异步任务生成的截图或图片日志
二、数据表设计
图片信息直接存储在业务表中,通过 url 字段保存图片访问地址。
CREATE TABLE "public"."mv_file_ocr_cache" (
"id" int8 PRIMARY KEY,
"url" varchar,
"md5" varchar,
"filename" varchar,
"file_id" int8,
"data" varchar,
"elapsed" int8,
"creator" varchar(64) DEFAULT '',
"create_time" timestamptz NOT NULL DEFAULT CURRENT_TIMESTAMP,
"updater" varchar(64) DEFAULT '',
"update_time" timestamptz NOT NULL DEFAULT CURRENT_TIMESTAMP,
"deleted" int2 DEFAULT 0,
"tenant_id" int8 NOT NULL DEFAULT 0
);
字段说明
| 字段名 | 说明 |
|---|---|
| id | 主键 |
| url | 图片访问地址 |
| filename | 原始文件名 |
| md5 | 文件 MD5 |
| file_id | 文件服务中的文件 ID |
| data | OCR 或业务处理结果 |
| elapsed | 处理耗时 |
| deleted | 软删除标记 |
| tenant_id | 租户 ID |
三、前端表格列配置
使用 Ant Design Pro 的 ProColumns,直接通过 valueType: 'image' 实现图片展示。
import { ProColumns } from '@ant-design/pro-components';
export const mv_file_ocr_cache_column = (): ProColumns<any>[] => [
{
title: 'url',
dataIndex: 'url',
valueType: 'image',
},
{
title: 'filename',
dataIndex: 'filename',
valueType: 'text',
},
{
title: 'file_id',
dataIndex: 'file_id',
valueType: 'text',
},
{
title: 'data',
dataIndex: 'data',
valueType: 'textarea',
ellipsis: true,
copyable: true,
},
{
title: 'update_time',
dataIndex: 'update_time',
valueType: 'dateTime',
hideInSearch: true,
hideInForm: true,
},
{
key: 'update_time',
title: 'update_time',
dataIndex: 'update_time_range',
valueType: 'dateTimeRange',
hideInTable: true,
hideInForm: true,
hideInDescriptions: true,
},
];
说明
valueType: 'image'- 自动渲染为图片
- 支持点击放大预览
data字段支持:- 超出省略
- 一键复制
时间字段同时支持:
- 表格展示
- 区间查询(通过隐藏列实现)
四、页面组件配置
页面使用通用的 ApiTable 组件,仅用于查询与展示。
import ApiTable from '@/components/common/ApiTable';
import { mv_file_ocr_cache_column } from '@/pages/app/mv_file_ocr_cache/mv_file_ocr_cache_column';
export default () => {
const from = 'mv_file_ocr_cache';
const beforePageRequest = (params: any, isRecoveryMode?: boolean) => {
params.idType = 'long';
params.deleted = isRecoveryMode ? 1 : 0;
params.orderBy = 'update_time';
params.isAsc = 'false';
params.update_time_op = 'bt';
params.topicOp = 'ct';
params.codeOp = 'ct';
// 防止后端尝试自动解析 JSON 字段
params.json_fields = ['files'];
return params;
};
const beforeCreateRequest = (formValues: any) => {
return {
...formValues,
idType: 'long',
};
};
return (
<ApiTable
from={from}
columns={mv_file_ocr_cache_column()}
beforePageRequest={beforePageRequest}
beforeCreateRequest={beforeCreateRequest}
/>
);
};
关键点说明
本页面 不配置上传能力
ApiTable仅用于:- 分页查询
- 条件筛选
- 图片预览
明确排序规则,避免列表顺序不稳定
保留
json_fields是为了兼容后端通用逻辑
五、后端接口返回示例
接口地址:
GET /api/table/mv_file_ocr_cache/page
返回数据示例:
{
"code": 1,
"data": {
"list": [
{
"id": "604516238379364352",
"url": "https://manimvideo.explanation.fun/user/upload/604516212877996032.png",
"filename": "截屏2026-01-23 下午4.31.30.png",
"md5": "54dd34351d6d2ac81f39d014a001730c",
"file_id": "604516213351952384",
"data": "xxx",
"elapsed": "5960",
"update_time": "2026-01-23 21:31:42.599663",
"creator": "",
"updater": "",
"deleted": 0,
"tenant_id": "0"
}
],
"total": 12
},
"ok": true
}
说明
url字段直接用于图片展示- 不需要任何额外格式转换
- 前端可直接消费该数据结构
六、页面展示效果


页面效果说明:
- 表格中直接显示图片缩略图
- 点击图片可进行放大预览
- 支持分页、排序、时间区间筛选
- 文本字段支持复制,便于排查与分析
七、方案总结
该单图片管理方案具备以下特点:
- 实现简单,无需额外文件表
- 完全只读,安全可控
- 与 tio-boot-admin 通用 CRUD 高度兼容
- 非常适合日志型、缓存型、结果型图片数据
