flex-image-viewer 1.0.0

package/README.md

@@ -0,0 +1,160 @@
+# flex-image-viewer
+
+一个功能丰富的 React 图片查看器组件，支持缩放、旋转、缩略图导航、信息面板等交互功能。
+
+## 特性
+
+- **图片浏览** — 支持多张图片切换浏览，可配置循环模式
+- **缩放操作** — 支持放大、缩小、自适应缩放，以及鼠标滚轮缩放
+- **旋转功能** — 支持左旋、右旋
+- **缩略图导航** — 底部缩略图列表，快速定位图片
+- **信息面板** — 展示图片详细信息（尺寸、大小等）
+- **EXIF 方向识别** — 自动识别并应用图片的 EXIF 方向信息
+- **预加载** — 支持图片预加载以提升浏览体验
+- **禁用右键** — 支持禁用图片右键菜单
+- **自定义操作** — 头部和底部操作栏支持自定义渲染
+- **加载状态** — 图片加载时显示加载指示器
+
+## 安装
+
+```bash
+pnpm install
+```
+
+## 使用
+
+```tsx
+import { FlexImageViewer, ActionItem } from 'flex-image-viewer';
+import type { FileData } from 'flex-image-viewer';
+
+function App() {
+  const [visible, setVisible] = useState(false);
+  const [current, setCurrent] = useState(1);
+
+  const files: FileData[] = [
+    {
+      name: 'image1.png',
+      src: 'https://example.com/image1.png',
+      alt: '图片1',
+      width: 1920,
+      height: 1080,
+      size: '2.5 MB',
+      infoData: [
+        { label: '尺寸', value: '1920x1080' },
+        { label: '格式', value: 'PNG' },
+      ],
+    },
+  ];
+
+  return (
+    <>
+      <button onClick={() => setVisible(true)}>打开查看器</button>
+      <FlexImageViewer
+        files={files}
+        visible={visible}
+        current={current}
+        onClose={() => setVisible(false)}
+        onIndexChange={setCurrent}
+        wheelZoom
+        disableRightClick={false}
+      />
+    </>
+  );
+}
+```
+
+## Props
+
+| 属性              | 类型                                     | 默认值  | 说明                          |
+| ----------------- | ---------------------------------------- | ------- | ----------------------------- |
+| files             | `FileData[]`                             | `[]`    | 图片数据列表                  |
+| current           | `number`                                 | `1`     | 当前显示的图片索引（从1开始） |
+| visible           | `boolean`                                | -       | 是否显示查看器                |
+| loop              | `boolean`                                | `false` | 是否循环浏览                  |
+| onClose           | `() => void`                             | -       | 关闭回调                      |
+| onIndexChange     | `(index: number) => void`                | -       | 图片切换回调                  |
+| onClear           | `() => void`                             | -       | 重置操作回调                  |
+| wheelZoom         | `boolean`                                | `true`  | 是否启用鼠标滚轮缩放          |
+| wheelZoomStep     | `number`                                 | `0.1`   | 滚轮缩放步长                  |
+| preload           | `boolean`                                | `false` | 是否预加载图片                |
+| disableRightClick | `boolean`                                | `false` | 是否禁用右键菜单              |
+| getSrc            | `(file: T) => Promise<string> \| string` | -       | 自定义获取原图地址            |
+| getThumbnail      | `(file: T) => Promise<string> \| string` | -       | 自定义获取缩略图地址          |
+| renderInfo        | `(file: T) => ReactNode`                 | -       | 自定义信息面板渲染            |
+| headerProps       | `{ renderAction? }`                      | -       | 头部操作栏配置                |
+| footerProps       | `{ renderAction? }`                      | -       | 底部操作栏配置                |
+
+## FileData 数据结构
+
+```ts
+interface FileData {
+  name?: string; // 文件名
+  description?: string; // 描述
+  src?: string; // 图片地址
+  alt?: string; // 替代文本
+  size?: string; // 文件大小
+  width?: string | number; // 图片宽度
+  height?: string | number; // 图片高度
+  angle?: number; // 旋转角度
+  scale?: number; // 缩放比例
+  infoData?: { label: string; value: string }[]; // 信息面板数据
+  orientation?: number; // EXIF 方向值
+}
+```
+
+## 开发
+
+### 启动开发模式
+
+```bash
+pnpm run dev
+```
+
+### 构建
+
+```bash
+pnpm run build
+```
+
+### 运行测试
+
+```bash
+pnpm run test
+```
+
+### 启动 Storybook
+
+```bash
+pnpm run storybook
+```
+
+### 启动文档站点
+
+```bash
+pnpm run doc
+```
+
+### 代码检查
+
+```bash
+pnpm run lint
+```
+
+### 代码格式化
+
+```bash
+pnpm run format
+```
+
+## 技术栈
+
+- React 19
+- TypeScript
+- Rslib（构建工具）
+- ahooks
+- es-toolkit
+- rc-slider / rc-tooltip
+
+## License
+
+MIT

package/dist/FlexImageViewer/Content/index.js

@@ -0,0 +1,193 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useState } from "react";
+import { useViewerDispatch, useViewerState } from "../../context/ViewerContext.js";
+import { Icon, Image } from "../../components/index.js";
+function Content(props) {
+    const { preload = true, wheelZoom, wheelZoomStep, disableRightClick, getSrc } = props;
+    const state = useViewerState();
+    const dispatch = useViewerDispatch();
+    const current = state.currentIndex;
+    const files = state.files;
+    const imageOptions = state.imageOptions;
+    const [displayIndices, setDisplayIndices] = useState([]);
+    useEffect(()=>{
+        const index = current - 1;
+        if (!files || 0 === files.length) return void setDisplayIndices([]);
+        let list = [];
+        if (preload) {
+            const prevIndex = index > 0 ? index - 1 : null;
+            const nextIndex = index < files.length - 1 ? index + 1 : null;
+            list = [
+                prevIndex,
+                index,
+                nextIndex
+            ];
+        } else list = [
+            index
+        ];
+        const newIndices = list.filter((idx)=>null !== idx);
+        setDisplayIndices(newIndices);
+    }, [
+        current,
+        files,
+        preload
+    ]);
+    const index = current - 1;
+    const handleAdapt = useCallback((zoom)=>{
+        dispatch({
+            type: 'ADAPT_ZOOM',
+            payload: {
+                index,
+                scale: zoom
+            }
+        });
+    }, [
+        dispatch,
+        index
+    ]);
+    const handleWheelZoom = useCallback((scale)=>{
+        dispatch({
+            type: 'SET_ZOOM',
+            payload: {
+                index,
+                scale
+            }
+        });
+    }, [
+        dispatch,
+        index
+    ]);
+    const handleOrientation = useCallback((displayIndex, orientation)=>{
+        dispatch({
+            type: 'UPDATE_FILE',
+            payload: {
+                index: displayIndex,
+                file: {
+                    orientation
+                }
+            }
+        });
+    }, [
+        dispatch
+    ]);
+    useEffect(()=>{
+        const handleKeyDown = (e)=>{
+            switch(e.key){
+                case 'ArrowLeft':
+                    e.preventDefault();
+                    dispatch({
+                        type: 'PREV_IMAGE'
+                    });
+                    break;
+                case 'ArrowRight':
+                    e.preventDefault();
+                    dispatch({
+                        type: 'NEXT_IMAGE'
+                    });
+                    break;
+                case '+':
+                case '=':
+                    e.preventDefault();
+                    dispatch({
+                        type: 'ZOOM_IN',
+                        payload: {
+                            index,
+                            step: 0.1
+                        }
+                    });
+                    break;
+                case '-':
+                    e.preventDefault();
+                    dispatch({
+                        type: 'ZOOM_OUT',
+                        payload: {
+                            index,
+                            step: 0.1
+                        }
+                    });
+                    break;
+                case 'r':
+                case 'R':
+                    e.preventDefault();
+                    {
+                        const file = files[index];
+                        dispatch({
+                            type: 'CLEAR_IMAGE',
+                            payload: {
+                                index,
+                                angle: file?.angle ?? 0,
+                                scale: file?.scale ?? 1
+                            }
+                        });
+                    }
+                    break;
+            }
+        };
+        document.addEventListener('keydown', handleKeyDown);
+        return ()=>{
+            document.removeEventListener('keydown', handleKeyDown);
+        };
+    }, [
+        dispatch,
+        index,
+        files
+    ]);
+    return /*#__PURE__*/ jsxs("main", {
+        className: "flex-image-viewer-content",
+        "aria-label": "图片内容",
+        children: [
+            /*#__PURE__*/ jsx("div", {
+                className: "flex-image-viewer-content-tool-left",
+                children: /*#__PURE__*/ jsx("span", {
+                    onClick: ()=>dispatch({
+                            type: 'PREV_IMAGE'
+                        }),
+                    "aria-label": "上一张图片",
+                    role: "button",
+                    tabIndex: 0,
+                    children: /*#__PURE__*/ jsx(Icon, {
+                        name: "ArrowLeft"
+                    })
+                })
+            }),
+            /*#__PURE__*/ jsx("div", {
+                className: "flex-image-viewer-content-image",
+                children: displayIndices.map((displayIndex)=>{
+                    const isVisible = displayIndex === index;
+                    return /*#__PURE__*/ jsx(Image, {
+                        file: files?.[displayIndex],
+                        scale: imageOptions?.[displayIndex]?.scale,
+                        angle: imageOptions?.[displayIndex]?.angle,
+                        isAdapt: imageOptions?.[displayIndex]?.isAdapt,
+                        onAdapt: handleAdapt,
+                        wheelZoom: wheelZoom,
+                        wheelZoomStep: wheelZoomStep,
+                        onWheelZoom: handleWheelZoom,
+                        getSrc: getSrc,
+                        onOrientation: (orientation)=>handleOrientation(displayIndex, orientation),
+                        disableRightClick: disableRightClick,
+                        style: {
+                            display: isVisible ? 'flex' : 'none'
+                        }
+                    }, displayIndex);
+                })
+            }),
+            /*#__PURE__*/ jsx("div", {
+                className: "flex-image-viewer-content-tool-right",
+                children: /*#__PURE__*/ jsx("span", {
+                    onClick: ()=>dispatch({
+                            type: 'NEXT_IMAGE'
+                        }),
+                    "aria-label": "下一张图片",
+                    role: "button",
+                    tabIndex: 0,
+                    children: /*#__PURE__*/ jsx(Icon, {
+                        name: "ArrowRight"
+                    })
+                })
+            })
+        ]
+    });
+}
+const FlexImageViewer_Content = Content;
+export default FlexImageViewer_Content;

package/dist/FlexImageViewer/Footer/Actions.js

@@ -0,0 +1,115 @@
+import { jsx } from "react/jsx-runtime";
+import "react";
+import { BaseActions } from "../../components/index.js";
+import { useViewerDispatch, useViewerState } from "../../context/ViewerContext.js";
+const FOOTER_ITEMS = [
+    {
+        key: 'thumbnail',
+        type: 'icon',
+        tooltipKey: 'thumbnail',
+        iconName: 'Thumbnail'
+    },
+    {
+        key: 'info',
+        type: 'icon',
+        tooltipKey: 'info',
+        iconName: 'Info'
+    },
+    {
+        key: 'zoomAdapt',
+        type: 'icon',
+        tooltipKey: 'zoomAdapt',
+        iconName: 'ZoomAdapt'
+    },
+    {
+        key: 'zoomSelect',
+        type: 'select',
+        valueKey: 'zoom'
+    },
+    {
+        key: 'zoomOut',
+        type: 'icon',
+        tooltipKey: 'zoomOut',
+        iconName: 'ZoomOut'
+    },
+    {
+        key: 'zoomSlider',
+        type: 'slider',
+        valueKey: 'zoom'
+    },
+    {
+        key: 'zoomIn',
+        type: 'icon',
+        tooltipKey: 'zoomIn',
+        iconName: 'ZoomIn'
+    }
+];
+function Actions(props) {
+    const { zoom = 1, updateCurrentFile, renderAction } = props;
+    const dispatch = useViewerDispatch();
+    const state = useViewerState();
+    const index = state.currentIndex - 1;
+    const handleAction = (key, value, _event)=>{
+        switch(key){
+            case 'thumbnail':
+                dispatch({
+                    type: 'TOGGLE_THUMBNAIL'
+                });
+                break;
+            case 'info':
+                dispatch({
+                    type: 'TOGGLE_INFO'
+                });
+                break;
+            case 'zoomAdapt':
+                dispatch({
+                    type: 'ADAPT_ZOOM',
+                    payload: {
+                        index,
+                        scale: zoom / 100
+                    }
+                });
+                break;
+            case 'zoomSelect':
+            case 'zoomSlider':
+                if (void 0 !== value) dispatch({
+                    type: 'SET_ZOOM',
+                    payload: {
+                        index,
+                        scale: value / 100
+                    }
+                });
+                break;
+            case 'zoomOut':
+                dispatch({
+                    type: 'ZOOM_OUT',
+                    payload: {
+                        index,
+                        step: 0.1
+                    }
+                });
+                break;
+            case 'zoomIn':
+                dispatch({
+                    type: 'ZOOM_IN',
+                    payload: {
+                        index,
+                        step: 0.1
+                    }
+                });
+                break;
+        }
+    };
+    const context = {
+        zoom,
+        updateCurrentFile: updateCurrentFile ?? (()=>{})
+    };
+    return /*#__PURE__*/ jsx(BaseActions, {
+        items: FOOTER_ITEMS,
+        contextValues: context,
+        renderAction: renderAction,
+        onAction: handleAction
+    });
+}
+const Footer_Actions = Actions;
+export default Footer_Actions;

package/dist/FlexImageViewer/Footer/index.js

@@ -0,0 +1,56 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useViewerState } from "../../context/ViewerContext.js";
+import { Icon } from "../../components/index.js";
+import { shouldSwapDimensions } from "../../utils/exif.js";
+import Actions from "./Actions.js";
+function Footer({ renderAction, updateCurrentFile }) {
+    const state = useViewerState();
+    const zoom = (state.imageOptions[state.currentIndex - 1]?.scale ?? 1) * 100;
+    const files = state.files;
+    const current = state.currentIndex;
+    const fileData = files[current - 1];
+    const width = fileData?.width;
+    const height = fileData?.height;
+    const sizeArr = shouldSwapDimensions(fileData?.orientation) ? [
+        height,
+        width
+    ].filter(Boolean) : [
+        width,
+        height
+    ].filter(Boolean);
+    return /*#__PURE__*/ jsxs("footer", {
+        className: "flex-image-viewer-footer",
+        children: [
+            /*#__PURE__*/ jsxs("div", {
+                className: "flex-image-viewer-footer-title",
+                children: [
+                    2 === sizeArr.length && /*#__PURE__*/ jsxs("div", {
+                        className: "flex-image-viewer-footer-size",
+                        children: [
+                            /*#__PURE__*/ jsx(Icon, {
+                                name: "Size"
+                            }),
+                            sizeArr.join(' x ')
+                        ]
+                    }),
+                    !!fileData?.size && /*#__PURE__*/ jsxs("div", {
+                        className: "flex-image-viewer-footer-memory",
+                        children: [
+                            /*#__PURE__*/ jsx(Icon, {
+                                name: "Save"
+                            }),
+                            fileData?.size
+                        ]
+                    })
+                ]
+            }),
+            /*#__PURE__*/ jsx(Actions, {
+                zoom: zoom,
+                renderAction: renderAction,
+                updateCurrentFile: updateCurrentFile
+            })
+        ]
+    });
+}
+const FlexImageViewer_Footer = Footer;
+export default FlexImageViewer_Footer;

package/dist/FlexImageViewer/Header/Actions.js

@@ -0,0 +1,80 @@
+import { jsx } from "react/jsx-runtime";
+import "react";
+import { useViewerDispatch, useViewerState } from "../../context/ViewerContext.js";
+import { BaseActions } from "../../components/index.js";
+const HEADER_ITEMS = [
+    {
+        key: 'rotateLeft',
+        type: 'icon',
+        tooltipKey: 'rotateLeft',
+        iconName: 'RotateLeft',
+        tooltipPlacement: 'bottomRight'
+    },
+    {
+        key: 'rotateRight',
+        type: 'icon',
+        tooltipKey: 'rotateRight',
+        iconName: 'RotateRight',
+        tooltipPlacement: 'bottomRight'
+    },
+    {
+        key: 'clear',
+        type: 'icon',
+        tooltipKey: 'clear',
+        iconName: 'Clear',
+        tooltipPlacement: 'bottomRight'
+    },
+    {
+        key: 'close',
+        type: 'icon',
+        tooltipKey: 'close',
+        iconName: 'Close',
+        tooltipPlacement: 'bottomRight'
+    }
+];
+function Actions(props) {
+    const { rotate = 0, updateCurrentFile, renderAction, onClear, onClose } = props;
+    const dispatch = useViewerDispatch();
+    const state = useViewerState();
+    const index = state.currentIndex - 1;
+    const handleAction = (key, _value, event)=>{
+        switch(key){
+            case 'rotateLeft':
+                dispatch({
+                    type: 'ROTATE_LEFT',
+                    payload: {
+                        index
+                    }
+                });
+                break;
+            case 'rotateRight':
+                dispatch({
+                    type: 'ROTATE_RIGHT',
+                    payload: {
+                        index
+                    }
+                });
+                break;
+            case 'clear':
+                onClear?.();
+                break;
+            case 'close':
+                onClose?.(event);
+                break;
+        }
+    };
+    const context = {
+        rotate,
+        updateCurrentFile: updateCurrentFile ?? (()=>{}),
+        onClear,
+        onClose
+    };
+    return /*#__PURE__*/ jsx(BaseActions, {
+        items: HEADER_ITEMS,
+        contextValues: context,
+        renderAction: renderAction,
+        onAction: handleAction
+    });
+}
+const Header_Actions = Actions;
+export default Header_Actions;

package/dist/FlexImageViewer/Header/index.js

@@ -0,0 +1,42 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import "react";
+import { useViewerState } from "../../context/ViewerContext.js";
+import Actions from "./Actions.js";
+function Header({ renderAction, onClose, onClear, updateCurrentFile }) {
+    const state = useViewerState();
+    const current = state.currentIndex;
+    const total = state.filesLength;
+    const name = state.files[current - 1]?.name;
+    const rotate = state.imageOptions[current - 1]?.angle ?? 0;
+    return /*#__PURE__*/ jsxs("header", {
+        className: "flex-image-viewer-header",
+        children: [
+            /*#__PURE__*/ jsxs("div", {
+                className: "flex-image-viewer-header-title",
+                children: [
+                    /*#__PURE__*/ jsxs("div", {
+                        className: "flex-image-viewer-header-count",
+                        children: [
+                            current,
+                            "/",
+                            total
+                        ]
+                    }),
+                    /*#__PURE__*/ jsx("div", {
+                        className: "flex-image-viewer-header-name",
+                        children: name
+                    })
+                ]
+            }),
+            /*#__PURE__*/ jsx(Actions, {
+                rotate: rotate,
+                renderAction: renderAction,
+                onClose: onClose,
+                onClear: onClear,
+                updateCurrentFile: updateCurrentFile
+            })
+        ]
+    });
+}
+const FlexImageViewer_Header = Header;
+export default FlexImageViewer_Header;

package/dist/FlexImageViewer/Info/index.js

@@ -0,0 +1,52 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useCreation } from "ahooks";
+import { useViewerDispatch, useViewerState } from "../../context/ViewerContext.js";
+import { Icon } from "../../components/index.js";
+function Info(props) {
+    const { renderInfo } = props;
+    const state = useViewerState();
+    const dispatch = useViewerDispatch();
+    const visible = state.infoVisible;
+    const files = state.files;
+    const current = state.currentIndex;
+    const fileData = files[current];
+    const content = useCreation(()=>renderInfo ? renderInfo(fileData) : /*#__PURE__*/ jsx("ul", {
+            children: fileData?.infoData?.map((item, index)=>/*#__PURE__*/ jsxs("li", {
+                    children: [
+                        /*#__PURE__*/ jsxs("span", {
+                            children: [
+                                item.label,
+                                "："
+                            ]
+                        }),
+                        /*#__PURE__*/ jsx("p", {
+                            children: item.value
+                        })
+                    ]
+                }, index))
+        }), [
+        fileData,
+        renderInfo
+    ]);
+    return /*#__PURE__*/ jsxs("div", {
+        className: `flex-image-viewer-info ${visible ? 'visible' : ''}`,
+        children: [
+            /*#__PURE__*/ jsx("div", {
+                className: "flex-image-viewer-info-tool",
+                children: /*#__PURE__*/ jsx("span", {
+                    "aria-label": "切换信息面板",
+                    role: "button",
+                    tabIndex: 0,
+                    onClick: ()=>dispatch({
+                            type: 'TOGGLE_INFO'
+                        }),
+                    children: /*#__PURE__*/ jsx(Icon, {
+                        name: "CaretRight"
+                    })
+                })
+            }),
+            content
+        ]
+    });
+}
+export default Info;