商品 SDK 组件

介绍

本项目提供了一套用于快速集成商品展示、交易、支付、地址管理等功能的组件。

组件概览

| 组件名 | 描述 | | ------------------ | ------------------------ | | ProductButton | 商品操作按钮 | | ProductList | 商品列表 | | ProductItem | 商品卡片 | | ProductListPopup | 带弹层的商品列表 | | ProductDetail | 商品详情 | | ProductDetailPopup| 带弹层的商品详情 | | OrderList | 订单列表 | | OrderItem | 订单卡片 | | OrderListPopup | 带弹层的订单列表 | | OrderDetail | 订单详情 | | OrderConfirm | 订单确认 | | OrderPopup | 带弹层及收货地址管理的订单确认 | | AddressList | 收货地址列表 | | AddressItem | 收货地址卡片 | | AddressEdit | 收货地址编辑/新建 |

运行项目

在启动项目前，请确保你已经安装了以下依赖：

• Node.js: >=20.17.0
• pnpm: >=10.8.0

启动项目：

# 在项目根目录下执行
pnpm dev

或者，如果仅需构建 UI 包并监听变化：

cd packages/ui
pnpm dev

组件详细说明

ProductButton 商品操作按钮

Props

| 参数 | 说明 | 类型 | 默认值 | | --------------- | ------------ | ----------------------------- | ------- | | productTarget | 商品 SDK 实例 | Object | - (必填) | | productConfig | 商品配置 | ProductConfig | {} | | productData | 商品数据 | ProductData | - (必填) | | disabled | 是否禁用 | Boolean | false |

ProductConfig 类型定义：

/**
 * 获取链接参数
 */
type GetLinkParams = (url: string) => Record<string, unknown>;

interface ProductConfig {
  /**
   * 获取链接参数
   */
  getLinkParams?: GetLinkParams;
  /**
   * 自定义商品按钮的禁用逻辑
   */
  customProductDisabled?: (productData: ProductData) => boolean;
  /**
   * 自定义商品按钮点击
   */
  customClickButtonHandler?: (productData: ProductData) => unknown;
  /**
   * 自定义商品看讲解点击
   */
  customClickExplainHandler?: (productData: ProductData) => unknown;
  /**
   * 是否为预览模式
   * @default false
   */
  isPreviewMode?: boolean;
  /** 预览商品列表 */
  previewProductList?: ProductData[];
}

Events

| 事件名 | 说明 | 参数类型 | | ------------ | -------- | ---------------------- | | direct-buy | 监听直接购买 | ProductData |

ProductList 商品列表

Props

| 参数 | 说明 | 类型 | 默认值 | | --------------- | ------------ | --------------------------- | ------- | | productTarget | 商品 SDK 实例 | Object | - (必填) | | productConfig | 商品配置 | Object (ProductConfig) | {} | | paymentTarget | 支付实例 | Object (Payment instance) | - (必填) |

ProductItem 商品卡片

Props

| 参数 | 说明 | 类型 | 默认值 | | --------------- | -------------- | --------------------------- | ------- | | productTarget | 商品 SDK 实例 | Object | - (必填) | | productConfig | 商品配置 | Object (ProductConfig) | {} | | product | 单个商品数据 | Object (ProductData) | - (必填) |

Events

| 事件名 | 说明 | 参数类型 | | ---------------------- | ---------------- | --------------- | | click-explain | 点击讲解时触发 | ProductData | | click-product-item | 点击商品项时触发 | ProductData | | direct-buy | 点击直接购买时触发 | ProductData |

ProductListPopup 商品列表（弹层）

Props

| 参数 | 说明 | 类型 | 默认值 | | --------------- | ------------ | --------------------------- | ------- | | productTarget | 商品 SDK 实例 | Object | - (必填) | | productConfig | 商品配置 | Object (ProductConfig) | {} | | paymentTarget | 支付实例 | Object (Payment instance) | - (必填) |

Instance

| 方法名 | 描述 | 参数 | 返回值 | | --------- | -------- | ---- | ------ | | open() | 打开弹窗 | 无 | void | | close() | 关闭弹窗 | 无 | void |

ProductDetail 商品详情

Props

| 参数 | 说明 | 类型 | 默认值 | | --------------- | ------------ | --------------------------- | ------- | | productTarget | 商品 SDK 实例 | Object (Product instance) | - (必填) | | productConfig | 商品配置 | Object (ProductConfig) | {} | | productId | 商品 ID | Number | - (必填) |

Events

| 事件名 | 说明 | 参数类型 | | ------ | ---------- | -------- | | play | 视频播放时触发 | void | | pause| 视频暂停时触发 | void |

ProductDetailPopup 商品详情弹窗

Props

| 参数 | 说明 | 类型 | 默认值 | | --------------- | ------------ | --------------------------- | ------- | | productTarget | 商品 SDK 实例 | Object | - (必填) | | productConfig | 商品配置 | Object (ProductConfig) | {} |

Events

| 事件名 | 说明 | 参数类型 | | ------ | ---------- | -------- | | play | 视频播放时触发 | void | | pause| 视频暂停时触发 | void |

ProductDetailPopup Instance

| 方法名 | 描述 | 参数 | 返回值 | | --------- | -------- | ---- | ------ | | open() | 打开弹窗 | 无 | void | | close() | 关闭弹窗 | 无 | void |

OrderList 订单列表

Props

| 参数 | 说明 | 类型 | 默认值 | | --------------- | ----------- | --------------------------- | ------- | | orderTarget | 订单 SDK 实例 | Object | - (必填) | | paymentTarget | 支付实例 | Object (Payment instance) | - (必填) |

Events

该组件目前没有直接对外声明的事件。

OrderDetail 订单详情

Props

| 参数 | 说明 | 类型 | 默认值 | | --------------- | -------------- | --------------------------- | --------- | | orderTarget | 订单 SDK 实例 | Object | - (必填) | | paymentTarget | 支付实例 | Object (Payment instance) | - (必填) | | syncPayStatus | 是否同步支付状态 | Boolean | false | | orderNo | 订单号 | String | - (必填) |

Events

该组件目前没有直接对外声明的事件。

OrderPopup 订单确认（弹层）

Props

| 参数 | 说明 | 类型 | 默认值 | | --------------- | ---------------- | --------------------------- | ------- | | orderTarget | 订单 SDK 实例 | Object | - (必填) | | paymentTarget | 支付实例 | Object | - (必填) | | addressTarget | 地址 SDK 实例 | Object | - (必填) | | value | 当前选中的地址ID | String | - (必填) |

Instance

| 方法名 | 描述 | 参数 | 返回值 | | --------- | -------- | ---- | ------ | | open() | 打开弹窗 | 无 | void | | close() | 关闭弹窗 | 无 | void |

AddressList 地址列表

Props

| 参数 | 说明 | 类型 | 默认值 | | --------------- | ---------------- | --------------------------- | ------- | | addressTarget | 地址 SDK 实例 | Object | - (必填) | | value | 当前选中的地址ID | String | - (必填) |

Events

| 事件名 | 说明 | 参数类型 | | ---------------- | ------------------ | --------------- | | input | v-model更新选中地址ID | String | | add-address | 点击添加地址按钮时触发 | void | | choose-address | 选择某个地址时触发 | AddressData | | edit-address | 点击编辑地址按钮时触发 | AddressData |

AddressEdit 地址编辑/创建

Props

| 参数 | 说明 | 类型 | 默认值 | | -------------- | ---------------------------------------------------------- | ---------------------------------------------- | ------ | | formList | 表单配置数组 | Array<AddressEditFormItem> | [] | | submitAction | 提交表单后的回调函数，参数为表单数据对象，返回 Promise | Function ((formValue: Record<number, any>) => Promise<void>) | - |

Events

该组件目前没有直接对外声明的事件。

OrderItem 订单列表项

Props

| 参数 | 说明 | 类型 | 默认值 | | ------- | ------------ | ------------------------ | ------- | | order | 单个订单数据 | Object (OrderData) | - (必填) |

Events

| 事件名 | 说明 | 参数类型 | | ------------------------ | ------------------------------------ | --------------------------------------------- | | click-purchase-product | 点击订单中的某个商品时触发 | String (orderNo) | | click-order-btn | 点击订单操作按钮（如付款、查看物流）时触发 | Object ({ orderNo: string, orderStatus: string }) |

OrderListPopup 订单列表（弹层）

Props

| 参数 | 说明 | 类型 | 默认值 | | --------------- | ----------- | --------------------------- | ------- | | orderTarget | 订单 SDK 实例 | Object | - (必填) | | paymentTarget | 支付实例 | Object| - (必填) |

Component Instance

| 方法名 | 描述 | 参数 | 返回值 | | --------- | -------- | ---- | ------ | | open() | 打开弹窗 | 无 | void | | close() | 关闭弹窗 | 无 | void |

OrderConfirm 订单确认

Props

| 参数 | 说明 | 类型 | 默认值 | | --------------- | ---------------- | --------------------------- | ------- | | orderTarget | 订单 SDK 实例 | Object | - (必填) | | paymentTarget | 支付实例 | Object | - (必填) | | addressTarget | 地址 SDK 实例 | Object | - (必填) | | products | 待确认商品列表 | Array<OrderProductData> | [] |

Events

| 事件名 | 说明 | 参数类型 | | -------------- | -------------- | ------------------------------------------------------------------------------------------------------- | | submit-order | 提交订单时触发 | SubmitOrderParams |

SubmitOrderParams 类型定义：

interface SubmitOrderParams {
  sku: { productId: number; quantity: number }[];
  address?: AddressData;
  phone: string;
  paymentMethod: OrderPayProviderType;
}

AddressItem 地址列表项

Props

| 参数 | 说明 | 类型 | 默认值 | | ------------- | ------------ | ------------------------ | ------- | | addressInfo | 单个地址信息 | Object (AddressData) | - (必填) |

Events

| 事件名 | 说明 | 参数类型 | | ---------------- | ---------------- | ------------- | | choose-address | 选择该地址时触发 | AddressData |