Skip to content

Latest commit

 

History

History
202 lines (161 loc) · 7.79 KB

README.zh_CN.md

File metadata and controls

202 lines (161 loc) · 7.79 KB
Raw

unplugin-svg-component

English | 中文

NPM Version Downloads Stats

unplugin-svg-component 启发于vite-plugin-svg-icons,它将本地的svg文件生成为一个 vue/react 组件, 通过该组件结合svg文件的名称使用svg图标。

智能提示效果

Vue

image

React

image

功能

  • 智能提示: 使用组件时, 配合 Typescript 会提示出 svg 文件名称
  • 热更新: svg 文件的增删改操作, 都会实时显示于页面上, 无需刷新浏览器
  • Vue & React 支持: 自动检测项目类型
  • Tree-shaking: 从v0.5.0版本开始, 生产环境只会打包你用到的 svg 图标
  • SSR: 通过开启 option.domInsertionStrategy = 'replaceHtml' 这个选项(默认开启)支持SSR.

安装

yarn add unplugin-svg-component -D
# or
npm i unplugin-svg-component -D
# or
pnpm install unplugin-svg-component -D

使用

Vite config
// vite.config.ts
import UnpluginSvgComponent from 'unplugin-svg-component/vite'

export default defineConfig({
  plugins: [
    UnpluginSvgComponent({ /* options */ })
  ],
})


Vue-cli config
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
const UnpluginSvgComponent = require('unplugin-svg-component/webpack').default

module.exports = defineConfig({
  configureWebpack: {
    plugins: [
      UnpluginSvgComponent({ /* options */ })
    ]
  }
})


Webpack config
// webpack.config.js
const UnpluginSvgComponent = require('unplugin-svg-component/webpack').default

module.exports = {
  /* ... */
  plugins: [
    UnpluginSvgComponent({ /* options */ }),
  ],
}


Rollup config
// rollup.config.js
import UnpluginSvgComponent from 'unplugin-svg-component/rollup'

export default {
  plugins: [
    UnpluginSvgComponent({ /* options */ }),
  ],
}


Esbuild config
// esbuild.config.js
import { build } from 'esbuild'
import UnpluginSvgComponent from 'unplugin-svg-component/esbuild'

build({
  /* ... */
  plugins: [
    UnpluginSvgComponent({
      /* options */
    }),
  ],
})


Vue

// main.ts
import SvgIcon from '~virtual/svg-component'

app.component(SvgIcon.name, SvgIcon)

React

// App.tsx
import SvgIcon from '~virtual/svg-component'

function App() {
  return (
    <div className="logo">
      <SvgIcon name="icon-react"></SvgIcon>
    </div>
  )
}

获取svgNames / 类型 SvgName

// all svg icon name
import { svgNames } from '~virtual/svg-component'

// type SvgName = "icon-icon-addUser" | "icon-icon-barCode"
import type { SvgName } from '~virtual/svg-component'

插件配置

属性 类型 默认值 描述
iconDir string | string[] - 图标文件夹位置
projectType vue | react | auto auto 项目类型, 默认会自动检测
dts boolean - 是否生成d.ts文件
dtsDir string - d.ts文件位置
prefix string - 给每个svg name加上前缀,使用时记得加上这个前缀
componentName string SvgIcon 生成的组件名称
componentStyle string width: 1em; height: 1em; fill:currentColor; 组件的行内样式
preserveColor RegExp - 通常, 插件会把svg标签内的fill, stroke属性替换成currentColor, 此属性会对每个svg路径进行正则匹配, 匹配成功的svg则不会替换currentColor, 而是保留原有的颜色.
symbolIdFormatter (svgName:string, prefix: string)=>string code 可以通过这个参数来设置symbolId的格式
optimizeOptions SvgoOptions - svgo 的优化参数
svgSpriteDomId string svg_sprite__dom 自定义生成的svg元素的id
vueVersion 2 | 3 | auto auto Vue 版本, 默认会自动检测
treeShaking boolean true 是否开启tree-shaking
scanGlob string[] code 用于 tree-shaking 的模式匹配路径
scanStrategy text | component | (code: string[], options: Options)=>string[] component 用于 tree-shaking 的模式匹配策略, 未匹配成功则不会打包到最终的产物中去, text选项表示按图标名称匹配, 所以你应该保证你图标名称的唯一性(可以考虑用symbolIdFormatter选项定制)，以此避免错误的tree-shaking, 而默认值component表示的是按组件这一整体进行匹配, 此外你也可以通过传递函数的方式来实现 tree-shaking 策略, 函数的返回值表示用到的 svg 图标合集。
domInsertionStrategy replaceHtml | dynamic replaceHtml 控制注入SVG元素的方法,replaceHtml（默认）：在服务端通过替换HTML字符串来注入SVG元素; dynamic：在浏览器端,通过JavaScript动态地注入SVG元素。警告：如果您处于服务器端渲染（ssr）模式，您应该使用replaceHtml策略。

Typescript 支持

// tsconfig.json
{
  "include": ["svg-component.d.ts", "svg-component-global.d.ts"]
}

最佳实践

可以根据需求参考examples, 注意 examples 中的配置都是默认配置.

Contributing

  1. Fork (https://github.com/Jevon617/unplugin-svg-component/fork)
  2. 新建一个分支 (git checkout -b feature/fooBar)
  3. 提交你的代码 (git commit -am 'Add some fooBar')
  4. 提交到你的远程分支 (git push origin feature/fooBar)
  5. 提交PR

License

MIT License © 2022-PRESENT Jevon617