# @atlaskit/media-avatar-picker 中文文档

规范地址：https://npmcn.com/package/%40atlaskit/media-avatar-picker/

版本：28\.3\.5
npm 元数据更新时间：2026-10-01T09:42:32.835Z
中文译文更新时间：2026-11-07T03:10:30.504Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40atlaskit/media-avatar-picker
原文对照：https://npmcn.com/package/%40atlaskit/media-avatar-picker/?lang=original
项目主页：https://bitbucket.org/atlassian/atlassian-frontend-mirror#readme
源码仓库：https://bitbucket.org/atlassian/atlassian-frontend-mirror

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：783 kB，218 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：19 个
- peer 依赖：react ^18\.2\.0，react-intl ^5\.25\.1 \|\| ^6\.0\.0 \|\| ^7\.0\.0，@emotion/react ^11\.7\.1
- 首次发布：2017-04-19T12:53:07.391Z
- 最新版本发布：2026-10-01T09:42:32.642Z
- 近 30 天下载量：8042（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：355（近 12 个月 50 个）

## 中文简介

一个用于选择、拖曳并调整图像外观大小的组件。 它还提供了预定义的相声的默认列表.

## 安装

```sh
npm install @atlaskit/media-avatar-picker
```

也可以使用：`pnpm add @atlaskit/media-avatar-picker`、`yarn add @atlaskit/media-avatar-picker`、`bun add @atlaskit/media-avatar-picker`

## README

# @atlaskit/media-avatar-捡取器

提供用于选择、拖动并调整图像外观大小的组件。 它还提供了预定义的相声的默认列表.

## 安装

```sh
yarn add @atlaskit/media-avatar-picker
```

## 使用组件

### 本地图像上传和裁剪

这个 `AvatarPickerDialog` 允许用户上传或降下本地图像,然后将平板并缩放到所期望的裁剪视图.

默认的缩放水平应当符合收成区域内的图像. 比收成面积小的图像被放大.

该组件会限制图像的平面和缩放,以确保用户只能选择有效的区域.

### 预定义的神通

该组件还允许用户从预定义的外观图像中选择. 这些可以通过它提供给组件 `avatars` 属性.

预定义的相机在用户选择图像时被隐藏.

### 只有客户端

该组件目前被设计为将所选的图像或外观递回. 它不使用任何特定的API来存储或上传,这是目前消费者的责任. 换句话说, 您需要一个解决方案来存储选中的图像或外观 .

### 限制

组件目前只接受 `image/gif`, (中文(简体) ), `image/jpeg`,以及 `image/png` mIME类型。 SVG 目前不支持.

组件只接受最高为10Mib的图像.

### 处理错误

该组件将处理客户端的下列错误:

-   坏格式 - 如果用户上传一个格式不好的图像, 或丢弃无效的 MIME 类型, 将会显示错误
-   图像大小 > 10Mib - 如果用户上传或降下大于 10Mib 的图像大小, 将会显示错误消息

见 `errorMessage` 属性下方可以设置您的自定义错误消息.

## 无障碍

该部分旨在完全无障碍,并遵循《世界儿童保护公约》的准则:

### 键盘导航

-   **图像裁剪**: 使用箭头键在裁剪区域内移动并定位图像
-   **标签导航**: 所有交互式元素都可以通过键盘访问
-   **重点管理**: 整个接口清晰的视觉焦点指标

### 屏幕阅读器支持

-   **ARIA 标签**: 描述所有交互式元素的标签
-   **实时通知**: 裁剪时移动图像时实时反馈
-   **语义标记**:辅助技术的适当作用和结构

### 特征

-   完全键盘可访问图像裁剪和导航
-   图像定位屏幕阅读器通知
-   高对比度重点指标
-   整个接口的逻辑标签顺序

## API 密码

`onImagePicked?: (file: File, crop: CropProperties) => void`

此属性在用户单击时被提高 **保存** 按钮,则有一个选定的图像。 通过了两个论点: `file:File` 是一个圆柱形,而收成设置是一个包含 `x:number`, (中文(简体) ),`y:number`,以及 `size:number` 值,这些值都相对于所选图像的坐标.

**说明** 由于对Safari QQ 10.0和IE11的限制,a `Blob` 对象将返回而不是一个 `File`。这仍然允许访问图像字节数据以便利上传,基本上减去文件名和日期属性.

这个 `x` 财务报告和审定财务报表 `y` 代表作物面积的来源。 这个 `size` 值是一个代表作物面积宽度和高度的单一值。 要从所选图像中获取收割区域,只需取取被剪接的矩形(`x`, (中文(简体) ), `y`, (中文(简体) ), `size`, (中文(简体) ), `size`)来自给定的图像.

`onImagePickedDataURI?: (dataURI: string) => void`

此属性在用户单击时被提高 **保存** 按钮,并有一个选定的图像。 选定的图像作为数据URI字符串提供.

`onAvatarPicked: (avatar: Avatar) => void`

此属性在用户单击时被提高 **保存** 按钮,并有预定义的已选择的外观,没有选择图像。 一个 `Avatar` 对象为 a `dataURI` 财产通过.

`onCancel: Function`

当用户点击时, 此属性会上升 **取消** 按钮.

**说明** 无法关闭对话框 。 由消费者负责从UI中重新提交并删除对话框.

`imageSource?: string`

_(可选)_ 此属性用于设置选中的图像, 以便组件随其可见而打开 .

该值应为有效的数据URI字符串. 如果给出了无效的数据URI,则会触发不良格式错误状态并显示消息.

`avatars: Array<Avatar>`

此属性用于提供一系列预定义的外观. 这个 `Avatar` 对象是一个单一的简单类型 `dataURI: string` 属性。 为方便起见,此类型从 `@atlassian/media-avatar-picker` 模块与 `AvatarPickerDialog` 组件.

`defaultSelectedAvatar?: Avatar`

_(可选)_ 该财产与 `avatar` 属性。 它允许您设置当前选中的预定义外观 。 默认情况下,即使 `avatars` 属性设置.

`title?: string`

_(可选)_ 对话框的标题文本 。 默认是 _上传相机_。 。 。 .

`primaryButtonText?: string`

_(可选)_ 主按钮文字. 默认是 _保存_。 。 。 .

`errorMessage?: string`

_(可选)_ 此属性允许消费者显示错误消息 。 这可能是从呼叫服务。 如果大于 125 个字符串( 对话框内约有 3行) , 字符串会被剪接 .

### 用法示例

下面是制作 " Avatar PickerDialog " 的例子。 对话应被 " Modal Transition " 部分包住,以便在关闭时淡出.

```
import { AvatarPickerDialog, Avatar } from '@atlaskit/media-avatar-picker';
import { ModalTransition } from '@atlaskit/modal-dialog';

const avatars: Array<Avatar> = [{ dataURI: 'some-data-uri' }];

const App = ({ isOpen }) => (
  <ModalTransition>
    {isOpen && (
      <AvatarPickerDialog
        avatars={avatars}
        onImagePicked={(selectedImage, crop) => {
          console.log(selectedImage.size, crop.x, crop.y, crop.size);
        }}
        onAvatarPicked={selectedAvatar =>
          console.log(selectedAvatar.dataURI)
        }
        onCancel={() => /* we need to close the dialog... */}
      />
    )}
  </ModalTransition>
);
```

## 常见问题

### @atlaskit/media-avatar-picker 是什么？

一个用于选择、拖曳并调整图像外观大小的组件。 它还提供了预定义的相声的默认列表\.

### 如何安装 @atlaskit/media-avatar-picker？

在项目目录运行 npm install @atlaskit/media-avatar-picker，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.2\.0）、react-intl（^5\.25\.1 \|\| ^6\.0\.0 \|\| ^7\.0\.0）、@emotion/react（^11\.7\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @atlaskit/media-avatar-picker 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @atlaskit/media-avatar-picker 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @atlaskit/media-avatar-picker 可以商用吗？

@atlaskit/media-avatar-picker 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @atlaskit/media-avatar-picker 的下载量有多少？

根据 npm 官方下载统计，@atlaskit/media-avatar-picker 在 2026/10/07 – 2026/11/05 这 30 天内被下载 8,042 次，日均约 268 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @atlaskit/media-avatar-picker 还在维护吗？

最新版本 28\.3\.5 发布于 2026/10/01（1 个月前）；至今共发布 355 个版本，其中过去 12 个月发布了 50 个；首次发布于 2017/04/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。