# vue-select-avatar

> 一个头像集选择/裁剪的组件库

Latest version **3.0.0-alpha.8** (published 2026-05-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install vue-select-avatar
pnpm add vue-select-avatar
yarn add vue-select-avatar
bun add vue-select-avatar
```

## Health

**Score 55/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.0.0-alpha.8 |
| Published | 2026-05-21 |
| First published | 2022-10-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^20.19.0 \|\| >=22.12.0 |
| Dependencies | 0 |
| Unpacked size | 44.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | xiangheng08 |
| Maintainers | laowan |
| Keywords | avatar, avatar-crop, avatar-select, crop, select, select-avatar, vue-avatar, 头像, 裁剪, 选择头像 |

## Links

- npm: https://www.npmjs.com/package/vue-select-avatar
- Repository: https://github.com/xiangheng08/vue-select-avatar
- Issues: https://github.com/xiangheng08/vue-select-avatar/issues
- npm.io page: https://npm.io/package/vue-select-avatar

## Alternatives

- [lodash.startswith](https://npm.io/package/lodash.startswith.md) — 769.7K weekly downloads
- [@tarojs/service](https://npm.io/package/@tarojs/service.md) — 33.9K weekly downloads
- [io.extendreality.tilia.indicators.spatialtargets.unity](https://npm.io/package/io.extendreality.tilia.indicators.spatialtargets.unity.md) — 131 weekly downloads
- [@rtarojs/taro](https://npm.io/package/@rtarojs/taro.md) — 90 weekly downloads
- [node-branch-io](https://npm.io/package/node-branch-io.md) — 50 weekly downloads

## Recent versions

- 3.0.0-alpha.8 (latest) — 2026-05-21
- 3.0.0-alpha.7 — 2026-05-21
- 3.0.0-alpha.5 — 2025-08-30
- 3.0.0-alpha.4 — 2025-08-30
- 3.0.0-alpha.3 — 2025-06-07
- 3.0.0-alpha.1 — 2025-06-06
- 2.0.3 — 2023-10-16
- 2.0.2 — 2023-09-27
- 2.0.1 — 2023-09-09
- 2.0.0 — 2023-08-31
- 1.2.3 — 2022-11-16
- 1.2.2 — 2022-11-16
- 1.2.1 — 2022-11-11
- 1.2.0 — 2022-11-07
- 1.1.1 — 2022-11-06
- … 1 more at https://npm.io/package/vue-select-avatar/versions

## README

<div align="center">

# vue-select-avatar

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![License][license-image]][license-url]

**基于 Vue 3 的头像选择与裁剪组件**

一个轻量级、功能丰富的头像裁剪库，支持图片校验、压缩、格式转换和实时预览

</div>

---

## 📸 在线演示

<div align="center">

![Demo](https://xiangheng08.github.io/vue-select-avatar/demo-compress.gif)

</div>

<div align="center">

|                               观察窗固定模式                               |                                图片固定模式                                 |
| :------------------------------------------------------------------------: | :-------------------------------------------------------------------------: |
| ![Fixed view](https://xiangheng08.github.io/vue-select-avatar/style_1.png) | ![Fixed image](https://xiangheng08.github.io/vue-select-avatar/style_2.png) |

</div>

---

## 🔗 快速链接

- 📖 [完整文档](https://xiangheng08.github.io/vue-select-avatar/)
- 🎯 [在线示例](https://xiangheng08.github.io/vue-select-avatar/usage)
- 📝 [更新日志](https://xiangheng08.github.io/vue-select-avatar/CHANGELOG)

## 功能特性

- 🖼️ 图片格式校验与尺寸限制（支持多种图片格式，可设置文件大小和尺寸限制）
- 📏 自动缩放超大图片（支持设置最大尺寸，自动等比例缩放）
- ⚡ 内置图片压缩功能（可配置压缩质量和触发条件）
- ✂️ 可视化区域裁剪（支持1:1正方形裁剪，实时预览效果）
- 📤 支持输出文件或Base64格式（灵活选择输出格式）
- 🎨 可配置JPEG背景色（支持自定义透明背景填充色）
- 🖱️ 多种交互方式（鼠标拖拽、滚轮缩放、键盘快捷键控制）
- 📱 触摸设备支持（单指拖动、双指缩放操作）
- 🔄 两种工作模式（固定图片或固定观察窗模式）
- 👁️ 实时预览组件（同步显示裁剪效果，支持圆形预览）
- 🌐 多语言支持（内置中英文，支持自定义错误信息）

## 安装

```sh
npm i vue-select-avatar
pnpm add vue-select-avatar
yarn add vue-select-avatar
```

## 使用

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { Viewport, selectImage, AvatarError } from 'vue-select-avatar'
import type { ViewportInstance, ImageInfo } from 'vue-select-avatar'

const viewportRef = ref<ViewportInstance>()
const info = ref<ImageInfo>()

const handleSelect = async () => {
  try {
    info.value = await selectImage({ maxFileSize: 1024 * 1024 * 5 })
  } catch (error) {
    if (AvatarError.isCancel(error)) return
  }
}

const handleCrop = () => {
  viewportRef.value?.crop<File>({ format: 'file' }).then((file) => {
    console.log(file.size, file)
  })
}
</script>

<template>
  <button @click="handleSelect">选择图片</button>
  <button @click="handleCrop">截取图片</button>
  <Viewport v-if="info" ref="viewportRef" grid :info="info" />
</template>
```

## 开发

```sh
git clone https://github.com/xiangheng08/vue-select-avatar.git
# or
git clone https://gitee.com/xiangheng08/vue-select-avatar.git
cd vue-select-avatar
pnpm i
pnpm dev # 启动开发服务
pnpm build # 构建项目
pnpm docs:dev # 启动文档开发服务（请先运行 pnpm build）
pnpm docs:build # 构建文档（请先运行 pnpm build）
```

## License

[MIT](https://github.com/xiangheng08/vue-select-avatar/blob/HEAD/LICENSE)

[npm-url]: https://www.npmjs.com/package/vue-select-avatar
[npm-version-image]: https://badgen.net/npm/v/vue-select-avatar
[npm-downloads-image]: https://badgen.net/npm/dm/vue-select-avatar
[license-image]: https://badgen.net/github/license/xiangheng08/vue-select-avatar
[license-url]: https://github.com/xiangheng08/vue-select-avatar/blob/HEAD/LICENSE

---
_Source: https://npm.io/package/vue-select-avatar · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._