magic-img
v0.4.2
Published
让你的图片加载更加优雅
Downloads
48
Maintainers
Readme
magic-img
English | 简体中文
Make img loading more elegant
demo
Before
After
Feature
- no framework limitations - base on Web Components
- lazy load - base on Intersection Observer API
- support load remote url
- mode
- blurhash - blurred algorithm generates placeholder image
- lqip - transition based on thumbnail base64 image
- sqip - transition based on SVG outline, with customizable outline and filters
- cucoloris - transition with silhouette, customizable color and background color
- draw - transition with a dynamic brush, customizable brush color
- support - jpg,jpeg,png,gif,webp
- [custom duration](#custom duration)
- integration
Behavior
You may notice that after the first load of the image, the transition animation is hardly visible on subsequent loads. This is intentional, as we are addressing the issue of white space during image loading. However, typically the image is cached by the browser after the initial load, so there is no need to waste time loading the transition animation again on subsequent visits. If your images do not use caching policies, the transition animation will still be loaded.
Install
npm install magic-img
Useage
Load_Methods
// magic = blurhash|lqip|sqip|cucoloris|draw
import img from './home.png?magic=lqip'
// 可拼接参数
import img from './home.png?magic=sqip&numberOfPrimitives=100&blur=0'
// 加载远程链接
import img from 'magic-img@https://cdn.pixabay.com/photo/2013/07/18/20/26/sea-164989__480.jpg?magic=lqip'
Web Component
Web component is good at across framework, but not good at ssr
// main.js
import installMagicImg from 'magic-img'
import 'magic-img/css'
installMagicImg()
// vue
<magic-img :src='img'>
// react
<magic-img src={ img }>
// ... 其他技术栈
For SSR needs, you can avoid using web components and use one of the following frameworks (list is continuously growing...)
Vue2.7+,3
import 'magic-img/css'
import MagicImg from 'magic-img/vue2'
// import MagicImg from 'magic-img/vue3' // vue3
Vue.use(MagicImg)
<MagicImg :src='img' />
React >= 16.18
import 'magic-img/css'
import MagicImg from 'magic-img/react'
<MagicImg :src='img' />
Vite
// vite.config.js
import magicImg from 'magic-img/vite';
export default {
plugins: [
magicImg(/* options */)
]
}
Webpack
// webpack.config.js
const magicImg = require('magic-img/webpack').default;
module.exports = {
plugins: [
magicImg(/* options */)
]
}
Options
- blurhash
- w (number) - thumbnail width(this refers to the compressed width value, not the actual display) (default: 20)
- h (number) - thumbnail height
- componentX (number) (default: 4)
- componentY (number) (default: 4)
- punch (number) - contrast ratio
- hash (string) - custom hash,default by img
- lqip
- w (number) - thumbnail width (default: 20)
- h (number) - thumbnail height
- sqip
- numberOfPrimitives (number) - the number of generated outlines (default: 20)
- blur (number) (default: 2)
- mode (number) (default: 0) 0=combo, 1=triangle, 2=rect, 3=ellipse, 4=circle, 5=rotatedrect, 6=beziers, 7=rotatedellipse, 8=polygon
- cucoloris
- background (string) (default: '#fff')
- color (string) (default: '#c7d4d8')
- threshold (number) - threshold (default: 120)
- draw
- w (number) - thumbnail width (default: 400)
- h (number) - thumbnail height
Custom Options
Global Options
// vite.config.js
import magicImg from 'magic-img/vite';
export default {
plugins: [
magicImg({
sqip: {
numberOfPrimitives: 100,
blur: 0,
}
})
]
}
Custom Duration
you can custom animation duration
migic-img dom construction
<magic-img>
<!-- 占位元素,可能是 img,svg -->
<placeholder class='magic-placeholder' />
<!-- 最终展示图片 -->
<target class='magic-target' />
</magic-img>
Duration
- default - default style
- from - when el inside window placeholder,target will be set status=from
- to - img is loaded placeholder,target will be set status=to
Example
<magic-img src='xxx' class='my-style'>
.my-style .magic-placeholder {
filter: blur(10px)
}
.my-style .magic-target[status=from] {
border: 1px solid;
}
.my-style .magic-target[status=to] {
opacity: 1;
filter: grayscale(1);
transition: all 4s;
}
Notice
in vue, custom element need registry
Vue2
Vue.config.ignoredElements = [
'magic-img',
]
Vue3 + Vite
// vite.config.js
import vue from '@vitejs/plugin-vue'
export default {
plugins: [
vue({
template: {
compilerOptions: {
isCustomElement: (tag) => tag.includes('magic-img')
}
}
})
]
}
Vue3 + Vue-cli
// vue.config.js
module.exports = {
chainWebpack: config => {
config.module
.rule('vue')
.use('vue-loader')
.tap(options => ({
...options,
compilerOptions: {
// treat any tag that starts with ion- as custom elements
isCustomElement: tag => tag.startsWith('magic-img')
}
}))
}
}