Back to Details

bitrix-catalog

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Trade Catalog Module

Trade Catalog模块

Baseline: main 23.0+. Features newer than baseline are marked Since.
Catalog attaches commerce data to iblock elements. Requires 
iblock
+ 
catalog
. Cart/orders live in 
sale
— see skill 
bitrix-sale
.
php
\Bitrix\Main\Loader::includeModule('iblock');
\Bitrix\Main\Loader::includeModule('catalog');
Product ID = iblock element ID. Trade row: 
b_catalog_product
(
ProductTable
). Prices: 
b_catalog_price
(
PriceTable
). Catalog↔iblock link: 
b_catalog_iblock
(
CatalogIblockTable
/ 
CCatalog
).
基准版本：main 23.0+。晚于基准版本的功能会标记Since。
Catalog模块将商务数据关联到iblock元素。需要同时引入
iblock
和
catalog
模块。购物车/订单功能位于
sale
模块中——可参考技能
bitrix-sale
。
php
\Bitrix\Main\Loader::includeModule('iblock');
\Bitrix\Main\Loader::includeModule('catalog');
产品ID = iblock元素ID。交易记录行：
b_catalog_product
（对应
ProductTable
）。价格表：
b_catalog_price
（对应
PriceTable
）。Catalog与iblock的关联表：
b_catalog_iblock
（对应
CatalogIblockTable
/ 
CCatalog
）。

Linking an Iblock to Catalog

将Iblock关联到Catalog模块

Register the product iblock as a catalog:
php
\CCatalog::Add([
    'IBLOCK_ID' => $productIblockId,
    'YANDEX_EXPORT' => 'N',
    'SUBSCRIPTION' => 'N',
]);
Read binding via ORM:
php
$row = \Bitrix\Catalog\CatalogIblockTable::getByPrimary($productIblockId)->fetch();
// IBLOCK_ID, PRODUCT_IBLOCK_ID, SKU_PROPERTY_ID, VAT_ID, …
Iblock catalog kinds (
CCatalogSku
, 
catalog/general/catalog_sku.php
):
ConstantMeaning
TYPE_CATALOG
(
D
)		Simple catalog (no SKU)
TYPE_PRODUCT
(
P
)		Product iblock with separate offers iblock
TYPE_OFFERS
(
O
)		Offers (SKU) iblock
TYPE_FULL
(
X
)		Product iblock that itself holds simple products + SKUs
php
$info = \CCatalogSku::GetInfoByIBlock($iblockId);
// CATALOG_TYPE, PRODUCT_IBLOCK_ID, SKU_PROPERTY_ID, …
将产品iblock注册为目录：
php
\CCatalog::Add([
    'IBLOCK_ID' => $productIblockId,
    'YANDEX_EXPORT' => 'N',
    'SUBSCRIPTION' => 'N',
]);
通过ORM读取关联信息：
php
$row = \Bitrix\Catalog\CatalogIblockTable::getByPrimary($productIblockId)->fetch();
// IBLOCK_ID, PRODUCT_IBLOCK_ID, SKU_PROPERTY_ID, VAT_ID, …
Iblock目录类型（定义于
CCatalogSku
，文件路径
catalog/general/catalog_sku.php
）：
常量含义
TYPE_CATALOG
(
D
)		简单目录（无SKU）
TYPE_PRODUCT
(
P
)		产品iblock，关联独立的报价iblock
TYPE_OFFERS
(
O
)		报价（SKU）iblock
TYPE_FULL
(
X
)		自身包含简单产品+SKU的产品iblock
php
$info = \CCatalogSku::GetInfoByIBlock($iblockId);
// CATALOG_TYPE, PRODUCT_IBLOCK_ID, SKU_PROPERTY_ID, …

Product Types (
ProductTable
)

产品类型（
ProductTable
）

Verified in 
catalog/lib/product.php
:
ConstantValueMeaning
TYPE_PRODUCT
1Simple product
TYPE_SET
2Set / bundle
TYPE_SKU
3Parent with offers
TYPE_OFFER
4Offer (SKU variant)
TYPE_FREE_OFFER
5Offer without parent link
TYPE_EMPTY_SKU
6SKU parent without offers
TYPE_SERVICE
7Service (no warehouse tracking)
php
use Bitrix\Catalog\ProductTable;

$product = ProductTable::getByPrimary($elementId, [
    'select' => ['ID', 'TYPE', 'QUANTITY', 'AVAILABLE', 'VAT_ID', 'VAT_INCLUDED'],
])->fetch();

ProductTable::update($elementId, [
    'QUANTITY' => 10,
    'QUANTITY_TRACE' => ProductTable::STATUS_YES,
    'CAN_BUY_ZERO' => ProductTable::STATUS_NO,
]);
Prefer 
\Bitrix\Catalog\Model\Product
for add/update when you need catalog automation (availability, parent SKU type, subscriptions). Legacy: 
CCatalogProduct
.
定义于
catalog/lib/product.php
：
常量值含义
TYPE_PRODUCT
1简单产品
TYPE_SET
2套装/捆绑商品
TYPE_SKU
3关联报价的父产品
TYPE_OFFER
4报价（SKU变体）
TYPE_FREE_OFFER
5无父产品关联的报价
TYPE_EMPTY_SKU
6无报价的SKU父产品
TYPE_SERVICE
7服务类产品（无需仓库跟踪）
php
use Bitrix\Catalog\ProductTable;

$product = ProductTable::getByPrimary($elementId, [
    'select' => ['ID', 'TYPE', 'QUANTITY', 'AVAILABLE', 'VAT_ID', 'VAT_INCLUDED'],
])->fetch();

ProductTable::update($elementId, [
    'QUANTITY' => 10,
    'QUANTITY_TRACE' => ProductTable::STATUS_YES,
    'CAN_BUY_ZERO' => ProductTable::STATUS_NO,
]);
当需要目录自动化功能（如可用性、父SKU类型、订阅）时，优先使用
\Bitrix\Catalog\Model\Product
进行新增/更新操作。遗留方案：
CCatalogProduct
。

SKU / Offers Pattern

SKU/报价模式

  1. Product iblock (parents) + offers iblock (variants).
  2. In the offers iblock: property 
    PROPERTY_TYPE = E
    , 
    LINK_IBLOCK_ID = product iblock
    (SKU link). Prefer 
    USER_TYPE = SKU
    (
    PropertyTable::USER_TYPE_SKU
    ).
  3. Register offers iblock as catalog linked to the product iblock:
php
\CCatalog::Add([
    'IBLOCK_ID' => $offersIblockId,
    'PRODUCT_IBLOCK_ID' => $productIblockId,
    'SKU_PROPERTY_ID' => $skuPropertyId, // E-property on offers iblock
]);
Parent elements get 
TYPE_SKU
; offer elements get 
TYPE_OFFER
. Customer buys a specific offer (or a simple 
TYPE_PRODUCT
when no SKU).
  1. 产品iblock（父产品） + 报价iblock（变体）。
  2. 在报价iblock中：属性
    PROPERTY_TYPE = E
    ，
    LINK_IBLOCK_ID = 产品iblock ID
    （SKU关联）。优先使用
    USER_TYPE = SKU
    （对应
    PropertyTable::USER_TYPE_SKU
    ）。
  3. 将报价iblock注册为关联到产品iblock的目录：
php
\CCatalog::Add([
    'IBLOCK_ID' => $offersIblockId,
    'PRODUCT_IBLOCK_ID' => $productIblockId,
    'SKU_PROPERTY_ID' => $skuPropertyId, // 报价iblock上的E类型属性
]);
父元素类型为
TYPE_SKU
；报价元素类型为
TYPE_OFFER
。客户购买的是特定报价（若无SKU则购买简单的
TYPE_PRODUCT
类型产品）。

Prices and Price Types

价格与价格类型

  • Price type (catalog group): 
    b_catalog_group
    → 
    Bitrix\Catalog\GroupTable
    (
    BASE
    , 
    NAME
    , …). Access: 
    GroupAccessTable
    / legacy 
    CCatalogGroup
    .
  • Price row: 
    Bitrix\Catalog\PriceTable
    — 
    PRODUCT_ID
    , 
    CATALOG_GROUP_ID
    , 
    PRICE
    , 
    CURRENCY
    , optional 
    QUANTITY_FROM
    / 
    QUANTITY_TO
    .
php
use Bitrix\Catalog\PriceTable;
use Bitrix\Catalog\GroupTable;

$base = GroupTable::getRow(['filter' => ['=BASE' => 'Y']]);

PriceTable::add([
    'PRODUCT_ID' => $elementId,
    'CATALOG_GROUP_ID' => (int)$base['ID'],
    'PRICE' => 1990.00,
    'CURRENCY' => 'RUB',
]);

$prices = PriceTable::getList([
    'filter' => ['=PRODUCT_ID' => $elementId],
    'select' => ['ID', 'PRICE', 'CURRENCY', 'CATALOG_GROUP_ID'],
])->fetchAll();
Legacy write helpers: 
CPrice
. VAT fields live on the product (
VAT_ID
, 
VAT_INCLUDED
).
  • 价格类型（目录组）：
    b_catalog_group
    → 
    Bitrix\Catalog\GroupTable
    （包含
    BASE
    、
    NAME
    等字段）。权限控制：
    GroupAccessTable
    / 遗留方案
    CCatalogGroup
    。
  • 价格记录行：
    Bitrix\Catalog\PriceTable
    — 包含
    PRODUCT_ID
    、
    CATALOG_GROUP_ID
    、
    PRICE
    、
    CURRENCY
    ，可选字段
    QUANTITY_FROM
    / 
    QUANTITY_TO
    。
php
use Bitrix\Catalog\PriceTable;
use Bitrix\Catalog\GroupTable;

$base = GroupTable::getRow(['filter' => ['=BASE' => 'Y']]);

PriceTable::add([
    'PRODUCT_ID' => $elementId,
    'CATALOG_GROUP_ID' => (int)$base['ID'],
    'PRICE' => 1990.00,
    'CURRENCY' => 'RUB',
]);

$prices = PriceTable::getList([
    'filter' => ['=PRODUCT_ID' => $elementId],
    'select' => ['ID', 'PRICE', 'CURRENCY', 'CATALOG_GROUP_ID'],
])->fetchAll();
遗留的写入辅助类：
CPrice
。VAT字段存储在产品表中（
VAT_ID
、
VAT_INCLUDED
）。

Stock and Stores (Overview)

库存与门店（概述）

  • Product-level qty: 
    ProductTable
    fields 
    QUANTITY
    , 
    QUANTITY_RESERVED
    , 
    QUANTITY_TRACE
    , 
    CAN_BUY_ZERO
    , 
    AVAILABLE
    .
  • Multi-store: 
    StoreTable
    (
    b_catalog_store
    ) + 
    StoreProductTable
    (
    b_catalog_store_product
    : 
    STORE_ID
    , 
    PRODUCT_ID
    , 
    AMOUNT
    , 
    QUANTITY_RESERVED
    ).
  • Documents / batches: 
    StoreDocumentTable
    , 
    StoreBatchTable
    , … — use for warehouse ops, not ad-hoc SQL.
php
use Bitrix\Catalog\StoreProductTable;

$amounts = StoreProductTable::getList([
    'filter' => ['=PRODUCT_ID' => $elementId],
    'select' => ['STORE_ID', 'AMOUNT', 'QUANTITY_RESERVED'],
])->fetchAll();
TYPE_SERVICE
products are not warehouse-tracked like ordinary goods.
  • 产品级库存数量：
    ProductTable
    中的字段
    QUANTITY
    、
    QUANTITY_RESERVED
    、
    QUANTITY_TRACE
    、
    CAN_BUY_ZERO
    、
    AVAILABLE
    。
  • 多门店模式：
    StoreTable
    （对应
    b_catalog_store
    ） + 
    StoreProductTable
    （对应
    b_catalog_store_product
    ：包含
    STORE_ID
    、
    PRODUCT_ID
    、
    AMOUNT
    、
    QUANTITY_RESERVED
    字段）。
  • 单据/批次：
    StoreDocumentTable
    、
    StoreBatchTable
    等——用于仓库操作，请勿直接使用SQL进行临时操作。
php
use Bitrix\Catalog\StoreProductTable;

$amounts = StoreProductTable::getList([
    'filter' => ['=PRODUCT_ID' => $elementId],
    'select' => ['STORE_ID', 'AMOUNT', 'QUANTITY_RESERVED'],
])->fetchAll();
TYPE_SERVICE
类型的产品无需像普通商品一样进行仓库跟踪。

Boundary with 
sale

与
sale
模块的边界划分

ConcernModule
Product card, type, qty, prices, stores
catalog
Basket, order, payment, delivery, shipments
sale
Basket lines reference catalog product/offer IDs; price resolution and discounts may involve both modules. Do not invent cart APIs inside 
catalog
— use skill 
bitrix-sale
.
关注点所属模块
产品卡片、类型、数量、价格、门店
catalog
购物车、订单、支付、配送、发货
sale
购物车记录行引用目录产品/报价ID；价格解析和折扣计算可能涉及两个模块。请勿在
catalog
模块内自行开发购物车API——请使用技能
bitrix-sale
。

API Choice

API选择

UsePrefer
Read product/price/store rows
ProductTable
, 
PriceTable
, 
StoreProductTable
, 
CatalogIblockTable
Write with catalog side effects
\Bitrix\Catalog\Model\Product
, 
CCatalog::Add/Update
Legacy admin / compatibility
CCatalogProduct
, 
CPrice
, 
CCatalogSku
Inspect 
bitrix/modules/catalog/lib/
before adopting newer 
v2
/ REST helpers — confirm against the project kernel.
使用场景优先方案
读取产品/价格/门店记录
ProductTable
、
PriceTable
、
StoreProductTable
、
CatalogIblockTable
写入并触发目录相关副作用
\Bitrix\Catalog\Model\Product
、
CCatalog::Add/Update
遗留后台/兼容性需求
CCatalogProduct
、
CPrice
、
CCatalogSku
在采用较新的
v2
/REST辅助类之前，请先查看
bitrix/modules/catalog/lib/
目录下的代码，并与项目内核版本进行确认。

Performance

性能优化建议

  • Batch price/stock updates; avoid per-item 
    CCatalogProduct::GetByID
    in loops/templates.
  • Cache list queries; warm after bulk import.
  • Load with ORM collections / joins, not N+1.
  • 批量更新价格/库存；避免在循环/模板中逐个调用
    CCatalogProduct::GetByID
    。
  • 缓存列表查询；批量导入后预热缓存。
  • 使用ORM集合/关联查询加载数据，避免N+1查询问题。

Checklist

检查清单

  • iblock
    + 
    catalog
    included.
  • Product iblock linked via 
    CCatalog::Add
    / 
    CatalogIblockTable
    .
  • SKU: offers iblock + 
    PRODUCT_IBLOCK_ID
    + 
    SKU_PROPERTY_ID
    .
  • Types use 
    ProductTable::TYPE_*
    .
  • Prices via 
    PriceTable
    / price types (
    GroupTable
    ).
  • Stock via catalog API / 
    StoreProductTable
    , not raw SQL.
  • Cart/orders delegated to 
    sale
    (
    bitrix-sale
    ).
  • 已引入
    iblock
    + 
    catalog
    模块。
  • 产品iblock已通过
    CCatalog::Add
    / 
    CatalogIblockTable
    完成关联。
  • SKU配置：报价iblock + 
    PRODUCT_IBLOCK_ID
    + 
    SKU_PROPERTY_ID
    。
  • 产品类型使用
    ProductTable::TYPE_*
    常量。
  • 价格通过
    PriceTable
    / 价格类型（
    GroupTable
    ）管理。
  • 库存通过目录API / 
    StoreProductTable
    管理，而非直接操作SQL。
  • 购物车/订单功能委托给
    sale
    模块（
    bitrix-sale
    ）。