单图片管理（只读模式）

本文介绍如何在 tio-boot-admin + tio-boot-admin-react 体系下，实现单张图片的管理与展示。该方案仅用于浏览与查询，不支持图片上传、编辑或删除操作，适用于 OCR 结果缓存、日志快照、第三方图片引用等只读业务场景。

一、使用场景说明

本方案适合以下场景：

每条记录只对应 一张图片
图片已由其他系统或流程生成
当前系统只负责 展示与查询
不需要在后台进行图片编辑或替换

例如：

OCR 识别结果缓存
第三方接口返回的图片结果
异步任务生成的截图或图片日志

二、数据表设计

图片信息直接存储在业务表中，通过 url 字段保存图片访问地址。

sql

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 组件，仅用于查询与展示。

tsx

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

返回数据示例：

json

{
  "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 字段直接用于图片展示
不需要任何额外格式转换
前端可直接消费该数据结构

六、页面展示效果

Alt text

页面效果说明：

表格中直接显示图片缩略图
点击图片可进行放大预览
支持分页、排序、时间区间筛选
文本字段支持复制，便于排查与分析

七、方案总结

该单图片管理方案具备以下特点：

实现简单，无需额外文件表
完全只读，安全可控
与 tio-boot-admin 通用 CRUD 高度兼容
非常适合日志型、缓存型、结果型图片数据

单图片管理（只读模式） ​

一、使用场景说明 ​

二、数据表设计 ​

字段说明 ​

三、前端表格列配置 ​

说明 ​

四、页面组件配置 ​

关键点说明 ​

五、后端接口返回示例 ​