UNPKG

6.48 kBTypeScriptView Raw
1import { ComponentType, ImgHTMLAttributes } from 'react'
2import { StandardProps, CommonEventFunction } from './common'
3interface ImageProps extends StandardProps {
4 /** 图片资源地址
5 * @supported weapp, alipay, swan, tt, qq, jd, h5, rn
6 */
7 src: string
8
9 /** 图片裁剪、缩放的模式
10 * @default "scaleToFill"
11 * @supported weapp, alipay, swan, tt, qq, jd, h5, rn
12 * @rn 部分支持 scaleToFill, aspectFit, aspectFill, widthFix
13 */
14 mode?: keyof ImageProps.Mode
15
16 /** 默认不解析 webP 格式，只支持网络资源
17 * @default false
18 * @supported weapp, swan
19 */
20 webp?: boolean
21
22 /** 默认不解析 svg 格式，svg 图片只支持 aspectFit
23 * @default false
24 * @supported rn
25 */
26 svg?: boolean
27
28 /** 图片懒加载。只针对 page 与 scroll-view 下的 image 有效
29 * @default false
30 * @supported weapp, alipay, swan, tt, qq, h5
31 */
32 lazyLoad?: boolean
33
34 /** 开启长按图片显示识别小程序码菜单
35 * @default false
36 * @supported weapp
37 */
38 showMenuByLongpress?: boolean
39
40 /**
41 * 为 img 标签额外增加的属性
42 * @supported h5
43 */
44 imgProps?: ImgHTMLAttributes<HTMLImageElement>
45
46 /** 用于透传 `WebComponents` 上的属性到内部 H5 标签上
47 * @supported h5
48 */
49 nativeProps?: Record<string, unknown>
50
51 /** 默认图片地址，若设置默认图片地址，会先显示默认图片，等 src 对应的图片加载成功后，再渲染对应的图片。
52 * @supported alipay
53 */
54 defaultSource?: string
55
56 /** 阻止长按图片时弹起默认菜单（即将该属性设置为image-menu-prevent="true"或image-menu-prevent），只在初始化时有效，不能动态变更；若不想阻止弹起默认菜单，则不需要设置此属性。注：长按菜单后的操作暂不支持 svg 格式
57 * @supported swan
58 */
59 imageMenuPrevent?: string
60
61 /** 点击后是否预览图片。在不设置的情况下，若 image 未监听点击事件且宽度大于 1/4 屏宽，则默认开启
62 * @supported swan
63 */
64 preview?: string
65
66 /** 预览时显示的图片地址
67 * @supported swan
68 */
69 originalSrc?: string
70
71 /** 无障碍访问，（属性）元素的额外描述
72 * @supported qq
73 */
74 ariaLabel?: string
75
76 /** 当错误发生时，发布到 AppService 的事件名，事件对象
77 * @supported weapp, alipay, swan, tt, qq, jd, h5, rn
78 */
79 onError?: CommonEventFunction<ImageProps.onErrorEventDetail>
80
81 /** 当图片载入完毕时，发布到 AppService 的事件名，事件对象
82 * @supported weapp, alipay, swan, tt, qq, jd, h5, rn
83 */
84 onLoad?: CommonEventFunction<ImageProps.onLoadEventDetail>
85
86 /** 点击图片时触发。
87 * @supported alipay
88 */
89 onTap?: CommonEventFunction
90
91 /** 点击图片时触发，阻止事件冒泡。
92 * @supported alipay
93 */
94 catchTap?: CommonEventFunction
95}
96declare namespace ImageProps {
97 /** mode 的合法值 */
98 interface Mode {
99 /** 缩放模式，不保持纵横比缩放图片，使图片的宽高完全拉伸至填满 image 元素 */
100 scaleToFill
101
102 /** 缩放模式，保持纵横比缩放图片，使图片的长边能完全显示出来。也就是说，可以完整地将图片显示出来。 */
103 aspectFit
104
105 /** 缩放模式，保持纵横比缩放图片，只保证图片的短边能完全显示出来。也就是说，图片通常只在水平或垂直方向是完整的，另一个方向将会发生截取。 */
106 aspectFill
107
108 /** 缩放模式，宽度不变，高度自动变化，保持原图宽高比不变 */
109 widthFix
110
111 /** 缩放模式，高度不变，宽度自动变化，保持原图宽高比不变 */
112 heightFix
113
114 /** 裁剪模式，不缩放图片，只显示图片的顶部区域 */
115 top
116
117 /** 裁剪模式，不缩放图片，只显示图片的底部区域 */
118 bottom
119
120 /** 裁剪模式，不缩放图片，只显示图片的中间区域 */
121 center
122
123 /** 裁剪模式，不缩放图片，只显示图片的左边区域 */
124 left
125
126 /** 裁剪模式，不缩放图片，只显示图片的右边区域 */
127 right
128
129 /** 裁剪模式，不缩放图片，只显示图片的左上边区域 */
130 'top left'
131
132 /** 裁剪模式，不缩放图片，只显示图片的右上边区域 */
133 'top right'
134
135 /** 裁剪模式，不缩放图片，只显示图片的左下边区域 */
136 'bottom left'
137
138 /** 裁剪模式，不缩放图片，只显示图片的右下边区域 */
139 'bottom right'
140 }
141 interface onErrorEventDetail {
142 /** 错误信息 */
143 errMsg: string
144 }
145 interface onLoadEventDetail {
146 /** 图片高度 */
147 height: number | string
148
149 /** 图片宽度 */
150 width: number | string
151 }
152}
153
154/** 图片。支持 JPG、PNG、SVG、WEBP、GIF 等格式以及云文件ID。
155 *
156 * **Note:** 为实现小程序的 `mode` 特性，在 H5 组件中使用一个 `div` 容器来对内部的 `img` 进行展示区域的裁剪，因此请勿使用元素选择器来重置 `img` 的样式！
157 * @classification media
158 * @supported weapp, alipay, swan, tt, qq, jd, h5, rn, harmony
159 * @example_react
160 * ```tsx
161 * export default class PageView extends Component {
162 * constructor() {
163 * super(...arguments)
164 * }
165 *
166 * render() {
167 * return (
168 * <View className='components-page'>
169 * <Image
170 * style='width: 300px;height: 100px;background: #fff;'
171 * src='nerv_logo.png'
172 * />
173 * <Image
174 * style='width: 300px;height: 100px;background: #fff;'
175 * src='https://camo.githubusercontent.com/3e1b76e514b895760055987f164ce6c95935a3aa/687474703a2f2f73746f726167652e333630627579696d672e636f6d2f6d74642f686f6d652f6c6f676f2d3278313531333833373932363730372e706e67'
176 * />
177 * </View>
178 * )
179 * }
180 * }
181 * ```
182 * @example_vue
183 * ```html
184 * <template>
185 * <view class="components-page">
186 * <image
187 * style="width: 300px;height: 100px;background: #fff;"
188 * src="nerv_logo.png"
189 * />
190 * <image
191 * style="width: 300px;height: 100px;background: #fff;"
192 * src="https://camo.githubusercontent.com/3e1b76e514b895760055987f164ce6c95935a3aa/687474703a2f2f73746f726167652e333630627579696d672e636f6d2f6d74642f686f6d652f6c6f676f2d3278313531333833373932363730372e706e67"
193 * />
194 * </view>
195 * </template>
196 * ```
197 * @see https://developers.weixin.qq.com/miniprogram/dev/component/image.html
198 */
199declare const Image: ComponentType<ImageProps>
200export { Image, ImageProps }