From d7403e056d25285615194c33b5cf2425df800941 Mon Sep 17 00:00:00 2001
From: dajiaohuang <dajiaohuang@bytedance.com>
Date: Mon, 24 Aug 2026 19:46:24 +0800
Subject: [PATCH 1/2] fix: prevent image preview for null/undefined image
 values

When image column cell value is null, undefined, or empty string,
clicking the cell should not open the broken image preview dialog.

Fixes #5290
---
 packages/vtable/src/event/media-click.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/packages/vtable/src/event/media-click.ts b/packages/vtable/src/event/media-click.ts
index 263489677..d18c4d65f 100644
--- a/packages/vtable/src/event/media-click.ts
+++ b/packages/vtable/src/event/media-click.ts
@@ -339,6 +339,9 @@ export function bindMediaClick(table: BaseTableAPI): void {
         if (clickToPreview === false) {
           return;
         }
+        if (!cellValue) {
+          return;
+        }
         const previewManager = getMediaPreviewManager(table);
 
         // 开启蒙版

From fa8b80afd6d0340c9ad86c34df1f87e2312cb637 Mon Sep 17 00:00:00 2001
From: Wu Shuwen <108231307+dajiaohuang@users.noreply.github.com>
Date: Wed, 26 Aug 2026 01:51:51 +0800
Subject: [PATCH 2/2] fix: handle empty audio and video previews

---
 ...0-image-null-preview_2026-08-25-17-50.json | 11 ++++++
 packages/vtable/__tests__/media-click.test.ts | 39 +++++++++++++++++++
 packages/vtable/src/event/media-click.ts      |  6 +++
 3 files changed, 56 insertions(+)
 create mode 100644 common/changes/@visactor/vtable/fix-5290-image-null-preview_2026-08-25-17-50.json
 create mode 100644 packages/vtable/__tests__/media-click.test.ts

diff --git a/common/changes/@visactor/vtable/fix-5290-image-null-preview_2026-08-25-17-50.json b/common/changes/@visactor/vtable/fix-5290-image-null-preview_2026-08-25-17-50.json
new file mode 100644
index 000000000..f2900f0db
--- /dev/null
+++ b/common/changes/@visactor/vtable/fix-5290-image-null-preview_2026-08-25-17-50.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "fix: prevent empty image, audio, and video cells from opening media previews (GitHub #5290)",
+      "type": "patch",
+      "packageName": "@visactor/vtable"
+    }
+  ],
+  "packageName": "@visactor/vtable",
+  "email": "108231307+dajiaohuang@users.noreply.github.com"
+}
diff --git a/packages/vtable/__tests__/media-click.test.ts b/packages/vtable/__tests__/media-click.test.ts
new file mode 100644
index 000000000..72b7c908d
--- /dev/null
+++ b/packages/vtable/__tests__/media-click.test.ts
@@ -0,0 +1,39 @@
+import { bindMediaClick } from '../src/event/media-click';
+import { Env, type EnvMode } from '../src/tools/env';
+import type { MousePointerCellEvent } from '../src/ts-types';
+import type { BaseTableAPI } from '../src/ts-types/base-table';
+
+describe('bindMediaClick', () => {
+  let originalMode: EnvMode;
+
+  beforeEach(() => {
+    originalMode = Env.mode;
+    Env.mode = 'browser';
+    document.body.innerHTML = '';
+  });
+
+  afterEach(() => {
+    Env.mode = originalMode;
+    document.body.innerHTML = '';
+  });
+
+  test.each(['image', 'audio', 'video'] as const)('does not open a %s preview for an empty cell', cellType => {
+    let clickHandler: ((event: MousePointerCellEvent) => void) | undefined;
+    const table = {
+      addReleaseObj: jest.fn(),
+      on: jest.fn((_event: string, handler: (event: MousePointerCellEvent) => void) => {
+        clickHandler = handler;
+      }),
+      getCellType: jest.fn(() => cellType),
+      isHeader: jest.fn(() => false),
+      getBodyColumnDefine: jest.fn(() => ({ clickToPreview: true })),
+      getCellValue: jest.fn(() => null),
+      getCellOriginValue: jest.fn(() => null)
+    } as unknown as BaseTableAPI;
+
+    bindMediaClick(table);
+    clickHandler?.({ col: 0, row: 0, target: { type: 'rect' } } as MousePointerCellEvent);
+
+    expect(document.body.childElementCount).toBe(0);
+  });
+});
diff --git a/packages/vtable/src/event/media-click.ts b/packages/vtable/src/event/media-click.ts
index d18c4d65f..25819d5ca 100644
--- a/packages/vtable/src/event/media-click.ts
+++ b/packages/vtable/src/event/media-click.ts
@@ -393,6 +393,9 @@ export function bindMediaClick(table: BaseTableAPI): void {
         if (clickToPreview === false) {
           return;
         }
+        if (!cellValue) {
+          return;
+        }
         const previewManager = getMediaPreviewManager(table);
 
         // 开启蒙版
@@ -434,6 +437,9 @@ export function bindMediaClick(table: BaseTableAPI): void {
         if (clickToPreview === false) {
           return;
         }
+        if (!cellValue) {
+          return;
+        }
         const previewManager = getMediaPreviewManager(table);
 
         // 开启蒙版