# @fluid-app/fluid 中文文档

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

版本：1\.1\.5
npm 元数据更新时间：2026-09-16T21:41:39.663Z
中文译文更新时间：2026-11-15T01:43:50.135Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：558 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2025-03-20T15:56:46.428Z
- 最新版本发布：2025-07-21T21:18:09.011Z
- 近 30 天下载量：21239（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：46（近 12 个月 0 个）

## 中文简介

流体商业 JavaScript SDK

## 安装

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

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

## README

# @ fluid-app/ fluid (英语)

官方JavaScript SDK为"流体通商",提供方便的车行管理,出站和归属追踪.

## 安装

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

## 快速启动

```typescript
import {
  addCartItems,
  checkout,
  getCart,
  getCartItemCount,
  initializeFluid,
} from "@fluid-app/fluid";

// Initialize the SDK (typically in your app's entry point)
// Basic initialization with server-side attribution
initializeFluid({
  fluidShop: "your-shop-id", // Replace with your shop ID
});

// Optional: Initialize with attribution override
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    share_guid: "your-affiliate-id",
  },
});

// Examples of common operations:

// 1. Add a single item to cart
const cart1 = await addCartItems(12345);

// 2. Add a single item with quantity
const cart2 = await addCartItems(12345, { quantity: 3 });

// 3. Add multiple items to cart at once
const cart3 = await addCartItems([
  { variant_id: 12345, quantity: 1 },
  { variant_id: 67890, quantity: 2 },
]);

// 4. Get the current cart
const cart = await getCart();

// 5. Get the number of items in the cart
const itemCount = getCartItemCount();

// 6. Proceed to checkout (redirects user automatically)
await checkout();
```

## 快速引用

### SDK 函数

-   [初始化流体](https://npmcn.com/package/%40fluid-app/fluid/#readme-initializefluid)
-   [获取卡特](https://npmcn.com/package/%40fluid-app/fluid/#readme-getcart)
-   [获取Cart 项目](https://npmcn.com/package/%40fluid-app/fluid/#readme-getcartitemcount)
-   [添加Cart 项目](https://npmcn.com/package/%40fluid-app/fluid/#readme-addcartitems)
-   [更新Cart 项目](https://npmcn.com/package/%40fluid-app/fluid/#readme-updatecartitems)
-   [订阅Cart 项目](https://npmcn.com/package/%40fluid-app/fluid/#readme-subscribecartitem)
-   [未订阅Cart 项目](https://npmcn.com/package/%40fluid-app/fluid/#readme-unsubscribecartitem)
-   [减少Cart 项目](https://npmcn.com/package/%40fluid-app/fluid/#readme-decrementcartitem)
-   [删除Cart 项目比德](https://npmcn.com/package/%40fluid-app/fluid/#readme-removecartitembyid)
-   [清空卡尔特](https://npmcn.com/package/%40fluid-app/fluid/#readme-clearcart)
-   [获取本地卡](https://npmcn.com/package/%40fluid-app/fluid/#readme-getlocalcart)
-   [离职](https://npmcn.com/package/%40fluid-app/fluid/#readme-checkout)
-   [重设](https://npmcn.com/package/%40fluid-app/fluid/#readme-reset)
-   [获取归属](https://npmcn.com/package/%40fluid-app/fluid/#readme-getattribution)
-   [查找关联](https://npmcn.com/package/%40fluid-app/fluid/#readme-lookupaffiliate)
-   [更新本地设置](https://npmcn.com/package/%40fluid-app/fluid/#readme-updatelocalesettings)

### 部件

-   [Cart 部件](https://npmcn.com/package/%40fluid-app/fluid/#readme-cart-widget)
-   [控制墨盒](https://npmcn.com/package/%40fluid-app/fluid/#readme-controlling-the-cart)
-   [添加带有数据属性的产品](https://npmcn.com/package/%40fluid-app/fluid/#readme-adding-products-with-data-attributes)
-   [添加带有数据属性的滚动包](https://npmcn.com/package/%40fluid-app/fluid/#readme-adding-enrollment-packs-with-data-attributes)
-   [合并包装和产品](https://npmcn.com/package/%40fluid-app/fluid/#readme-combined-enrollment-pack-and-products)
-   [铅捕获部件](https://npmcn.com/package/%40fluid-app/fluid/#readme-lead-capture-widget)

## 特征

-   **墨盒管理**: 创建推车、添加/移动项目并更新数量
-   **退出流程**: 自动重定向的一击取出
-   **追踪**: 内部跟踪附属营销
-   **事件跟踪**: 自动跟踪页面访问和推车互动
-   **会话管理**: 不带饼干处理用户会话
-   **浏览器指纹**: 跨部门用户识别
-   **优化更新**: 立即更新用户界面,以获得更好的用户体验
-   **输入的 API**: 具有准确类型的完整类型脚本支持

## 追踪

Fluid SDK默认包括了FairShare属性跟踪. 初始化时 `initializeFluid()`,属性跟踪自动设置 **服务器侧属性计算**。 。 。 .

### 服务器-系统分配如何工作

1.  **自动归属计算**: 获取设置时, 属性现在是根据当前页面 URL 计算的服务器侧 .
    
2.  **页面更改检测**:SDK自动检测URL变化(包括SPA导航)并视需要刷新归属数据.
    
3.  **归属覆盖支持**: 您可以以特定值来覆盖基于 URL 的属性, 用于测试或固定的情景 .
    
4.  **归属优先制度**: 归属比服务器计算归属优先.
    

### 基本服务器归属

```typescript
// Basic initialization - attribution calculated server-side automatically
initializeFluid({
  fluidShop: "your-shop-id",
});
```

### 归属

```typescript
// Attribution by email
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    email: "affiliate@example.com",
  },
});

// Attribution by username
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    username: "influencer-username",
  },
});

// Attribution by share GUID
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    share_guid: "abc123-def456-ghi789",
  },
});

// Attribution by Fluid rep ID
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    fluid_rep_id: 12345,
  },
});

// Attribution by external ID
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    external_id: "external-affiliate-id",
  },
});
```

## API 参考

### 核心设置

#### 初始化流体

`initializeFluid(config)`

初始化了Fluid SDK和集成的FairShare跟踪.

```typescript
import { initializeFluid } from "@fluid-app/fluid";

initializeFluid({
  fluidShop: "your-shop-id",
  debug: true, // Optional: enable debug logs
  apiEndpoint: "https://api.custom-endpoint.com", // Optional: custom API endpoint
});
```

您可以为本地开发、 校验或连接到特定的 API 实例等情景提供自定义 API 端点 .

#### 获取卡特

`getCart()`

从流体 API 获取当前手推车数据 .

```typescript
import { getCart } from "@fluid-app/fluid";

// Get the latest cart data from the API
const cart = await getCart();

// Access cart properties
if (cart?.items?.length > 0) {
  console.log(
    `Cart has ${cart.items.length} items with a total of $${cart.total}`,
  );
}
```

这使得网络请求获取最新的推车信息. 使用本地缓存数据的快捷离线选项,请参见 [`getLocalCart()`](https://npmcn.com/package/%40fluid-app/fluid/#readme-getlocalcart)。 。 。 .

### 墨盒管理

#### 获取Cart 项目

获得车内当前项目的数量.

```typescript
import { getCartItemCount } from "@fluid-app/fluid";

// Get the current cart item count
const itemCount = getCartItemCount();
console.log(`Cart contains ${itemCount} items`);
```

#### 添加Cart 项目

在推车中添加物品,如果已经装入车内,则增加其数量.

```typescript
// Add/increment a single item by 1
const cart1 = await addCartItems(12345);

// Add/increment a single item by 3
const cart2 = await addCartItems(12345, { quantity: 3 });

// Add/increment multiple items at once
const cart3 = await addCartItems([
  { variant_id: 12345, quantity: 2 },
  { variant_id: 67890, quantity: 1 },
]);

// Add an item with subscription
const cart4 = await addCartItems(12345, { subscribe: true });

// Add multiple items with mixed subscription preferences
const cart5 = await addCartItems([
  { variant_id: 12345, quantity: 1, subscribe: true },
  { variant_id: 67890, quantity: 2 },
]);
```

#### 更新Cart 项目

立即更新多件手推车物品的数量,对物品数量进行精确控制.

```typescript
import { updateCartItems } from "@fluid-app/fluid";

// Set exact quantities for multiple items
const cart = await updateCartItems([
  { variant_id: 12345, quantity: 3 },
  { variant_id: 67890, quantity: 1 },
]);

// This will set the quantities exactly as specified, regardless of previous values
```

#### 订阅Cart 项目

设置要作为订阅购买的手推车项目 .

```typescript
// Convert an existing cart item to a subscription
await subscribeCartItem(123); // where 123 is the item ID (not variant ID)
```

#### 未订阅Cart 项目

将一个手推车项目从订阅改为一次性购买.

```typescript
// Convert a subscription cart item back to a one-time purchase
await unsubscribeCartItem(123); // where 123 is the item ID (not variant ID)
```

#### 减少Cart 项目

将车内物品的数量减少规定数量(如果没有规定数量,则减少1个)。 如果数量为0,则从车中取出物品.

```typescript
// Decrement item by 1 (removes if quantity becomes 0)
const cart1 = await decrementCartItem(12345);

// Decrement item by 2
const cart2 = await decrementCartItem(12345, { quantity: 2 });
```

#### 删除Cart 项目比德

以项目 ID (而不是变体 ID) 完全删除一个手推车项目 。 此功能可用于删除全部项目而不论数量, 如入学包 .

```typescript
import { removeCartItemById } from "@fluid-app/fluid";

// Remove a cart item completely using its item ID
const cart = await removeCartItemById(itemId);

// This is particularly useful for enrollment packs
// where you want to remove the entire pack
const enrollmentItem = cart.items.find((item) => item.enrollment_pack_id);
if (enrollmentItem) {
  await removeCartItemById(enrollmentItem.id);
}
```

#### 清空卡尔特

删除手推车中的所有项目并删除手推车会话.

```typescript
clearCart();
```

#### 获取本地卡

直接从本地存储中获取当前推车, 而无需 API 调用 .

```typescript
const cart = getLocalCart();
if (cart?.items?.length > 0) {
  console.log(`Cart has ${cart.items.length} items`);
}
```

### 在 HTML 中显示墨盒计数

您可以在 HTML 元素中轻松显示当前手推车的计数, 方法是给它ID `fluid-cart-count`。SDK会自动更新此元素, 当拖车改变时.

```html
<!-- Simple cart count display -->
<span id="fluid-cart-count">0</span>
```

当 :

-   东西被加进车里
-   东西从车上搬走
-   项目数量得到更新
-   车已经清空了
-   创建一个新的推车
-   车是从API刷新出来的

### 离职

#### 离职

启动退出程序 。 这个:

1.  等待任何待办的推车操作完成
2.  如果有归属数据,则包括归属数据
3.  重定向到流体取出页面

```typescript
try {
  await checkout();
  // User is redirected automatically
} catch (error) {
  console.error("Checkout failed:", error);
}
```

### 公用事业

#### 重设

重置整个SDK状态,包括清除车和所有跟踪数据.

```typescript
import { reset } from "@fluid-app/fluid";

// Clear all data and reset state
reset();
```

#### 获取归属

获取当前属性数据.

```typescript
import { getAttribution } from "@fluid-app/fluid";

const attribution = getAttribution();
if (attribution?.username) {
  console.log("Referred by username:", attribution.username);
} else if (attribution?.email) {
  console.log("Referred by email:", attribution.email);
} else if (attribution?.share_guid) {
  console.log("Referred by share GUID:", attribution.share_guid);
} else if (attribution?.fluid_rep_id) {
  console.log("Referred by Fluid rep ID:", attribution.fluid_rep_id);
} else if (attribution?.external_id) {
  console.log("Referred by external ID:", attribution.external_id);
}
```

#### 查找关联

通过归属数据查找关联信息.

```typescript
import { lookupAffiliate } from "@fluid-app/fluid";

// Look up affiliate by username
try {
  const result = await lookupAffiliate({ username: "affiliate-username" });

  if (result?.affiliate) {
    console.log("Affiliate found:", result.affiliate.name);
    console.log("Email:", result.affiliate.email);
    console.log("Username:", result.affiliate.username);
    console.log("Share GUID:", result.affiliate.share_guid);
  }
} catch (error) {
  console.error("Affiliate not found or lookup failed:", error);
}

// Other lookup methods:
await lookupAffiliate({ email: "affiliate@example.com" });
await lookupAffiliate({ share_guid: "abc123" });
await lookupAffiliate({ fluid_rep_id: 123456 });
await lookupAffiliate({ external_id: "EXT-789" });
```

该函数可用于验证附属标识符或检索附属信息以用于显示目的.

#### 更新本地设置

更新手推车的语言和国别等地方设置.

```typescript
import { updateLocaleSettings } from "@fluid-app/fluid";

// Update language only
await updateLocaleSettings({ language: "fr" });

// Update country only
await updateLocaleSettings({ country: "CA" });

// Update both language and country
await updateLocaleSettings({
  language: "fr",
  country: "CA",
});
```

这对多语言/多区域商店很有用,以确保推车使用适当的地盘设置.

## Web 部件

Fluid提供随时可以使用的网络组件,很容易被整合到任何网站. 这些部件提供了精简的购物体验,不需要复杂的自定义执行.

### 安装

这些部件可通过CDN或作为国家防范机制软件包使用.

#### CDN / 脚本标签分发

使用这种方法直接纳入一个没有构建步骤的网站.

```html
<!-- Fluid SDK script tag with configuration attributes -->
<script
  id="fluid-cdn-script"
  src="https://assets.fluid.app/scripts/fluid-sdk/latest/web-widgets/index.js"
  data-fluid-shop="your-shop-id"
  data-fluid-api-base-url="https://api.your-custom-endpoint.com"
></script>
<!-- ^ The data-fluid-api-base-url attribute specifies a custom API endpoint -->
<!-- Attribution is now handled automatically server-side based on the page URL -->

<!-- Add the cart widget anywhere on your page -->
<fluid-cart-widget
  position="bottom-right"
  fluid-shop-display-name="Your Store Name"
></fluid-cart-widget>
```

#### CDN分发的主要好处

-   **无需安装国家预防机制** - 任何HTML页面的工作
-   **自动样式插入** - 没有单独的CSS文件可以包含
-   **单脚本标签处理所有事务** - 初始化SDK、加载样式、登记组件
-   **通过数据属性的灵活性**数字 :
    -   `data-fluid-shop` - 您的店牌( 需要)
    -   `data-fluid-api-base-url` - 使用自定义的API端点(用于开发/安装)
    -   `data-share-guid` - 设置硬码归属(可选)
    -   `data-debug` - 启用调试模式

#### 装置

```bash
npm install @fluid-app/web-widgets
```

```javascript
// Import the components and styles
import { initializeFluid } from "@fluid-app/fluid";
import { registerWebComponents } from "@fluid-app/web-widgets";

import "@fluid-app/web-widgets/styles.css";

// Initialize Fluid SDK with your shop ID
initializeFluid({
  fluidShop: "your-shop-id",
});

// Register the web components
registerWebComponents();
```

### 可用的部件

#### Cart 部件

推车部件为您的网站提供了浮动推车按钮和抽屉接口 .

```html
<!-- Basic cart widget -->
<fluid-cart-widget
  position="bottom-right"
  fluid-shop-display-name="Your Store"
></fluid-cart-widget>
```

**属性 :**

| 属性 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| 职位 | 字符串 | "从下到上" | 屏幕上的位置 : “ 左上” 、 “ 右上” 、 “ 左下” 、 “ 右下” |
| 流体处理- 播放- 名称 | 字符串 | "我的仓库" | 在车头显示店名 |
| 大小 | 编号 | 页:1 | 元件按像素键的大小 |
| x-边距 | 编号 | 第40条 | 从边缘到像素水平边距 |
| y-边距 | 编号 | 98国 | 从像素边缘起的垂直边距 |
| z 指数 | 编号 | 第50条 | 用于分层的 Z 索引 |
| 隐藏窗口 | 布尔 | 虚假 | 真实时, 隐藏按钮但保留拖车功能 |

#### 控制墨盒

您可以使用数据属性控制推车 :

```html
<!-- Cart control buttons -->
<button data-fluid-cart="open">Open Cart</button>
<button data-fluid-cart="close">Close Cart</button>
<button data-fluid-cart="toggle">Toggle Cart</button>
```

或使用 Java 脚本 :

```javascript
// When using NPM package
import { closeCart, openCart, toggleCart } from "@fluid-app/react-widgets";

openCart();
closeCart();
toggleCart();

// When using CDN
window.fluidCart.open();
window.fluidCart.close();
window.fluidCart.toggle();
```

#### 添加带有数据属性的产品

数据属性提供了一个简单的方法,无需写入 JavaScript 即可将产品添加到拖车中 :

```html
<!-- Basic usage with default quantity (1) - cart opens automatically -->
<button data-fluid-add-to-cart="22190">Add to Cart</button>

<!-- With specific quantity - cart opens automatically -->
<button data-fluid-add-to-cart="22190" data-fluid-quantity="2">
  Add 2 to Cart
</button>

<!-- Add to cart without opening cart drawer immediately -->
<button data-fluid-add-to-cart="22190" data-fluid-open-cart-after-add="false">
  Add to Cart (Keep Shopping)
</button>

<!-- Add with subscription enabled -->
<button data-fluid-add-to-cart="22190" data-fluid-subscribe="true">
  Add with Subscription
</button>

<!-- Add multiple products with one subscribed -->
<button data-fluid-add-to-cart="22190,22191" data-fluid-subscribe="true,false">
  Add Multiple (First Subscribed)
</button>
```

#### 添加带有数据属性的滚动包

使用数据属性可以添加输入包 :

```html
<!-- Basic usage to add an enrollment pack - cart opens automatically -->
<button data-fluid-add-enrollment-pack="64">Add Enrollment Pack</button>

<!-- Add enrollment pack without opening cart drawer immediately -->
<button
  data-fluid-add-enrollment-pack="64"
  data-fluid-open-cart-after-add="false"
>
  Add Enrollment Pack (Keep Shopping)
</button>
```

#### 合并包装和产品

您可以将招生包和普通产品合并为一个单项行动:

```html
<!-- Add enrollment pack and product together -->
<button data-fluid-add-enrollment-pack="64" data-fluid-add-to-cart="22190">
  Add Enrollment Pack with Product
</button>

<!-- Add multiple products with the enrollment pack -->
<button
  data-fluid-add-enrollment-pack="64"
  data-fluid-add-to-cart="22190,22191"
>
  Add Enrollment Pack with Multiple Products
</button>

<!-- With subscription enabled for the products -->
<button
  data-fluid-add-enrollment-pack="64"
  data-fluid-add-to-cart="22190,22191"
  data-fluid-subscribe="true"
>
  Add Pack with Subscribed Products
</button>

<!-- Different subscription settings for each product -->
<button
  data-fluid-add-enrollment-pack="64"
  data-fluid-add-to-cart="22190,22191"
  data-fluid-subscribe="true,false"
>
  Add Pack with Mixed Subscription Products
</button>
```

#### 铅捕获部件

主抓取部件提供了收集客户信息的表格.

```html
<!-- Basic lead capture widget -->
<fluid-lead-capture-widget
  title="Get Updates"
  contact-method="phone"
></fluid-lead-capture-widget>
```

### 自定义部件样式

您可以使用 CSS 变量自定义部件以匹配您的品牌 :

```css
:root {
  --company-color: #4361ee; /* Your brand color */
  --ff-body: "Your Custom Font", sans-serif; /* Your custom font */
}
```

-   `--company-color`: 设置按钮、口音和亮点的主要颜色
-   `--ff-body`: 设置整个部件所用的字体家族( 如果未指定则返回系统字体)

这使得您可以在您的网站和流体部件上保持一致的品牌和打字功能.

## 调试

启用调试模式以查看详细日志 :

```typescript
initializeFluid({
  fluidShop: "your-shop-id",
  debug: true,
});
```

您还可以检查本地Storage, 查看所存储的数据 :

-   `fs_cart`: 文件数据
-   `fs_attribution`: 归属数据
-   `fs_session`: 会话符号

## 许可证

麻省理工学院

## 常见问题

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

流体商业 JavaScript SDK

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

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

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

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

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

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

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

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

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

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

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

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