{"id":13534149,"url":"https://github.com/Caldis/react-zmage","last_synced_at":"2025-04-01T22:31:16.321Z","repository":{"id":21317387,"uuid":"108383378","full_name":"Caldis/react-zmage","owner":"Caldis","description":"一个基于 React 的可缩放图片控件 | A scalable image wrapper power by react","archived":false,"fork":false,"pushed_at":"2022-12-11T19:23:10.000Z","size":14377,"stargazers_count":921,"open_issues_count":79,"forks_count":95,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-31T19:11:26.705Z","etag":null,"topics":["animation","es6","image","img","javascript","js","react","react-zmage","slide","slider","slidershow","website","zmage","zoom","zoomer"],"latest_commit_sha":null,"homepage":"https://zmage.caldis.me","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Caldis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-26T08:29:35.000Z","updated_at":"2025-03-31T05:00:56.000Z","dependencies_parsed_at":"2022-07-10T13:47:29.464Z","dependency_job_id":null,"html_url":"https://github.com/Caldis/react-zmage","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Caldis%2Freact-zmage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Caldis%2Freact-zmage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Caldis%2Freact-zmage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Caldis%2Freact-zmage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Caldis","download_url":"https://codeload.github.com/Caldis/react-zmage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246523874,"owners_count":20791444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["animation","es6","image","img","javascript","js","react","react-zmage","slide","slider","slidershow","website","zmage","zoom","zoomer"],"created_at":"2024-08-01T07:01:27.018Z","updated_at":"2025-04-01T22:31:16.295Z","avatar_url":"https://github.com/Caldis.png","language":"JavaScript","readme":"[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/facebook/react/blob/master/LICENSE) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md#pull-requests)\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n  \u003ca href=\"https://github.com/Caldis/react-zmage\"\u003e\r\n    \u003cimg width=\"150\" height=\"150\" src=\"docs/logo.png\"\u003e\r\n  \u003c/a\u003e\r\n  \u003ch1\u003ereact-zmage\u003c/h1\u003e\r\n\u003c/div\u003e\r\n\r\n\u003e react-zmage 是一个基于 React 的的图片缩放控件, 使用 Zmage 标签包裹后的图片可以获得缩放效果, 您可以用这个控件替代原生的 img 标签, 令其附带图片缩放功能\r\n\r\n**需 react 版本大于 v16.6.0**\r\n\u003ch2 align=\"center\"\u003e演示\u003c/h2\u003e\r\n\r\n**在线**\r\n\r\n[https://zmage.caldis.me](https://zmage.caldis.me)\r\n\r\n\r\n**本地**\r\n```bash\r\ngit clone https://github.com/Caldis/react-zmage\r\ncd react-zmage\r\nnpm i\r\nnpm run dev\r\n```\r\n\r\n\r\n\u003ch2 align=\"center\"\u003e安装\u003c/h2\u003e\r\n\r\n```bash\r\nnpm i react-zmage --save\r\n```\r\n\r\n\r\n\u003ch2 align=\"center\"\u003e使用\u003c/h2\u003e\r\n\r\n\r\n#### 1.引入组件\r\n```js\r\nimport Zmage from 'react-zmage'\r\n```\r\n\r\n#### 2.将页面中的 img 标签替换为 Zmage 组件\r\n```js\r\n\u003cimg src=\"图片源连接\"/\u003e\r\n👆 to 👇\r\n\u003cZmage src=\"图片源连接\"/\u003e\r\n```\r\n\u003ch6\u003e现在这些图片都可以放大查看了 ！\u003c/h6\u003e\r\n\r\n#### 也可以通过函数调用来唤出图片\r\n```js\r\n// Zmage.browsing 函数接受的参数与 \u003cZmage/\u003e 组件完全一致\r\n\u003ca onClick={() =\u003e Zmage.browsing({ src:imagePath })}\u003e任意元素\u003c/a\u003e\r\n```\r\n\r\n#### 在`typescript`中使用\r\n\r\n```typescript\r\nimport ReactZmage from 'react-zmage';\r\n\r\n// 在生命周期等方法中使用\r\npublic componentDidMount() {\r\n    const zmage = new ReactZmage({\r\n        // ...options\r\n    });\r\n}\r\n\r\n// 也支持组件方式使用\r\npublic render(): JSX.Element {\r\n    const defaultConfig = {\r\n        src: 'http://zmage.caldis.me/imgSet/childsDream/demo.jpg',\r\n        alt: '示例图片',\r\n    };\r\n\r\n    return (\r\n        \u003cReactZmage\r\n            {...defaultConfig}\r\n        /\u003e\r\n    );\r\n}\r\n```\r\n\r\n\u003ch2 align=\"center\"\u003e基础配置\u003c/h2\u003e\r\n\u003ch6 align=\"center\"\u003e立即上手, 你仅仅需要了解下面的几个参数就足够了\u003c/h6\u003e\r\n\r\n#### 在线示例, 请参见 [https://zmage.caldis.me](https://zmage.caldis.me)\r\n\r\n- 基础调用属性\r\n\r\n|配置项|类型|默认值|描述|示例|\r\n|:--:|:--:|:-----:|:----------|:----------:|\r\n| **`src`** | String | \"\" | 图片 Url，与 `img` 标签的 `src` 属性相同 | [示例](https://github.com/Caldis/react-zmage#src) |\r\n| **`alt`** | String | \"\" | 图片占位文字，与 `img` 标签的 `alt` 属性相同 | [示例](https://github.com/Caldis/react-zmage#alt) |\r\n| **`set`** | Object[] | [] | 序列图片, 可以在 `set` 中传入多个图片对象用于在查看模式下呈现多张图片，也可用于呈现放大后的高清图片 | [示例](https://github.com/Caldis/react-zmage#set) |\r\n| **`defaultPage`** | Number | 0 | 如果传入了`set`来展示多张图片, 可以用于指定打开后的默认页 | [示例](https://github.com/Caldis/react-zmage#defaultPage) |\r\n\r\n\u003ch2 align=\"center\"\u003e高级配置\u003c/h2\u003e\r\n\u003ch6 align=\"center\"\u003e不需要了解这些参数也可以很好的使用, 但如果你需要更详细的定制, 可以进一步查阅下面的内容\u003c/h2\u003e\r\n\r\n- 预设配置 (beta)\r\n\r\n|配置项|类型|默认值|描述|示例|\r\n|:--:|:--:|:-----:|:----------|:----------:|\r\n| **`preset`** | String | \"auto\" | 轻松配置界面的功能及样式, 可设置为 `auto` `desktop` `mobile` | [示例](https://github.com/Caldis/react-zmage#preset) [受影响的配置项](https://github.com/Caldis/react-zmage/blob/master/src/config/default.js#L144) |\r\n\r\n- 受控属性\r\n\r\n|配置项|类型|默认值|描述|示例|\r\n|:--:|:--:|:-----:|:---------------|:----------:|\r\n| **`browsing`** | Boolean | empty | 控制是否进入查看模式 | [示例](https://github.com/Caldis/react-zmage#browsing) |\r\n\r\n- 功能控制\r\n\r\n|配置项|类型|默认值|描述|示例|\r\n|:--:|:--:|:-----:|:---------------|:----------:|\r\n| **`controller`** | [查看](https://github.com/Caldis/react-zmage/blob/9e13e09fe77b7944251af8b8d1b453c21d7e0445/src/config/default.js#L60) | [桌面](https://github.com/Caldis/react-zmage/blob/9e13e09fe77b7944251af8b8d1b453c21d7e0445/src/config/default.js#L136)\\|[移动](https://github.com/Caldis/react-zmage/blob/9e13e09fe77b7944251af8b8d1b453c21d7e0445/src/config/default.js#L156) | 将特定项设为 `false` 来隐藏查看模式下的操作控件 | [示例](https://github.com/Caldis/react-zmage#controller) |\r\n| **`hotKey`** | [查看](https://github.com/Caldis/react-zmage/blob/9e13e09fe77b7944251af8b8d1b453c21d7e0445/src/config/default.js#L76) | [桌面](https://github.com/Caldis/react-zmage/blob/9e13e09fe77b7944251af8b8d1b453c21d7e0445/src/config/default.js#L144)\\|[移动](https://github.com/Caldis/react-zmage/blob/9e13e09fe77b7944251af8b8d1b453c21d7e0445/src/config/default.js#L164) | 将特定项设为 `false` 来禁用查看模式下的快捷键 | [示例](https://github.com/Caldis/react-zmage#hotKey) |\r\n| **`animate`** | [查看](https://github.com/Caldis/react-zmage/blob/9e13e09fe77b7944251af8b8d1b453c21d7e0445/src/config/default.js#L88) | [桌面](https://github.com/Caldis/react-zmage/blob/9e13e09fe77b7944251af8b8d1b453c21d7e0445/src/config/default.js#L149)\\|[移动](https://github.com/Caldis/react-zmage/blob/9e13e09fe77b7944251af8b8d1b453c21d7e0445/src/config/default.js#L169) | 传入特定的参数指定翻页动画（browsing 动画暂不可配置） [可选值](https://github.com/Caldis/react-zmage/blob/9e13e09fe77b7944251af8b8d1b453c21d7e0445/src/config/default.js#L62) | [示例](https://github.com/Caldis/react-zmage#animate) |\r\n\r\n- 界面样式\r\n\r\n|配置项|类型|默认值|描述|示例|\r\n|:--:|:--:|:-----:|:----------|:----------:|\r\n| **`backdrop`** | String | \"#FFFFFF\" | 控制图片放大后的背景色 | [示例](https://github.com/Caldis/react-zmage#backdrop) |\r\n| **`zIndex`** | Number | 1000 | 控制外部容器的 `z-index`, 防止被其他元素遮挡 | [示例](https://github.com/Caldis/react-zmage#zIndex) |\r\n| **`radius`** | Number | [桌面](https://github.com/Caldis/react-zmage/blob/master/src/config/default.js#L160)\\|[移动](https://github.com/Caldis/react-zmage/blob/master/src/config/default.js#L178) | 控制图片在查看模式下的圆角 | [示例](https://github.com/Caldis/react-zmage#radius) |\r\n| **`edge`** | Number | [桌面](https://github.com/Caldis/react-zmage/blob/master/src/config/default.js#L161)\\|[移动](https://github.com/Caldis/react-zmage/blob/master/src/config/default.js#L179) | 控制图片在查看模式下距离屏幕边缘的距离 | [示例](https://github.com/Caldis/react-zmage#edge) |\r\n\r\n- 生命周期\r\n\r\n|配置项|类型|默认值|描述|示例|\r\n|:--:|:--:|:-----:|:----------|:----------:|\r\n| **`onBrowsing`** | func | (browsing)=\u003e{} | 生命周期方法, 在显示/隐藏时调用, 会回传显示状态 | [示例](https://github.com/Caldis/react-zmage#onBrowsing) |\r\n| **`onZooming`** | func | (zooming)=\u003e{} | 生命周期方法, 在放大/缩小时调用, 会回传缩放状态 | [示例](https://github.com/Caldis/react-zmage#onZooming) |\r\n| **`onSwitching`** | func | (paging)=\u003e{} | 生命周期方法, 在切换图片时调用, 会回传页码 | [示例](https://github.com/Caldis/react-zmage#onSwitching) |\r\n| **`onRotating`** | func | (deg)=\u003e{} | 生命周期方法, 在旋转图片时调用, 会回传角度 | [示例](https://github.com/Caldis/react-zmage#onRotating) |\r\n\r\n### `src`\r\n```js\r\n\"http://zmage.caldis.me/imgSet/childsDream/demo.jpg\"\r\n```\r\n\r\n### `alt`\r\n```js\r\n\"图片的占位文字，作为图片的标题, 请尽量保持简短\"\r\n```\r\n\r\n### `set`\r\n```js\r\n// 如果设置了 Set, 则进入查看模式后第一张图片将会是 set 的首图, 而不是 src\r\n// 如果你需要在查看模式中呈现高精度图片, 可以将其设置为 set 的首图, 或使用 defaultPage 指定\r\nset={[\r\n    {\r\n        // 图片 Url\r\n        src: \"http://zmage.caldis.me/imgSet/childsDream/1.jpg\",\r\n        // 图片占位文字\r\n        alt: \"图片的占位文字，作为图片的标题, 请尽量保持简短\",\r\n        // 图片样式\r\n        style: { borderRadius: 30 },\r\n        // 图片类名\r\n        className: 'testClassName'\r\n    },\r\n    {\r\n        // 另一个图片 Url\r\n        src: \"http://zmage.caldis.me/imgSet/childsDream/2.jpg\",\r\n        // 另一段图片占位文字\r\n        alt: \"图片的占位文字，作为图片的标题, 请尽量保持简短\",\r\n    }\r\n]}\r\n```\r\n\r\n### `defaultPage`\r\n```js\r\nset: [\r\n    {\r\n        // 图片 Url\r\n        src: \"http://zmage.caldis.me/imgSet/childsDream/1.jpg\",\r\n        // 图片占位文字\r\n        alt: \"图片的占位文字，尽量保持简短，描述图片作用\",\r\n    }\r\n]\r\n```\r\n\r\n### `browsing`\r\n```js\r\nbrowsing={this.state.contrlledZmageState}\r\n```\r\n\r\n### `controller`\r\n```js\r\ncontroller={{\r\n    // 关闭按钮\r\n    close: true,\r\n    // 缩放按钮\r\n    zoom: true,\r\n    // 下载按钮\r\n    download: true,\r\n    // 旋转按钮\r\n    rotate: true,\r\n    // 翻页按钮\r\n    flip: true,\r\n    // 多页指示\r\n    pagination: true,\r\n}}\r\n```\r\n\r\n### `hotKey`\r\n```js\r\nhotKey={{\r\n    // 关闭（ESC）\r\n    close: true,\r\n    // 缩放（空格）\r\n    zoom: true,\r\n    // 翻页（左右）\r\n    flip: true,\r\n}}\r\n```\r\n\r\n### `animate`\r\n```js\r\nanimate={{\r\n    flip: 'fade',\r\n}}\r\n```\r\n\r\n### `backdrop`\r\n```js\r\nbackdrop=\"linear-gradient(90deg, rgba(0,212,255,1) 0%, rgba(26,94,215,1) 100%)\"\r\n```\r\n\r\n### `zIndex`\r\n```js\r\nzIndex={19260817}\r\n```\r\n\r\n### `radius`\r\n```js\r\nradius={5}\r\n```\r\n\r\n### `edge`\r\n```js\r\nedge={20}\r\n```\r\n\r\n### `onBrowsing`\r\n```js\r\nonBrowsing={state =\u003e {\r\n    console.info(\"Browsing State: \", state)\r\n}}\r\n```\r\n\r\n### `onZooming`\r\n```js\r\nonZooming={state =\u003e {\r\n    console.info(\"Zooming State: \", state)\r\n}}\r\n```\r\n\r\n### `onSwitching`\r\n```js\r\nonSwitching={page =\u003e {\r\n    console.info(\"Switching page: \", page)\r\n}}\r\n```\r\n\r\n### `onRotating`\r\n```js\r\nonRotating={deg =\u003e {\r\n    console.info(\"Rotating State: \", deg, \"deg\")\r\n}}\r\n```\r\n\r\n\r\n\u003ch2 align=\"center\"\u003e贡献\u003c/h2\u003e\r\n\r\n我们随时欢迎发起一个 [PR](https://github.com/Caldis/react-zmage/pulls) 来帮助我们改进代码\r\n如果发现任何问题, 也欢迎 [发起一个ISSUE](https://github.com/Caldis/react-zmage/issues) 来反馈你的意见\r\n\r\n\u003ch2 align=\"center\"\u003e引用\u003c/h2\u003e\r\n- [Material Icons](https://material.io/tools/icons/)\r\n\r\n\u003ch2 align=\"center\"\u003e证书\u003c/h2\u003e\r\n\r\nreact-zmage 基于 [MIT licensed](./LICENSE) 发布\r\n","funding_links":[],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCaldis%2Freact-zmage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCaldis%2Freact-zmage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCaldis%2Freact-zmage/lists"}