# 快速开始

[返回目录](../README.md)

## siteconfig

`siteConfig` 是站点级配置对象。它用于描述站点展示差异：主题、品牌、筛选、详情字段、文案映射等。

```ts
import { initSDK, type SiteConfig } from "realibox-ui-sdk";

const siteConfig: SiteConfig = {
  locale: "en",
  productList: { pageSize: 24 },
};

initSDK({
  key: "YOUR_KEY",
  mode: "production",
  siteConfig,
});
```

推荐规则：

- 官网 Catalog 实例通常在 `initSDK({ siteConfig })` 里放默认配置，避免每个页面重复传参。
- 如果列表页和详情页需要跟随语言切换、A/B 配置或 CMS 配置实时变化，可以给组件传 `site-config`；组件级配置会覆盖全局配置。
- React / Vue 工程里可以直接维护 `SiteConfig` 对象，最终传对象或 `JSON.stringify(siteConfig)` 都可以。
- HTML / CDN 场景只能通过属性传字符串，因此 `site-config` 必须是合法 JSON。

HTML / CDN 场景可以把 JSON 字符串传给组件：

```html
<product-list-page site-config='{"locale":"en"}'></product-list-page>
```

示例工程默认显式传入 `locale: "en"`；SDK core 未传 locale 时仍按下方优先级解析语言。

## 全局配置与组件配置

全局配置适合作为站点默认值：

```ts
initSDK({
  key: "YOUR_KEY",
  mode: "production",
  siteConfig,
});
```

组件配置适合页面级覆盖：

```html
<product-list-page site-config='{"productList":{"pageSize":24}}'></product-list-page>
```

优先级从高到低：

1. 组件级 `site-config`
2. `initSDK({ siteConfig })`
3. SDK 默认值

注意：组件级配置是覆盖当前组件读取到的配置，不会自动写回全局 `configManager`。如果希望列表页、详情页、Header 和 Footer 使用完全一致的配置，建议复用同一个 `siteConfig` 生成函数。

## locale

当前配置语言。优先级：

1. 组件级 `site-config.locale`
2. `initSDK({ locale })`
3. `initSDK({ siteConfig: { locale } })`
4. 浏览器语言
5. `"zh-CN"`

常用值：

| 值 | 说明 |
| --- | --- |
| `"zh-CN"` | 中文 |
| `"en"` | 英文 |

## messages

覆盖 SDK 内置静态 UI 文案，如按钮、标题、加载和错误状态。

旧的扁平格式仍可使用，并会应用到所有语言：

```json
{
  "messages": {
    "detail.params": "TECHNICAL DETAILS",
    "detail.viewerLoading": "Model loading, configuration will be available soon"
  }
}
```

一个配置需要跟随语言切换时，推荐为每个 key 提供语言映射。SDK 按精确语言（`en-US`）、基础语言（`en`）、`zh-CN` 的顺序取值；语言 key 不区分大小写。

```ts
const siteConfig: SiteConfig = {
  messages: {
    "configurator.graphicsDefaultText": {
      "zh-CN": "新文字",
      en: "New text",
      ja: "新しいテキスト",
    },
    "configurator.graphicsAddImage": {
      "zh-CN": "添加图片",
      en: "Add image",
    },
  },
};
```

`initSDK({ locale })` 会覆盖同次初始化中 `siteConfig.locale` 的默认语言；组件自身的 `site-config.locale` 仍拥有最高优先级。`messages` 是全局或组件配置的一部分，因此请在需要组件级文案差异时一并传入组件级 `site-config`。

数据驱动文案，如分类、属性、属性值，请使用 [aliases](../aliases/README.md#aliases)。