# @fluid-app/dam-picker 中文文档

规范地址：https://npmcn.com/package/%40fluid-app/dam-picker/

版本：0\.2\.10
npm 元数据更新时间：2026-09-16T21:41:38.948Z
中文译文更新时间：2026-11-15T01:40:57.874Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40fluid-app/dam-picker
原文对照：https://npmcn.com/package/%40fluid-app/dam-picker/?lang=original
项目主页：https://github.com/fluid-commerce/fluid-dam-picker
源码仓库：https://github.com/fluid-commerce/fluid-dam-picker

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

- 包体积（解压后）：1.5 MB，18 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2026-04-15T21:58:08.464Z
- 最新版本发布：2026-07-14T20:03:15.615Z
- 近 30 天下载量：23529（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

Fluid Commerce 应用程序可嵌入的 DAM 文件拾取器

## 安装

```sh
npm install @fluid-app/dam-picker
```

也可以使用：`pnpm add @fluid-app/dam-picker`、`yarn add @fluid-app/dam-picker`、`bun add @fluid-app/dam-picker`

## README

# @fluid-app/dam-捡取器

Fluid Commerce应用程序的可嵌入 DAM(数字资产管理)文件取取器.

## 特征

-   **浏览 DAM 库** - 搜索和导航您的现有资产
-   **上传文件** - 拖放或点击计算机上传
-   **从 URL 从中导入** - 从任何公共 URL 直接导入文件
-   **资产类型过滤** - 通过图像、视频、文档或音频过滤
-   **框架不可知论** - 与React、Vue、Angular或香草JavaScript合作

## 安装

```bash
npm install @fluid-app/dam-picker
# or
pnpm add @fluid-app/dam-picker
# or
yarn add @fluid-app/dam-picker
```

## 快速启动

### 香草 Java 脚本

```javascript
import { DamPicker } from '@fluid-app/dam-picker';

const picker = new DamPicker({
  token: 'your-fluid-api-token',
  onSelect: (assets) => {
    console.log('Selected asset:', assets[0].url);
    // Use the asset URL in your application
  },
  onCancel: () => {
    console.log('User cancelled');
  },
  onError: (error) => {
    console.error('Error:', error.message);
  },
});

// Open the picker
document.getElementById('choose-image').addEventListener('click', () => {
  picker.open();
});
```

### 反应 (Hook)

```jsx
import { useDamPicker } from '@fluid-app/dam-picker/react';

function ImageSelector() {
  const [imageUrl, setImageUrl] = useState(null);
  const { open } = useDamPicker({ token: 'your-fluid-api-token' });

  const handleChooseImage = () => {
    open({
      onSelect: (assets) => setImageUrl(assets[0].url),
      onCancel: () => console.log('Cancelled'),
    });
  };

  return (
    <div>
      <button onClick={handleChooseImage}>Choose Image</button>
      {imageUrl && <img src={imageUrl} alt="Selected" />}
    </div>
  );
}
```

### 反应( 组件)

```jsx
import { useState } from 'react';
import { DamPickerModal } from '@fluid-app/dam-picker/react';

function ImageSelector() {
  const [isOpen, setIsOpen] = useState(false);
  const [imageUrl, setImageUrl] = useState(null);

  return (
    <div>
      <button onClick={() => setIsOpen(true)}>Choose Image</button>
      {imageUrl && <img src={imageUrl} alt="Selected" />}

      <DamPickerModal
        isOpen={isOpen}
        token="your-fluid-api-token"
        onSelect={(assets) => {
          setImageUrl(assets[0].url);
          setIsOpen(false);
        }}
        onCancel={() => setIsOpen(false)}
      />
    </div>
  );
}
```

## API 参考

### 达姆派克

香草JavaScript使用的主要类.

#### 构造选项

| 选项 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `token` | `string` | 对 | 您的流体 API 符号 |
| `onSelect` | `(assets: SelectedAsset[]) => void` | 对 | 当用户选择资产时调用 |
| `onCancel` | `() => void` | 没有 | 用户取消时调用 |
| `onError` | `(error: DamPickerError) => void` | 没有 | 调用错误 |
| `onReady` | `() => void` | 没有 | 选手准备好就打电话 |
| `baseUrl` | `string` | 没有 | 覆盖 picker 应用 URL (用于本地开发) |
| `zIndex` | `number` | 没有 | Modal z- index( 默认: 10000) |
| `maxSelectable` | `number` | 没有 | 可选择资产的最大数目(违约:1,最低:1) |
| `filters.assetTypes` | `string[]` | 没有 | 按资产类型过滤: “ 图像”、“ 视频”、“ 文件”、“ 音频” |

#### 方法

-   `open()` - 打开拾取模式
-   `close()` - 关闭拾取模式
-   `destroy()` - 清理拾取者实例
-   `isOpen()` - 返回拾取器当前是否打开

### 选集

选择时返回的资产对象(无论是从库选择还是上传).

```typescript
interface SelectedAsset {
  url: string;           // Public URL to the asset
  assetCode: string;     // Unique asset identifier
  name: string;          // Display name
  mimeType: string;      // MIME type (e.g., "image/png")
  metadata?: {
    width?: number;      // Image/video width
    height?: number;     // Image/video height
    fileSize?: number;   // File size in bytes
  };
  variantId?: string;    // Selected variant ID (if applicable)
}
```

### 达姆派克错误

错误对象传递到 Error 调用 .

```typescript
interface DamPickerError {
  code: 'AUTHENTICATION_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT' | 'UNKNOWN';
  message: string;
}
```

## 过滤资产类型

您可以限制哪些资产类型用户可以浏览并上传 :

```javascript
const picker = new DamPicker({
  token: 'your-token',
  filters: {
    assetTypes: ['images', 'videos'], // Only show images and videos
  },
  onSelect: (assets) => console.log(assets),
});
```

可用资产类型:

-   `'images'` - 图像文件(jpg、png、gif、webp、svg等)
-   `'videos'` - 视频文件(mp4、webm、mov等)
-   `'documents'` - 文件(pdf、Doc、docx、xls、xlsx等)
-   `'audio'` - 音频文件(mp3、wav、ogg等)

## 多选择

默认情况下,用户可以一次选择一个资产. 使用 `maxSelectable` 以允许多个选择:

```javascript
const picker = new DamPicker({
  token: 'your-token',
  maxSelectable: 5, // Allow up to 5 assets
  onSelect: (assets) => {
    assets.forEach((asset) => console.log(asset.url));
  },
});
```

> **中断更改 :** `onSelect` 现在总是收到一组 `SelectedAsset[]`,即使当 `maxSelectable` 为 1.

## 上传行为

当用户上传文件时( 无论是从计算机还是 URL ) :

1.  文件通过 ImageKit 上传到 Fluid 的 DAM
2.  一旦完成 `onSelect` 用新资产解除回调
3.  拾取器在成功上传后自动关闭

这意味着你处理上传的方式与库选择相同 - 只是听 `onSelect`。 。 。 .

## Vue.js 一体化

使用 Vue 中的香草 JavaScript API :

```vue
<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
import { DamPicker } from '@fluid-app/dam-picker';

const imageUrl = ref(null);
let picker = null;

onMounted(() => {
  picker = new DamPicker({
    token: 'your-fluid-api-token',
    onSelect: (assets) => {
      imageUrl.value = assets[0].url;
    },
  });
});

onUnmounted(() => {
  picker?.destroy();
});

const openPicker = () => picker?.open();
</script>

<template>
  <div>
    <button @click="openPicker">Choose Image</button>
    <img v-if="imageUrl" :src="imageUrl" alt="Selected" />
  </div>
</template>
```

## 角融合

```typescript
import { Component, OnDestroy } from '@angular/core';
import { DamPicker } from '@fluid-app/dam-picker';

@Component({
  selector: 'app-image-selector',
  template: `
    <button (click)="openPicker()">Choose Image</button>
    <img *ngIf="imageUrl" [src]="imageUrl" alt="Selected" />
  `,
})
export class ImageSelectorComponent implements OnDestroy {
  imageUrl: string | null = null;
  private picker: DamPicker;

  constructor() {
    this.picker = new DamPicker({
      token: 'your-fluid-api-token',
      onSelect: (assets) => {
        this.imageUrl = assets[0].url;
      },
    });
  }

  openPicker() {
    this.picker.open();
  }

  ngOnDestroy() {
    this.picker.destroy();
  }
}
```

## 地方发展

对于本地开发,请将 SDK 指向您的本地流体管理实例 :

```javascript
const picker = new DamPicker({
  token: 'your-token',
  baseUrl: 'http://localhost:3007/dam-picker',
  onSelect: (assets) => console.log(assets),
});
```

## 许可证

麻省理工学院

## 常见问题

### @fluid-app/dam-picker 是什么？

Fluid Commerce 应用程序可嵌入的 DAM 文件拾取器

### 如何安装 @fluid-app/dam-picker？

在项目目录运行 npm install @fluid-app/dam-picker，或使用 pnpm add / yarn add / bun add。

### @fluid-app/dam-picker 支持 TypeScript 吗？

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

### @fluid-app/dam-picker 支持 ESM 还是 CommonJS？

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

### @fluid-app/dam-picker 可以商用吗？

@fluid-app/dam-picker 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fluid-app/dam-picker 的下载量有多少？

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

### @fluid-app/dam-picker 还在维护吗？

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