realibox-ui-sdk

realibox-ui-sdk 用于在网页中嵌入 product-3d-viewer 组件。

安装

npm install realibox-ui-sdk

或

pnpm add realibox-ui-sdk

使用流程

接入分为两步：

1. 调用 initSDK 完成初始化
2. 在页面中使用 <product-3d-viewer> 组件

初始化

使用组件前必须先执行 initSDK。

import { initSDK } from "realibox-ui-sdk";

initSDK({
  key: "your-key",
  mode: "development",
});

initSDK 参数说明

| 参数名 | 类型 | 是否必填 | 说明 | | -------- | ------------------------------- | -------- | --------------------------------------------------------------------- | | key | string | 是 | SDK 授权密钥。不能为空。 | | mode | "development" \| "production" | 是 | SDK 运行环境。development 使用测试环境，production 使用正式环境。 | | locale | string | 否 | 默认语言（如 "zh-CN"、"en"）。不传则自动读取浏览器语言。 |

语言解析优先级（从高到低）：组件级 site-config.locale > initSDK({ locale }) > 浏览器语言 > "zh-CN"。

除内置 UI 文案外，分类 / 属性 / 属性值 / 布尔等数据驱动文案可通过 site-config.aliases 自定义分语言显示名（详见示例工程 README 的「数据别名 aliases」一节）。

官网 SiteConfig 配置

product-list-page 和 product-sidebar 的筛选侧边栏通过 siteConfig.filterFields 配置。字段可映射为后端属性筛选（默认 scope: "attribute"），也可配置为推荐类型筛选（scope: "recommend_type"）。静态筛选项使用 options，依赖后端 /filter-options 的字段可设置 hideWhenNoOptions: true 在无可用选项时自动隐藏。

新增配置能力：

• filterDisplay: "configured" | "all"：控制筛选项部分展示或全部动态展示。
• scope: "has_3d"：把单选筛选映射为顶层 has_3d 参数，不进入属性 filters。
• enumWhitelist：按分类 code / 属性 value 白名单过滤前端展示。
• aliases.recommendTypes：推荐类型独立别名映射。
• productDetail.dynamicFields.flattenJson：详情页 JSON 动态字段平铺展示，默认开启。
• productDetail.showGalleryArrows / showProductCode / 标题字号配置：控制详情页图库和标题区样式。

siteConfig.ts 与 JSON 的区别：

• siteConfig.ts 适合工程接入：可以写函数、按 locale 动态生成文案、复用常量，并获得 TypeScript 类型检查。
• JSON 适合迁移和外部系统：只能保存纯数据，不能写函数或注释，可直接作为 Web Component 的 site-config JSON 字符串。

完整 siteConfig 参数目录见 docs/site-config/README.md。

组件

组件名：product-3d-viewer

组件参数说明

不同接入方式下，参数名的命名规范不同：

| 参数名 (React/Vue) | 参数名 (HTML/CDN) | 类型 | 是否必填 | 说明 | | :--- | :--- | :--- | :--- | :--- | | projectId | project-id | string | 是 | 3D 项目 ID | | partSelection | part-selection | boolean | 否 | 部件切换 | | cameraFocus | camera-focus | boolean | 否 | 相机聚焦 | | design | design | boolean | 否 | 设计 | | outlineRender | outline-render | boolean | 否 | 描边 |

示例

HTML

<script type="module">
  import { initSDK } from "realibox-ui-sdk";

  initSDK({
    key: "your-key",
    mode: "development",
  });
</script>

<product-3d-viewer project-id="your-project-id"></product-3d-viewer>

React

import { initSDK } from "realibox-ui-sdk";

initSDK({
  key: "your-key",
  mode: "development",
});

export default function App() {
  return <product-3d-viewer projectId="your-project-id" />;
}

如果 React 项目运行时走 CDN，而不是 import "realibox-ui-sdk"，需要额外引入一次 React 类型入口：

import type {} from "realibox-ui-sdk/react";

这样 TypeScript 才能识别 <product-3d-viewer />。

Vue

Vue 使用 Web Components 时，需要先将 product-3d-viewer 声明为自定义元素。

vite.config.js

import vue from "@vitejs/plugin-vue";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag === "product-3d-viewer",
        },
      },
    }),
  ],
});

src/vite-env.d.ts

/// <reference types="vite/client" />

import type {} from "realibox-ui-sdk/vue";

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "jsx": "preserve",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "skipLibCheck": true,
    "types": ["vite/client"]
  },
  "vueCompilerOptions": {
    "strictTemplates": true
  },
  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.vue"]
}

App.vue

<script setup lang="ts">
import { initSDK } from "realibox-ui-sdk";

initSDK({
  key: "your-key",
  mode: "development",
});
</script>

<template>
  <product-3d-viewer projectId="your-project-id" />
</template>

CDN

<script src="https://cdn.jsdelivr.net/npm/realibox-ui-sdk@latest/dist/realibox-ui-sdk.umd.js"></script>
<script>
  window.RealiboxUISDK.initSDK({
    key: "your-key",
    mode: "development",
  });
</script>

<product-3d-viewer project-id="your-project-id"></product-3d-viewer>

如果是在 React / TypeScript 项目中通过 CDN 使用 SDK，推荐：

1. 运行时继续使用 CDN 脚本和 window.RealiboxUISDK
2. 类型检查通过 npm 安装 SDK，并在类型文件中引入：

import type {} from "realibox-ui-sdk/react";