# @aftership/shop-now 中文文档

规范地址：https://npmcn.com/package/%40aftership/shop-now/

版本：0\.0\.11
npm 元数据更新时间：2026-11-05T03:39:07.792Z
中文译文更新时间：2026-11-05T23:57:26.001Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：92.4 kB，107 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react ^18\.2\.0 \|\| ^19\.0\.0，react-dom ^18\.2\.0 \|\| ^19\.0\.0
- 首次发布：2024-05-29T09:33:42.516Z
- 最新版本发布：2026-11-05T03:39:07.595Z
- 近 30 天下载量：8679（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 4 个）

## 中文简介

现在的返回商店库

## 安装

```sh
npm install @aftership/shop-now
```

也可以使用：`pnpm add @aftership/shop-now`、`yarn add @aftership/shop-now`、`bun add @aftership/shop-now`

## README

# @aftership/shop-现在

现在的返回商店库

## ++ 预先要求

交换其他项目 SDK 需要 `Premium or above plan`登录到 [飞船返回后管理员](https://admin.returnscenter.com/) 升级您的订阅.

## \* 背景情况

商店流上返回的efa会从回页跳到商店,在URL中包含相关的参数. 这个 `shop-now` SDK 将处理存储 URL 中包含的参数并提供相關能力,使您可以轻松地完成自建存储中的返回efa流量

## \* 特性

-   方便学习和使用.
-   QQ支持反应.
-   QQ 多自定义 API 支持交换所储存的任何东西 .
-   • 支持多种电子商务平台,包括Shofify、Bigcommerce和Slesforce Commerce Cloud.
-   QQ 在 TypeScript 中以可预测的静态类型写入 .
-   \* 支持安全部门改革

## QQ 安装

```bash
npm i @aftership/shop-now
```

## 开始

### 反应

这里有一个要使用的例子

```typescript
import {useReturnsShopNow} from '@aftership/shop-now/react';
```

使用ReturnsShopNow是逻辑数据的集合,不包括UI. 您可以自己执行 UI 或使用 SDK 提供的 UI 横幅

1,第一步,确定是否在返回efa进程中. 您可以使用FromEFA从使用ReturnsShopNow来确定它是否在efa进程中.

```typescript
import {useReturnsShopNow} from '@aftership/shop-now/react';

function YourComponent() {
  const {isFromEFA} = useReturnsShopNow({
    platform: 'shopify',
  });

  if (isFromEFA) {
    // EFA process logic here
    return <EFAFlowComponent />;
  }

  // Regular flow logic here
  return <RegularFlowComponent />;
}
```

2,第二步,当确认是efa过程时,新页需要调用initCart方法来计算目前的购物车项目价格.

```typescript
import {useEffect} from 'react';
const {initCart, isFromEFA, shopContext} = useReturnsShopNow({
  platform: 'shopify',
});

const {isMounted, isLoading} = shopContext;

useEffect(() => {
  if (isFromEFA && isMounted) {
    initCart?.(lineItems as LineItems);
  }
}, [isFromEFA, initCart, isMounted]);
```

我们还提供 `isLoading` 计算 API 和 `isMounted` 钩子状态 。 你们可以表演 `initCart` 之后 `isMounted` 状态是真实的. 当您有需要使用的特殊情景时 `initCart`,您可以使用 `isMounted`。一般使用 `updateCart` 足够了.

shopContext 包含一些您可以使用的信息

```typescript
export type PlatformContext = Partial<{
  shopInfo: {
    currency: string;
    // return page language
    language: string;
    // return page redirect url
    redirectUrl: string;
    // return page origin
    rc_origin: string;
    // return page navigate from path
    rc_navigate_from_path: string;
  };
  // price calculation
  price: {amount: number; currency: string};
  // returns admin page editor style
  style: {
    background: string;
    font: string;
  };
}> & {
  /**
   * fetch calculation api loading
   */
  isLoading: boolean;
  /**
   * EFA process hook loading status
   */
  isMounted: boolean;
};
```

此外,所有行项目均应符合以下格式:

```typescript
type LineItem = {
  external_product_id: string;
  external_variant_id: string;
  quantity: number;
};

type LineItems = LineItem[];
```

一旦价格计算成功,你就会从shopContext得到价格. 您可以访问shopContext下的价格对象以获取金额和货币. `shopContext?.price;`

```typescript
interface Price {
  amount: number;
  currency: string;
}
```

三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 三 `lineItems`。 。 。 . `shopContext` 是一个订阅状态,所以当项目被成功计算时,它将自动更新

```typescript
const {updateCart} = useReturnsShopNow({
  platform: 'shopify',
});

updateCart?.(lineItems);
```

建议使用 `updateCart` 以触发计算。 当手推车改变时,你可以通过手推车数据进行计算,这样可以有效地进行聚合计算.

此外,我提供 `addToCart` 财务报告和审定财务报表 `removeFromCart` 基于单个项目更改的方法,只允许您通过当前 `lineItem`

```typescript
const {addToCart, removeFromCart} = useReturnsShopNow({
  platform: 'shopify',
});

addToCart(lineItem);
removeFromCart(lineItem);
```

当您想知道存储在SDK内的物品的实际数量和信息时,您可以访问 `cart` 商店上下文中的财产.

```typescript
const {shopContext} = useReturnsShopNow({
  platform: 'shopify',
});

const cart = shopContext?.cart ?? [];
```

#### 3.1 确定贴现代码

如果你的店铺购买了适用于推车的折扣代码,你可以使用 `setDiscountCodes` 方法。 这将确保贴现代码与返回意向一起节省.

```typescript
const {setDiscountCodes} = useReturnsShopNow({
  platform: 'shopify',
});

// Set discount codes (e.g., from Shopify cart.js discount_codes where applicable: true)
setDiscountCodes?.(['DISCOUNT10', 'SUMMER2024']);
```

4,第四步,你可以叫退房,去Back,购买现在三种方法回到回页"

4.1 离职 当用户点击商店里的购物车按钮进行检查时,您应该调用退出,它会自动重定向到返回页面

```typescript
const {checkout} = useReturnsShopNow({
  platform: 'shopify',
});

checkout?.();
```

4.2,现在购买 当用户点击商店中的买入按钮检查时, 您应该拨打买入, 在行中通过项目, 它会自动重定向到返回页面

```typescript
const {buyNow} = useReturnsShopNow({
  platform: 'shopify',
});

buyNow?.(lineItem);
```

4.3.3. 归来 当用户在返回页面中单击返回按钮时,您应该拨打 goBack, 它会自动重定向到商店页面

```typescript
const {goBack} = useReturnsShopNow({
  platform: 'shopify',
});

goBack?.();
```

恭喜,你现在熟悉 efa sdk的核心过程

| 步骤 | 特性 | 关键方法/成果 | 说明 |
| --- | --- | --- | --- |
| 1个 | 流量检测 | `isFromEFA` 从使用ReturnsShop现在 | 确定当前流量是否为全民教育进程 |
| 2个 | 墨盒初始化 | `initCart(lineItems)` | 初始化推车并计算价格 |
| 3个 | 墨盒操作 | `updateCart(lineItems)`  
`addCart(lineItem)`  
`removeFromCart(lineItem)` | 搬运物品的管理方法 |
| 3.1 国家 | 贴现代码 | `setDiscountCodes(codes: string[])` | 为推车设定适用的折扣代码 |
| 页:1 | 导航方法 | `checkout()`  
`buyNow()`  
`goBack()` | 返回返回页面的方法 |
| 页:1 | 价格访问 | `price` 从 `shopContext` | 获取数额和货币信息 |

#### 📦 此外,还提供一些外出能力

如果您想要使用默认的 Return UI 横幅来显示, 我们已将其包装为您使用的 React 组件 .

1,回归ShopNow Banner

```typescript
import {ReturnsShopNowBanner} from '@aftership/shop-now/react';

export interface IBannerStyleConfig {
  background?: string;
  font?: string;
  opacity?: number;
}
interface IReturnsShopNowBannerProps {
  styleConfig: IBannerStyleConfig;
  creditText: string;
}

const {shopContext} = useReturnsShopNow({
  platform: 'shopify',
});

<ReturnsShopNowBanner styleConfig={shopContext?.style} creditText={} />;
```

您可以调用 shopContext ?. style 以返回管理器配置横幅样式, 或者您可以自己覆盖它们

2\. 错误处理 对于错误处理, SDK 提供了一个错误字段让外部代码意识到 SDK 内部发生的错误

SDK会从计算 API 中返回出错,这些错误可以分类为会话过期和内部 API 出错. 如果会话已过期, 您需要返回返回页面并再次启动返回进程 。 如果存在内部API错误,请联系我们.

注:储存过程中单次返回的全民教育最长期限为30分钟。 如果会议超过30分钟,会议将结束.

```typescript
const {error} = useReturnsShopNow({
  platform: 'shopify',
});

const isSessionExpired = error.type === 'SESSION_EXPIRED';
const isApiError = error.type === 'API_ERROR';

console.log(error);
```

`error` 是一个州。 如果你想清除错误,你可以打电话 `clearError` 清理的方法.

```typescript
const {clearError} = useReturnsShopNow({
  platform: 'shopify',
});
```

3, 使用返回信用翻译 如果您想让信用文本字体与返回管理员保持一致, 您可以调用 getCredit Translation 调用后文本方法 翻译、 转出金额和货币以获取信用文本

```typescript
const {shopContext, initTranslation, getCreditTranslationText} =
  useReturnsShopNow({
    platform: 'shopify',
  });

useEffect(() => {
  initTranslation?.();
}, [initTranslation]);

const creditText = useMemo(() => {
  return (
    getCreditTranslationText?.(
      shopContext?.price?.amount,
      shopContext?.price?.currency,
    ) ?? '--'
  );
}, [shopContext]);
```

## 常见问题

### @aftership/shop-now 是什么？

现在的返回商店库

### 如何安装 @aftership/shop-now？

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

### @aftership/shop-now 支持 TypeScript 吗？

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

### @aftership/shop-now 支持 ESM 还是 CommonJS？

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

### @aftership/shop-now 可以商用吗？

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

### @aftership/shop-now 的下载量有多少？

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

### @aftership/shop-now 还在维护吗？

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