feat(image-viewer): support closeOnEscKeydown (#2890)

Tencent · Nov 23, 2023 · 2a7af5a · 2a7af5a
1 parent 1c64151
commit 2a7af5a
Show file tree

Hide file tree

Showing 7 changed files with 30 additions and 11 deletions.
diff --git a/src/image-viewer/_example/base.vue b/src/image-viewer/_example/base.vue
@@ -1,7 +1,7 @@
 <template>
   <div>
     <div class="tdesign-demo-image-viewer__base">
-      <t-image-viewer v-model="visible" :images="[img]">
+      <t-image-viewer v-model="visible" :images="[img]" :closeOnEscKeydown="false">
         <template #trigger="{ open }">
           <div class="tdesign-demo-image-viewer__ui-image" @click="open">
             <img alt="test" :src="img" class="tdesign-demo-image-viewer__ui-image--img" />

diff --git a/src/image-viewer/image-viewer.en-US.md b/src/image-viewer/image-viewer.en-US.md
@@ -6,19 +6,21 @@
 name | type | default | description | required
 -- | -- | -- | -- | --
 closeBtn | Boolean / Slot / Function | true | Typescript：`boolean \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
+closeOnEscKeydown | Boolean | true | trigger image viewer close event on `ESC` keydown | N
 closeOnOverlay | Boolean | - | \- | N
 draggable | Boolean | undefined | \- | N
 imageScale | Object | - | Typescript：`ImageScale` `interface ImageScale { max: number; min: number; step: number }`。[see more ts definition](https://github.com/Tencent/tdesign-vue/tree/develop/src/image-viewer/type.ts) | N
 images | Array | [] | Typescript：`Array<string \| File \| ImageInfo>` `interface ImageInfo { mainImage: string \| File; thumbnail?: string \| File; download?: boolean }`。[see more ts definition](https://github.com/Tencent/tdesign-vue/tree/develop/src/image-viewer/type.ts) | N
-index | Number | - | `.sync` is supported | N
-defaultIndex | Number | - | uncontrolled property | N
+index | Number | 0 | `.sync` is supported | N
+defaultIndex | Number | 0 | uncontrolled property | N
 mode | String | modal | options: modal/modeless | N
 navigationArrow | Boolean / Slot / Function | true | Typescript：`boolean \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
 showOverlay | Boolean | undefined | \- | N
 title | String / Slot / Function | - | preview title。Typescript：`string \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
-trigger | String / Slot / Function | - | trigger element。Typescript：`string \| TNode<{ open: () => void }>`。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
+trigger | String / Slot / Function | - | trigger element。Typescript：`TNode \| TNode<{ open: () => void }>`。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
 viewerScale | Object | - | Typescript：`ImageViewerScale` `interface ImageViewerScale { minWidth: number; minHeight: number }`。[see more ts definition](https://github.com/Tencent/tdesign-vue/tree/develop/src/image-viewer/type.ts) | N
-visible | Boolean | false | `v-model` is supported | N
+visible | Boolean | false | hide or show image viewer。`v-model` is supported | N
+defaultVisible | Boolean | false | hide or show image viewer。uncontrolled property | N
 zIndex | Number | - | \- | N
 onClose | Function |  | Typescript：`(context: { trigger: 'close-btn' \| 'overlay' \| 'esc'; e: MouseEvent \| KeyboardEvent }) => void`<br/> | N
 onIndexChange | Function |  | Typescript：`(index: number, context: { trigger: 'prev' \| 'next' \| 'current' }) => void`<br/> | N

diff --git a/src/image-viewer/image-viewer.md b/src/image-viewer/image-viewer.md
@@ -6,19 +6,21 @@
 名称 | 类型 | 默认值 | 说明 | 必传
 -- | -- | -- | -- | --
 closeBtn | Boolean / Slot / Function | true | 是否展示关闭按钮，值为 `true` 显示默认关闭按钮；值为 `false` 则不显示关闭按钮；也可以完全自定义关闭按钮。TS 类型：`boolean \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
+closeOnEscKeydown | Boolean | true | 按下 ESC 时是否触发图片预览器关闭事件 | N
 closeOnOverlay | Boolean | - | 是否在点击遮罩层时，触发预览关闭 | N
 draggable | Boolean | undefined | 是否允许拖拽调整位置。`mode=modal` 时，默认不允许拖拽；`mode=modeless` 时，默认允许拖拽 | N
 imageScale | Object | - |  图片缩放相关配置。`imageScale.max` 缩放的最大比例；`imageScale.min` 缩放的最小比例；`imageScale.step` 缩放的步长速度。TS 类型：`ImageScale` `interface ImageScale { max: number; min: number; step: number }`。[详细类型定义](https://github.com/Tencent/tdesign-vue/tree/develop/src/image-viewer/type.ts) | N
 images | Array | [] | 图片数组。`mainImage` 表示主图，必传；`thumbnail` 表示缩略图，如果不存在，则使用主图显示；`download` 是否允许下载图片，默认允许下载。示例: `['img_url_1', 'img_url_2']`，`[{ thumbnail: 'small_image_url', mainImage: 'big_image_url', download: false }]`。TS 类型：`Array<string \| File \| ImageInfo>` `interface ImageInfo { mainImage: string \| File; thumbnail?: string \| File; download?: boolean }`。[详细类型定义](https://github.com/Tencent/tdesign-vue/tree/develop/src/image-viewer/type.ts) | N
-index | Number | - | 当前预览图片所在的下标。支持语法糖 `.sync` | N
-defaultIndex | Number | - | 当前预览图片所在的下标。非受控属性 | N
+index | Number | 0 | 当前预览图片所在的下标。支持语法糖 `.sync` | N
+defaultIndex | Number | 0 | 当前预览图片所在的下标。非受控属性 | N
 mode | String | modal | 模态预览（modal）和非模态预览（modeless)。可选项：modal/modeless | N
 navigationArrow | Boolean / Slot / Function | true | 切换预览图片的左图标，可自定义。TS 类型：`boolean \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
 showOverlay | Boolean | undefined | 是否显示遮罩层。`mode=modal` 时，默认显示；`mode=modeless` 时，默认不显示 | N
 title | String / Slot / Function | - | 预览标题。TS 类型：`string \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
-trigger | String / Slot / Function | - | 触发图片预览的元素，可能是一个预览按钮，可能是一张缩略图，完全自定义。TS 类型：`string \| TNode<{ open: () => void }>`。[通用类型定义](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
+trigger | String / Slot / Function | - | 触发图片预览的元素，可能是一个预览按钮，可能是一张缩略图，完全自定义。TS 类型：`TNode \| TNode<{ open: () => void }>`。[通用类型定义](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
 viewerScale | Object | - | 限制预览器缩放的最小宽度和最小高度，仅 `mode=modeless` 时有效。TS 类型：`ImageViewerScale` `interface ImageViewerScale { minWidth: number; minHeight: number }`。[详细类型定义](https://github.com/Tencent/tdesign-vue/tree/develop/src/image-viewer/type.ts) | N
 visible | Boolean | false | 隐藏/显示预览。支持语法糖 `v-model` | N
+defaultVisible | Boolean | false | 隐藏/显示预览。非受控属性 | N
 zIndex | Number | - | 层级，默认为 2000 | N
 onClose | Function |  | TS 类型：`(context: { trigger: 'close-btn' \| 'overlay' \| 'esc'; e: MouseEvent \| KeyboardEvent }) => void`<br/>关闭时触发，事件参数包含触发关闭的来源：关闭按钮、遮罩层、ESC 键 | N
 onIndexChange | Function |  | TS 类型：`(index: number, context: { trigger: 'prev' \| 'next' \| 'current' }) => void`<br/>预览图片切换时触发，`context.prev` 切换到上一张图片，`context.next` 切换到下一张图片 | N

diff --git a/src/image-viewer/image-viewer.tsx b/src/image-viewer/image-viewer.tsx
@@ -128,7 +128,9 @@ export default defineComponent({
           onZoomOut();
           break;
         case EVENT_CODE.esc:
-          onCloseHandle({ e, trigger: 'esc' });
+          if (props.closeOnEscKeydown) {
+            onCloseHandle({ e, trigger: 'esc' });
+          }
           break;
         default:
           break;

diff --git a/src/image-viewer/props.ts b/src/image-viewer/props.ts
@@ -13,6 +13,11 @@ export default {
     type: [Boolean, Function] as PropType<TdImageViewerProps['closeBtn']>,
     default: true,
   },
+  /** 按下 ESC 时是否触发图片预览器关闭事件 */
+  closeOnEscKeydown: {
+    type: Boolean,
+    default: true,
+  },
   /** 是否在点击遮罩层时，触发预览关闭 */
   closeOnOverlay: Boolean,
   /** 是否允许拖拽调整位置。`mode=modal` 时，默认不允许拖拽；`mode=modeless` 时，默认允许拖拽 */
@@ -37,6 +42,7 @@ export default {
   /** 当前预览图片所在的下标，非受控属性 */
   defaultIndex: {
     type: Number,
+    default: 0,
   },
   /** 模态预览（modal）和非模态预览（modeless) */
   mode: {

diff --git a/src/image-viewer/type.ts b/src/image-viewer/type.ts
@@ -12,6 +12,11 @@ export interface TdImageViewerProps {
    * @default true
    */
   closeBtn?: boolean | TNode;
+  /**
+   * 按下 ESC 时是否触发图片预览器关闭事件
+   * @default true
+   */
+  closeOnEscKeydown?: boolean;
   /**
    * 是否在点击遮罩层时，触发预览关闭
    */
@@ -31,10 +36,12 @@ export interface TdImageViewerProps {
   images?: Array<string | File | ImageInfo>;
   /**
    * 当前预览图片所在的下标
+   * @default 0
    */
   index?: number;
   /**
    * 当前预览图片所在的下标，非受控属性
+   * @default 0
    */
   defaultIndex?: number;
   /**
@@ -58,7 +65,7 @@ export interface TdImageViewerProps {
   /**
    * 触发图片预览的元素，可能是一个预览按钮，可能是一张缩略图，完全自定义
    */
-  trigger?: string | TNode<{ open: () => void }>;
+  trigger?: TNode | TNode<{ open: () => void }>;
   /**
    * 限制预览器缩放的最小宽度和最小高度，仅 `mode=modeless` 时有效
    */

diff --git a/src/image-viewer/utils.ts b/src/image-viewer/utils.ts
@@ -26,7 +26,7 @@ export const downloadFile = function (imgSrc: string) {
   image.src = imgSrc;
 };
 
-const isImageInfo = (image: string | File | ImageInfo): image is ImageInfo => typeof image !== 'string' && !(image instanceof File);
+const isImageInfo = (image: string | File | ImageInfo): image is ImageInfo => !!image && typeof image !== 'string' && !(image instanceof File);
 
 export const formatImages = (images: TdImageViewerProps['images']): ImageInfo[] => {
   if (!Array.isArray(images)) return [];