# @brandfolder-panel/sdk 中文文档

规范地址：https://npmcn.com/package/%40brandfolder-panel/sdk/

版本：0\.9\.33
npm 元数据更新时间：2024-12-17T17:02:23.887Z
中文译文更新时间：2026-11-08T13:55:26.349Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40brandfolder-panel/sdk
原文对照：https://npmcn.com/package/%40brandfolder-panel/sdk/?lang=original

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

- 包体积（解压后）：9.4 MB，852 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2022-09-23T05:14:17.324Z
- 最新版本发布：2024-12-17T17:02:23.708Z
- 近 30 天下载量：10212（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：55（近 12 个月 0 个）

## 中文简介

品牌文件夹

## 安装

```sh
npm install @brandfolder-panel/sdk
```

也可以使用：`pnpm add @brandfolder-panel/sdk`、`yarn add @brandfolder-panel/sdk`、`bun add @brandfolder-panel/sdk`

## README

# 面板 UI SDK

## 文档

### 开始

1.  安装 npm 包 : `npm install @brandfolder-panel/sdk`。 。 。 .
2.  导入样式表, 在 `@brandfolder-panel/sdk/styles.css`在您的申请中。 所有样式都被命名为 `.panel-ui-sdk` 因此,不应该有冲突.
3.  初始化并开始使用 SDK.

_注:由于Brandfolder GeneralUI SDK使组件处于消耗上下文,而不是在iframe内,所以其所有依赖性目前都包含在包中. 我们将重新评估和移动图书馆,以便在必要时成为同侪的依赖._

### 初始化

```
export interface PanelUISdkParameters {
  appName: string;
  anchorElement: HTMLElement; // Used to append the Iframe containing the Panel
  panelUIBaseUrl?: string; // OPTIONAL. Custom base URL if using a self-hosted version of the Panel
  headerBackgroundUrl?: string; // OPTIONAL. Custom background image url for the header
  // OPTIONAL. You can pass in a valid auth token that will be used for requests to the Brandfolder API. If this is
  // not passed in we will fallback to having the user input their API key.
  authParameters?: {
    token: string; // Valid OAuth token or API key
    refreshTokenHandler: () => Promise<string>; // Handler for fetching a new token if the initial one has become invalid. The SDK will call this function as needed.
  };
  statePersistence?: {
    enabled: boolean; // If true, the panel will persist its state in between uses
    storage?: Storage; // OPTIONAL. Allows consumer to pass in a custom storage implementation for persisting state
  };
  styles?: {
    backgroundColor?: string; // Background color for the panel,
    backgroundColorSecondary?: string; // Secondary background color for contrasted elements (i.e. hover styling)
  };
}
```

反应中的例子 :

```
function App() {
  const ref = useRef();

  useEffect(() => {
    if (ref.current) {
      const sdk = new PanelUISdk({ appName: 'test', anchorElement: ref.current } });
      sdk.selectAttachments();
    }
  }, [])

  return (
    <div className="App">
      <div ref={ref} id='panel-root' />
    </div>
  );
}
```

### 面板UISdk.selectAttachments

如果指定了品牌文件夹或收藏ID,则默认在 Org 登陆页或显示页上打开面板。 允许您通过一个处理器来聆听附件选择事件.

参数 :

```
export interface SelectAttachmentProps {
  containerId?: string | null; // OPTIONAL - Navigate to specified Brandfolder or Collection, otherwise go to org landing page
  supportedMimeTypes?: string[]; // OPTIONAL - pass in a list of supported mime types
  onDragStart?: (attachment: AttachmentDto) => void; // Called when a user starts dragging an attachment
  onDragEnd?: (attachment: AttachmentDto) => void; // Called when a user stops dragging an attachment
  onSelect: (attachment: AttachmentDto) => void; // Called whenever user selects an attachment
  hideHeader?: boolean; // OPTIONAL - hides the header. Defaults to false.
  resumeSession?: boolean; // OPTIONAL - resume from persisted session
  searchParameters?: SearchParameters; // OPTIONAL - Use search parameters with Brandfolder API 
  enforcedSearchParameters?: EnforcedSearchParameters; // OPTIONAL - Enforce search parameters with Brandfolder API
};
```

示例

```
panel.selectAttachments({
  containerId: 'VALID_BRANDFOLDER_ID',
  onSelect: (attachment) => console.log('Attachment selected: ', attachment),
  hideHeader: true,
});
```

#### 支持品牌文件夹附件的拖放

这个 `@brandfolder-panel/sdk/utilities` namespace 显示您可以用来简化您如何消耗来自面板的拖放事件的工具功能。 它会从事件中提取附件数据并传递给您的处理者.

现有职能如下:

```
export function isAttachmentDragEvent(event: DragEvent): boolean => {...};

export function handleAttachmentDragEvent(
  event: DragEvent,
  handler: (props: AttachmentDragEventHandlerProps) => void,
): void => {...};
```

举个例子,你如何在反应中使用它们:

```
const handleAttachmentDrag = (event: DragEvent) => {
  if (isAttachmentDragEvent(event)) {
    handleAttachmentDragEvent(event, ({ attachment }) => {
      console.log('Attachment dragged over drop zone: ', attachment);
    });
  }
};

return <div onDragOver={handleAttachmentDrag}>Drop Zone</div>;
```

### 面板UISdk.openUpload 软件

在上传页面上打开面板。 允许您通过带有要上传的文件blobs的一系列对象.

参数 :

```
export interface ImageUploadPayload {
  file_name: string;
  file: Blob;
}
```

```
export interface OpenUploadProps {
  uploadAssets: ImageUploadPayload[]; // an array of file blobs with file names
  hideHeader?: boolean; // OPTIONAL - hides the header
}
```

示例

```
panel.openUpload({
  uploadAssets: [{file_name: 'new-file', file: new Blob()}];
  hideHeader?: true;
});
```

### 面板UISdk.closePanel

将小组从锚要素中删除。 SDK对象仍然有效并可用于启动新的操作.

示例

```
panel.closePanel()
```

## 常见问题

### @brandfolder-panel/sdk 是什么？

品牌文件夹

### 如何安装 @brandfolder-panel/sdk？

在项目目录运行 npm install @brandfolder-panel/sdk，或使用 pnpm add / yarn add / bun add。

### @brandfolder-panel/sdk 支持 TypeScript 吗？

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

### @brandfolder-panel/sdk 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @brandfolder-panel/sdk 可以商用吗？

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

### @brandfolder-panel/sdk 的下载量有多少？

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

### @brandfolder-panel/sdk 还在维护吗？

最新版本 0\.9\.33 发布于 2024/12/18（1\.9 年前）；至今共发布 55 个版本，其中过去 12 个月发布了 0 个；首次发布于 2022/09/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。