# @fluid-app/storage-manager 中文文档

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

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

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

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

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

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

## 中文简介

Fluid 商业应用程序的存储管理设施

## 安装

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

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

## README

# @fluid-app/储存管理器

一个用于Fluid Commerce应用程序的公用软件包,为浏览器存储(localStorage)和cookie的工作提供一致的接口. 这个软件包处理浏览器环境中的存储,包括服务器侧渲染.

## 安装

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

## 基本用途

```typescript
import { STORAGE_KEYS, StorageManager } from "@fluid-app/storage-manager";

// Create a storage manager instance
const storageManager = new StorageManager();

// Store string data
storageManager.setItem(STORAGE_KEYS.CART, "cart_abc123");

// Retrieve string data
const cartToken = storageManager.getItem(STORAGE_KEYS.CART); // "cart_abc123"

// Store complex data (automatically serialized to JSON)
storageManager.setObject(STORAGE_KEYS.CART, {
  cart_token: "cart_abc123",
  items: [
    { id: 1, variant_id: 11601, quantity: 2 },
    { id: 2, variant_id: 11602, quantity: 1 },
  ],
  subtotal: "29.99",
});

// Retrieve complex data (automatically parsed from JSON)
const cart = storageManager.getObject(STORAGE_KEYS.CART);
console.log(cart.items.length); // 2

// Remove data
storageManager.removeItem(STORAGE_KEYS.CART);
```

## 与饼干合作

```typescript
import { COOKIE_KEYS, getCookie } from "@fluid-app/storage-manager";
import { getCountryFromLocale } from "path/to/localeUtils";

// Read a cookie value
const countryCookie = getCookie(COOKIE_KEYS.COUNTRY); // "US"

// The storage manager can also retrieve values from cookies as fallback
const storageManager = new StorageManager();

// Get country code with fallback to cookies
const locale = storageManager.getItem(STORAGE_KEYS.LOCALE);
const countryCode = getCountryFromLocale(locale);

// Get locale with fallback to cookies
const locale = storageManager.getItem(STORAGE_KEYS.LOCALE);
```

## 与流体生态系统的融合

存储管理器被其他 Fluid 包用于存储 :

1.  **绘图数据** (@fluid-app/fluid) (中文(简体) )
2.  **会话符号** (@fluid-app/fairshare) (法语)
3.  **指纹数据** (@fluid-app/fairshare) (法语)
4.  **事件队列** (@fluid-app/fairshare) (法语)

与 Fluid SDK 合并的例子 :

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

// Initialize Fluid SDK
initializeFluid({
  fluidShop: "your-shop-id",
  // Attribution is now handled server-side via the settings API
});

// You can still access other stored data if needed
const storageManager = new StorageManager();
const cartData = storageManager.getObject(STORAGE_KEYS.CART);
console.log("Current cart:", cartData);
```

## 存储密钥参考

软件包包括用于一致性的预定义存储密钥 :

```typescript
const STORAGE_KEYS = {
  ATTRIBUTION: "fs_attribution", // Attribution data
  ATTRIBUTION_CACHE: "fs_attribution_cache", // Cached attribution data
  CART: "fs_cart", // Cart data
  CLIENT_SETTINGS: "fs_client_settings",
  CONFIG: "fs_config", // SDK configuration
  COUNTRY: "fs_country", // Country code
  EVENT_QUEUE: "fs_event_queue", // Queued analytics events
  FINGERPRINT: "fs_fingerprint", // Browser fingerprint
  LOCALE: "fs_locale", // Locale
  SERVER_SETTINGS: "fs_server_settings", // Server settings
  SESSION: "fs_session", // Session token
  USER_ID: "fs_user_id", // User ID for identified users
};
```

## Cookie 密钥参考

软件包包括预定义的 cookie 密钥 :

```typescript
const COOKIE_KEYS = {
  COUNTRY: "country", // Country code cookie (often set by Cloudflare)
  LOCALE: "locale", // Locale cookie
};
```

## API 参考

### 存储管理类

```typescript
class StorageManager {
  // Store string data
  setItem(key: string, value: string): void;

  // Retrieve string data
  getItem(key: string): string | null;

  // Remove data
  removeItem(key: string): void;

  // Store complex data (automatically serialized to JSON)
  setObject<T>(key: string, value: T): void;

  // Retrieve complex data (automatically parsed from JSON)
  getObject<T>(key: string): T | null;

  // Get country code from storage or cookies
  getCountryCode(): string;

  // Set country code
  setCountryCode(countryCode: string): void;

  // Get locale from storage or cookies
  getLocale(): string | null;

  // Set locale
  setLocale(locale: string): void;
}
```

### 工具函数

```typescript
// Check if code is running in a browser environment
function isBrowser(): boolean;

// Get a cookie value by name
function getCookie(name: string): string | null;
```

## 服务器- Side 渲染兼容性

此软件包安全地处理浏览器和服务器环境,使其与Next.js等框架相兼容:

```typescript
// In a Next.js component (works in both client and server components)
import { StorageManager } from "@fluid-app/storage-manager";

export default function CartIndicator() {
  // Create a client component that uses localStorage safely
  "use client";

  const [itemCount, setItemCount] = useState(0);

  useEffect(() => {
    const storageManager = new StorageManager();
    const cart = storageManager.getObject("fs_cart");
    setItemCount(cart?.items?.length || 0);
  }, []);

  return <div>Cart Items: {itemCount}</div>;
}
```

## 许可证

麻省理工学院

## 常见问题

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

Fluid 商业应用程序的存储管理设施

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

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

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

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

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

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

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

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

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

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

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

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