# @buyingbuddy/react 中文文档

规范地址：https://npmcn.com/package/%40buyingbuddy/react/

版本：0\.3\.4
npm 元数据更新时间：2026-10-27T12:50:06.323Z
中文译文更新时间：2026-11-08T22:18:04.221Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40buyingbuddy/react
原文对照：https://npmcn.com/package/%40buyingbuddy/react/?lang=original
项目主页：https://github.com/Blue-Fire-Group/buyingbuddy#readme
源码仓库：https://github.com/Blue-Fire-Group/buyingbuddy

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

- 包体积（解压后）：64.8 kB，24 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=18，react-dom \>=18
- 首次发布：2026-03-18T19:09:29.823Z
- 最新版本发布：2026-10-27T12:50:06.071Z
- 近 30 天下载量：2040（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

IDX MLS 地产集成 React, Next.js,和Framer——地产搜索,地图结果,上市,铅抓取,通过Buyding Buddy的CRM.

## 安装

```sh
npm install @buyingbuddy/react
```

也可以使用：`pnpm add @buyingbuddy/react`、`yarn add @buyingbuddy/react`、`bun add @buyingbuddy/react`

## README

# @ buyingbuddy/反应

将 IDX/ MLS 集成到您的站点中, 并带有嵌入的 React 组件 [购买Buddy IDX CMM](https://www.buyingbuddy.com/) 部件 - MLS 属性搜索,基于地图的结果,详细的上市页面,特色上市展示,铅抓取表,以及市场报告.

所有数据都托管在Buying Buddy服务器上. 你只需要安装软件包 买巴迪不需要任何数据库或其他技术先决条件. MLS/IDX 数据种子已经是您Buying Buddy 服务的一部分 - 没有单独的数据种子可以获取, 没有API可以连接, 没有任何连接 。 您不需要自编自导、 许可或整合数据 .

作为Buddy部件的船 `<bb-widget>` 从Buying Buddy插件脚本中装入自定义元素。 此软件包将元素包裹在平面反应组件中,这样您就可以将IDX搜索和列表添加到您的站点,而无需写入脚本标记或直接触碰自定义元素.

与 **反应**, (中文(简体) ), **下一个.js**,以及 **帧器**。 。 。 .

> **这是给你的包裹吗?** 这是一个 React 组件库——您在编译 JSX/TypeScript 的已建工具项目(Vite, Next.js, Frammer)内使用. 如果您只想将一个部件放入带有 `<script>` 标签,您不需要这个软件包——使用从您的Buyding Buddy账户仪表板上安装的标准部件(**部件 — 安装和设置**相反.

## 先决条件

在事情发生之前,你需要两个:

1.  **买Buddy账户激活密钥.** 在你的仪表板下找到它 **部件 — 插件安装和设置**。没有匿名或“尝试”模式——没有有效激活键,部件不会加载.
2.  **你的域名被授权使用.** 激活密钥只在账户注册的域上有效 。 在未经授权的域中, 运行时负载, 但部件会保留 **空** (没有返回数据) — 如果部件变为空白, 请检查域名是否在 **部件 — 插件安装和设置**。 。 。 .

**还没有账户吗?** [开始免费审判](https://buyingbuddy.com/free-trial-idx-plugin.php) 或者说 [购买执照](https://buyingbuddy.com/order) 获取激活键.

## 安装

在现有反应项目内:

```bash
npm install @buyingbuddy/react
```

反应 18 或 19 作为同伴的依赖, 请确保您的项目有:

```bash
npm install react react-dom
```

### 从头开始

没有反应项目了吗? 这让你从一无所有到运行的一页:

```bash
npm create vite@latest my-site -- --template react
cd my-site
npm install
npm install @buyingbuddy/react
npm run dev          # opens a dev server, usually http://localhost:5173
```

然后将下面的一个例子粘贴到 `src/App.jsx` 并保存——页面自动重载.

## 快开始

```jsx
import { BuyingBuddyProvider, BuyingBuddyWidget } from "@buyingbuddy/react";

export default function App() {
  return (
    <BuyingBuddyProvider activationKey="account-activation-key">
      <BuyingBuddyWidget type="FeaturedGallery" filter="limit:12" />
    </BuyingBuddyProvider>
  );
}
```

替换 `account-activation-key` 还有你的 `activationKey`。提供者为该账户装入了买入Buddy的脚本,并提供给其中的部件。 您自己的内容会直接消失, 提供商从不拒绝它, 一旦运行时间准备好, 每个部件就会出现 .

## 实例

**独立的搜索表 :**

```jsx
<BuyingBuddyProvider activationKey="account-activation-key">
  <BuyingBuddyWidget type="SearchForm" />
</BuyingBuddyProvider>
```

**在网格或列表布局中显示属性**,带有 `limit:` 在过滤器中标出数 :

```jsx
<BuyingBuddyWidget type="FeaturedGallery" filter="limit:12" />
```

> 要显示更广泛的 MLS 列表,请在 `filter` (下关. 如果过滤器没有其它标准, 部件会显示账户本身的( 特殊) 列表 .

**在网格布局中显示所选属性.** 所有选项均表示为 `+`\- 在一个单曲里面加入的标志 `filter` 字符串 — 标准、 排序和计算相同 。 使用 `FIELD()` 用于接受多个值的字段:

```jsx
{/* 6 listings over $300k, priced high-to-low */}
<BuyingBuddyWidget
  type="FeaturedGallery"
  filter="price_min:300000+order:price desc+limit:6"
/>

{/* combine criteria with + ; FIELD() for multi-value fields */}
<BuyingBuddyWidget
  type="FeaturedGallery"
  filter="city:Denver+FIELD(property_beds:3,4,5)+order:price desc+limit:9"
/>
```

**搜索结果** (结果部件由搜索/cookie状态驱动,以及 `SearchResults` 绑定在地图视图端口:

```jsx
<BuyingBuddyWidget
  type="SearchResults"
  filter="city:Denver+price_min:300000+order:price desc"
/>
```

**固定高度的交互式映射 :**

```jsx
<BuyingBuddyWidget type="InteractiveMap" style={{ height: "600px" }} />
```

### 下一个.js

提供者完全在浏览器中运行( 它装入脚本并读取) `window`),因此,使得它的文件必须是 **客户部分**在 App 路由器中,添加 `"use client"` 文件顶端的指示——它告诉Next.js在浏览器中运行这个组件,而不是只在服务器上运行.

单位 `app/page.tsx`数字 :

```tsx
"use client";

import { BuyingBuddyProvider, BuyingBuddyWidget } from "@buyingbuddy/react";

export default function Page() {
  return (
    <BuyingBuddyProvider activationKey="account-activation-key">
      <BuyingBuddyWidget type="SearchResults" />
    </BuyingBuddyProvider>
  );
}
```

由于这些部件仅是客户端,其上市内容是 **未交付服务器** 记住这一点,如果名单的SEO本身对你很重要.

### 帧器

一个独立、单一文件部件 [帧器](https://www.framer.com/) 网站构建者住址 [`framer/BuyingBuddyWidget.tsx`](https://npmcn.com/package/%40buyingbuddy/react/framer/BuyingBuddyWidget.tsx)它捆绑了脚本加载并添加了Framer属性控件(活化键,部件类型,过滤器),因此您可以配置Framer设计面板上的所有内容——不需要反应码.

1.  打开 [`framer/BuyingBuddyWidget.tsx`](https://npmcn.com/package/%40buyingbuddy/react/framer/BuyingBuddyWidget.tsx) 并复制其全部内容.
2.  在帧器中,转到 **资产 —— 代码 —— +** 把它粘起来.
3.  将组件拖入画布并设定 **激活密钥** 在财产面板.

你也可以从你的Buying Buddy帐号仪表板上 预先装满自己的激活键 **部件 — 插件安装和设置**。 。 。 .

## API 密码

### `<BuyingBuddyProvider>`

装入Buddy运行时的账户并提供给里面的部件。 使用 **一个** 供应商,靠近你的树顶.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `activationKey` | `string` | —— 说 | **要求.** 你的买巴迪账户激活密钥. |
| `fallback` | `ReactNode` | —— 说 | **已贬值,自0.3.2起不再开放.** 接受并被忽略;安全删除. 供货商不再扣留 `children`,所以没有装入状态使其屈服. |

### `<BuyingBuddyWidget>`

生成单个部件。 一定是一个后代 `<BuyingBuddyProvider>`。 。 。 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| `type` | `BuyingBuddyWidgetType` | **要求.** 要渲染的部件—— 例如 . `"FeaturedGallery"`, (中文(简体) ), `"SearchForm"`, (中文(简体) ), `"SearchResults"`, (中文(简体) ), `"InteractiveMap"`, (中文(简体) ), `"SearchDetails"`。 。 。 . |
| `filter` | `string` | 属性过滤为 `+`\- 加入的标志,例如. `"city:Denver+FIELD(property_beds:3,4,5)+order:price desc+limit:9"`。 。 。 . |
| `style` | `React.CSSProperties` | 直接应用到 `<bb-widget>` 键。 A 类 `height` 在此显示部件大小(例如: `InteractiveMap` 编号 : `SearchResults`) (中文(简体) ). |

常见 `type` 数值包括 `FeaturedGallery`, (中文(简体) ), `FeaturedList`, (中文(简体) ), `SearchForm`, (中文(简体) ), `SearchResults`, (中文(简体) ), `SearchDetails`, (中文(简体) ), `QuickSearch`, (中文(简体) ), `InteractiveMap`, (中文(简体) ), `Communities`, (中文(简体) ), `LcForm` (头部抓获), `LoginPanel`, (中文(简体) ), `Calculator`, (中文(简体) ), `MarketReport`, (中文(简体) ), `MarketStats`, (中文(简体) ), `Brokers`, (中文(简体) ), `OfficeRoster`,以及 `Disclaimer`编辑 `type` prop接受任意字符串,所以更新的部件类型甚至在输入之前就已经工作了.

### 类型脚本

包裹用"TypeScript"和"飞船"来书写出自己的类型. 这些要导出以满足您的打字需要 :

```ts
import type {
  BuyingBuddyWidgetType,
  BuyingBuddyWidgetProps,
  BuyingBuddyProviderProps,
  BuyingBuddyContextValue,
} from "@buyingbuddy/react";
```

## 洞穴限制( L)

-   **每页一个账户.** Buying Buddy 脚本安装了单个全局,所以一个页面需要使用一个 `activationKey`。不支持在同一页上以不同的激活键渲染两个提供者.
    
-   **仅限客户端.** 元件在脚本加载后在浏览器中渲染出——没有任何内容是服务器发送的. 没有SSR/流出输出,因此上市内容不在初始的HTML中(与SEO相关).
    
-   **更改道具重建部件 .** 变化 `type` 或者说 `filter` 泪下再现下底部 `<bb-widget>`,失去widget状态(地图位置、滚动、窗体输入).
    
-   **解载后剧本持续.** 卸载提供者不会移除脚本或重置全局-重载再用已装入的运行时间. 这是故意的.
    
-   **脚本加载失败会悄悄地降解.** 如果运行时脚本未能加载——CDN出道,广告屏蔽器,CSP规则,公司代理,下线——则您的应用程序完全按照它否则会产生的结果,而买入Buddy部件则完全缺失. 供应商在你的页面上不做任何自己的事。 故障记录在控制台上一次,可读取为 `error` 从 `useBuyingBuddy()` 如果你想自己说点什么的话:
    
    ```tsx
    const { error } = useBuyingBuddy();
    if (error) return <p>Property search is temporarily unavailable.</p>;
    ```
    
    注意这只涵盖脚本加载失败 —— 未经授权域装入精细但使空部件( 见 Prerequisites) .
    
-   **仅限无害环境管理.** 这个软件包船只作为ES模块(没有共同JS构建). 在有无害环境管理/捆绑者支持的项目中使用.
    
-   **释前.** 这个软件包是 `0.x` ——API可能改变.
    

## 发展

```bash
npm install
npm run build   # compile src/ to dist/ (JS + .d.ts)
npm run dev     # rebuild on change (tsc --watch)
npm test        # run the unit tests (vitest)
```

## 许可证

[麻省理工学院](https://npmcn.com/package/%40buyingbuddy/react/LICENSE) 蓝火集团/买巴迪

## 常见问题

### @buyingbuddy/react 是什么？

IDX MLS 地产集成 React, Next\.js,和Framer——地产搜索,地图结果,上市,铅抓取,通过Buyding Buddy的CRM\.

### 如何安装 @buyingbuddy/react？

在项目目录运行 npm install @buyingbuddy/react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18）、react-dom（\>=18）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @buyingbuddy/react 支持 TypeScript 吗？

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

### @buyingbuddy/react 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @buyingbuddy/react 可以商用吗？

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

### @buyingbuddy/react 的下载量有多少？

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

### @buyingbuddy/react 还在维护吗？

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