# SiteConfig 参数说明

这是 `realibox-ui-sdk` 页面配置的完整入口。配置可以传给：

- 全局初始化：`initSDK({ key, mode, siteConfig })`
- 单个组件：`<product-list-page site-config="...">`
- 框架组件属性：React/Vue 中直接传对象或 JSON 字符串

组件级 `site-config` 优先级高于全局 `initSDK.siteConfig`。

## 参数目录

| 模块 | 常用参数 |
| --- | --- |
| [新建 Catalog 官网实例](./catalog-instance/README.md) | 初始化、路由、列表页、详情页、部署和联调清单 |
| [快速开始](./getting-started/README.md) | [`siteConfig`](./getting-started/README.md#siteconfig), [`locale`](./getting-started/README.md#locale), [`messages`](./getting-started/README.md#messages) |
| [主题 Theme](./theme/README.md) | [`primaryColor`](./theme/README.md#primarycolor), [`borderRadius`](./theme/README.md#borderradius), [`fontFamily`](./theme/README.md#fontfamily) |
| [品牌与站点壳](./shell/README.md) | [`brand`](./shell/README.md#brand), [`navItems`](./shell/README.md#navitems), [`footer`](./shell/README.md#footer) |
| [产品列表](./product-list/README.md) | [`pageSize`](./product-list/README.md#pagesize), [`gridColumns`](./product-list/README.md#gridcolumns), [`categorySelection`](./product-list/README.md#categoryselection), [`has3d`](./product-list/README.md#has3d) |
| [产品详情](./product-detail/README.md) | [`galleryLayout`](./product-detail/README.md#gallerylayout), [`recommendLimit`](./product-detail/README.md#recommendlimit), [`recommendColumns`](./product-detail/README.md#recommendcolumns), [`recommendTitleFontSize`](./product-detail/README.md#recommendtitlefontsize), [`dynamicFields`](./product-detail/README.md#dynamicfields) |
| [筛选 FilterFields](./filters/README.md) | [`source`](./filters/README.md#source), [`target`](./filters/README.md#target), [`scope`](./filters/README.md#scope), [`scope: has_3d`](./filters/README.md#scope-has_3d), [`hideUnit`](./filters/README.md#hideunit) |
| [详情字段 DetailFields](./detail-fields/README.md) | [`source`](./detail-fields/README.md#source), [`target`](./detail-fields/README.md#target), [`sort`](./detail-fields/README.md#sort) |
| [文案与枚举](./aliases/README.md) | [`aliases`](./aliases/README.md#aliases), [`enumWhitelist`](./aliases/README.md#enumwhitelist), [`attributeMappings`](./aliases/README.md#attributemappings) |
| [3D 配置器](./viewer-controls/README.md) | [`viewerControls`](./viewer-controls/README.md#viewercontrols), [`colorPicker`](./viewer-controls/README.md#colorpicker), [`gradient`](./viewer-controls/README.md#gradient), [`graphicCustomization`](./viewer-controls/README.md#graphiccustomization) |
| [3D Viewer / 配置器 CSS 覆盖](./css-customization/README.md) | 布局变量、稳定选择器、长文本、对象可见性和响应式覆盖 |
| [SDK API](../../sdk-api/README.md) | `product-3d-viewer` 方法、Graphics2D、场景快照、事件和资源包 |

## 按功能查找

如果已经知道要改什么展示效果，可以从这里直接进入对应配置。

| 我要实现 | 主要配置 | 文档入口 |
| --- | --- | --- |
| 新建一个官网 Catalog | `initSDK`、`routerMode`、`siteConfig`、`product-list-page`、`product-detail-page` | [新建 Catalog 官网实例](./catalog-instance/README.md) |
| 配置品牌 Logo 和 Header | `brand.logoUrl`、`brand.name`、`navItems`、`productList.showHeader`、`productDetail.showHeader` | [品牌与站点壳](./shell/README.md#brand) |
| 配置 Footer | `footer`、`productList.showFooter`、`productDetail.showFooter` | [品牌与站点壳](./shell/README.md#footer) |
| 改主题色、圆角、字体 | `theme.primaryColor`、`theme.activeColor`、`theme.borderRadius`、`theme.fontFamily` | [主题 Theme](./theme/README.md) |
| 改列表列数 | `productList.gridColumns` | [产品列表](./product-list/README.md#gridcolumns) |
| 改每次加载数量 | `productList.pageSize` | [产品列表](./product-list/README.md#pagesize) |
| 把搜索框放到 Header | `productList.searchPlacement` | [产品列表](./product-list/README.md#searchplacement) |
| 配置左侧主筛选 | `productList.primaryFilter`、`productList.showPrimaryFilter` | [产品列表](./product-list/README.md#primaryfilter) |
| 配置普通筛选项 | `filterFields`、`filterDisplay`、`filterPresets` | [筛选 FilterFields](./filters/README.md) |
| 配置是否有 3D 的筛选 | `filterFields[].scope: "has_3d"` | [筛选 FilterFields](./filters/README.md#scope-has_3d) |
| 隐藏产品编码 | `productCard.showCode`、`productDetail.showProductCode` | [产品详情](./product-detail/README.md#showproductcode) |
| 改详情图库方向和箭头 | `productDetail.galleryLayout`、`productDetail.showGalleryArrows` | [产品详情](./product-detail/README.md#gallerylayout) |
| 配置推荐区 | `productDetail.recommendLimit`、`recommendColumns`、`recommendTitleAlign`、`recommendTitleFontSize` | [产品详情](./product-detail/README.md#recommendlimit) |
| 控制详情参数字段 | `detailFields`、`productDetail.dynamicFields` | [详情字段](./detail-fields/README.md), [产品详情](./product-detail/README.md#dynamicfields) |
| 配置多语言静态文案 | `locale`、`messages` | [快速开始](./getting-started/README.md#messages) |
| 覆盖后端 code/value 显示名 | `aliases.categories`、`aliases.attributes`、`aliases.attributeValues`、`aliases.recommendTypes` | [文案与枚举](./aliases/README.md#aliases) |
| 限制展示的分类或枚举 | `enumWhitelist.categories`、`enumWhitelist.attributeValues` | [文案与枚举](./aliases/README.md#enumwhitelist) |
| 控制 3D 配置器按钮 | `viewerControls` | [3D 配置器](./viewer-controls/README.md#viewercontrols) |
| 覆盖 3D Viewer / 配置器样式 | CSS 变量、稳定 `.pv-*` 选择器 | [CSS 样式覆盖](./css-customization/README.md) |

## 顶层结构

```ts
interface SiteConfig {
  locale?: string;
  messages?: I18nMessageOverrides;
  aliases?: AliasConfig;
  attributeMappings?: Record<string, string | AttributeMappingConfig>;
  enumWhitelist?: EnumWhitelistConfig;
  filterDisplay?: "configured" | "all";
  filterFields?: FilterFieldConfig[];
  filterPresets?: Record<string, FilterPresetOption[]>;
  detailFields?: DetailFieldConfig[];
  viewerControls?: ViewerControlsConfig;
  productCard?: ProductCardConfig;
  productList?: ProductListConfig;
  productDetail?: ProductDetailConfig;
  theme?: ThemeConfig;
  brand?: BrandConfig;
  navItems?: NavItemConfig[];
  footer?: FooterConfig;
}
```

## 推荐对接流程

1. 先按 [快速开始](./getting-started/README.md) 接入 `siteConfig`。
2. 对照 [筛选配置](./filters/README.md) 确认 `source` / `target` / `scope` 是否正确。
3. 对照产品列表、产品详情和主题文档补齐页面展示需求。
4. 在接入项目中通过 `initSDK({ siteConfig })` 或组件 `site-config` 传入配置。