Skip to content

product ​

产品管理 - 产品 CRUD 和搜索

概述 ​

k.commerce.product 提供产品相关操作,包括创建、查询、更新、删除等。

TypeScript 定义 ​

ts
interface KProduct {
    get(seoNameOrId: string): Product;
    list(query?: ProductQueryParams): Product[];
    create(product: NewProduct): Product;
    delete(productId: string): boolean;
    search(keyword: string, options?: SearchOptions): SearchResult;
    updateField(productId: string, field: string, value: any, lang?: string): void;
    updateFields(productId: string, updateContents: UpdateContent[]): void;
    getDiscountPrice(variantId: string, options?: DiscountOptions): number;
    createVariant(productId: string, variant: NewVariant): Product;
    updateVariantField(variantId: string, field: string, value: any): void;
    updateVariantFields(variantId: string, updateContents: UpdateContent[]): void;
    addCategory(productId: string, categoryId: string): void;
    removeCategory(productId: string, categoryId: string): void;
    addFileDigitalItem(variantId: string, name: string, filePath: string): void;
    addLinkDigitalItem(variantId: string, name: string, linkUrl: string): void;
    addTextDigitalItem(variantId: string, name: string, text: string): void;
    removeDigitalItem(variantId: string, digitalId: string): void;
}

核心方法 ​

list() ​

获取产品列表。

ts
k.api.get(() => {
    const products = k.commerce.product.list()
    return { count: products.length, products }
})

参数:

参数类型必填说明
queryProductQueryParams否产品列表筛选条件。
query.categoriesstring[]否按分类 ID 筛选。
query.includeOfflineboolean否是否包含下架产品,默认 false。
query.includeSubCategoryboolean否是否包含子分类产品,默认 false。

返回值:Product[]。匹配条件的产品列表。

get() ​

获取产品详情(包括变体)。

异常处理

get 方法查询不到产品时会抛出异常 "Product not found"

参数:

参数类型必填说明
seoNameOrIdstring是产品 SEO 名称或产品 ID。

返回值:Product。产品详情,包含变体信息。

ts
k.api.get(() => {
    const product = k.commerce.product.get('product-seo-name')
    return { title: product.title, variants: product.variants }
})

// 异常处理示例
k.api.get(() => {
    try {
        return k.commerce.product.get('product-id')
    } catch (e) {
        return { error: e.message }
    }
})

create() ​

创建产品。

参数:

参数类型必填说明
productNewProduct是新产品数据。

返回值:Product。创建后的产品对象。

ts
k.api.post(() => {
    const product = k.commerce.product.create({
        title: '新产品',
        description: '产品描述',
        price: 99.9,
        active: true
    })
    return { id: product.id, title: product.title }
})

createVariant() ​

为产品创建变体。

参数:

参数类型必填说明
productIdstring是产品 ID。
variantNewVariant是新变体数据。

返回值:Product。更新后的产品对象。

ts
k.api.post(() => {
    const product = k.commerce.product.createVariant(productId, {
        sku: 'SKU-001',
        price: 88,
        inventory: 100
    })
    return { variantCount: product.variants.length }
})

搜索产品。

参数:

参数类型必填说明
keywordstring是搜索关键词。
optionsSearchOptions否搜索筛选条件。
options.categoriesstring[]否按分类 ID 筛选。
options.includeOfflineboolean否是否包含下架产品,默认 false。
options.includeSubCategoryboolean否是否包含子分类产品,默认 false。

返回值:SearchResult。搜索结果和聚合信息。

ts
k.api.get(() => {
    const result = k.commerce.product.search("关键词")
    return { count: result.list.length, facets: result.facets }
})

// 带参数筛选
k.api.get(() => {
    const result = k.commerce.product.search("关键词", {
        includeOffline: true,
        includeSubCategory: false
    })
    return { count: result.list.length }
})

updateField() ​

更新单个字段。

参数:

参数类型必填说明
productIdstring是产品 ID。
fieldstring是字段名。
valueany是字段值。
langstring否语言代码,用于指定多语言字段。

返回值:void。

ts
k.api.post(() => {
    // 普通更新
    k.commerce.product.updateField(productId, "title", "新标题")
    return { success: true }
})

// 多语言更新(lang 用于指定语言)
k.api.post(() => {
    k.commerce.product.updateField(productId, "title", "New Title", "en")
    return { success: true }
})

updateFields() ​

批量更新字段。

参数:

参数类型必填说明
productIdstring是产品 ID。
updateContentsUpdateContent[]是要批量更新的字段列表。
updateContents[].propertystring是字段名。
updateContents[].valueany是字段值。
updateContents[].langstring否语言代码,用于指定多语言字段。

返回值:void。

ts
k.api.post(() => {
    k.commerce.product.updateFields(productId, [
        { property: "title", value: "新标题", lang: "zh" },
        { property: "tags", value: ["tag1", "tag2"] }
    ])
    return { success: true }
})

updateVariantField() ​

更新变体字段。

参数:

参数类型必填说明
variantIdstring是变体 ID。
fieldstring是字段名。
valueany是字段值。

返回值:void。

ts
k.api.post(() => {
    k.commerce.product.updateVariantField(variantId, "sku", "NEW-SKU")
    return { success: true }
})

updateVariantFields() ​

批量更新变体字段。

参数:

参数类型必填说明
variantIdstring是变体 ID。
updateContentsUpdateContent[]是要批量更新的字段列表。
updateContents[].propertystring是字段名。
updateContents[].valueany是字段值。
updateContents[].langstring否语言代码,用于指定多语言字段。

返回值:void。

ts
k.api.post(() => {
    k.commerce.product.updateVariantFields(variantId, [
        { property: "sku", value: "NEW-SKU", lang: "zh" }
    ])
    return { success: true }
})

getDiscountPrice() ​

获取折扣价格。

参数:

参数类型必填说明
variantIdstring是变体 ID。
optionsDiscountOptions否折扣计算选项。

返回值:number。应用折扣后的价格。

ts
k.api.get(() => {
    const price = k.commerce.product.getDiscountPrice(variantId)
    return { price }
})

delete() ​

删除产品。

参数:

参数类型必填说明
productIdstring是要删除的产品 ID。

返回值:boolean。删除成功时返回 true。

ts
k.api.post(() => {
    const success = k.commerce.product.delete(productId)
    return { success }
})

分类与数字商品 ​

产品与分类的关联、以及数字商品(Digital Item)都挂在变体上。

addCategory() / removeCategory() ​

把产品加入 / 移出某个分类。

参数类型必填说明
productIdstring是产品 ID。
categoryIdstring是分类 ID。

返回值:void。

ts
k.api.post(() => {
    k.commerce.product.addCategory(productId, categoryId)
    k.commerce.product.removeCategory(productId, categoryId)
})

addTextDigitalItem() / addLinkDigitalItem() / addFileDigitalItem() ​

给变体添加数字商品项:文本、链接或站点内文件(如序列号、下载地址、电子书文件)。文件路径用 k.file 可读写的站点目录路径。

参数类型必填说明
variantIdstring是变体 ID。
namestring是数字商品名称,展示给顾客。
text / link / filePathstring是数字商品内容:文本、链接或文件路径。

返回值:void。

ts
k.api.post(() => {
    k.commerce.product.addTextDigitalItem(variantId, "License key", "XXXX-XXXX")
    k.commerce.product.addLinkDigitalItem(variantId, "Download", "https://example.com/file.zip")
    k.commerce.product.addFileDigitalItem(variantId, "E-book", "exports/book.pdf")
})

removeDigitalItem() ​

按数字商品 ID 移除某一项。数字商品列表见下方 Digital 属性。

参数类型必填说明
variantIdstring是变体 ID。
digitalIdstring是数字商品 ID。

返回值:void。

ts
k.api.post(() => {
    k.commerce.product.removeDigitalItem(variantId, digitalId)
})

产品结构 ​

Product 属性 ​

属性说明类型
id产品 IDstring
title产品名称string
description产品描述string
featuredImage主图string
images图片列表string[]
seoNameSEO 名称string
tags标签string[]
price价格(默认应用到第一个变体)number
inventory库存number
active是否启用boolean
isDigital是否数字产品boolean
autoDelivery是否自动发货boolean
variantImage变体图片string
maxDownloadCount最大下载次数(数字产品)number
maxDownloadDay最大下载天数(数字产品)number
attributes属性键值对{key: string, value: string}[]
variants变体列表Variant[]
categories分类列表Category[]

Variant 属性 ​

属性说明类型
id变体 IDstring
productId所属产品 IDstring
createdAt创建时间Date
updatedAt更新时间Date
skuSKU 编码string
barcode条码string
price价格number
inventory库存number
weight重量number
order排序number
sales销量number
active是否启用boolean
autoDelivery是否自动发货boolean
image变体图片string
selectedOptions选项(如颜色/尺寸){name: string, value: string}[]
digitals数字产品列表Digital[]

Digital 属性 ​

属性说明类型
id数字产品 IDstring
type类型'file' | 'image' | 'video'
name名称string
value内容(文件路径/链接/文本)string
contentType内容类型(仅 file 类型)string
size大小(仅 file 类型)number

相关文档 ​