# 3D 配置器 ViewerControls

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

`viewerControls` 控制 3D 配置器中哪些模块可见。

```json
{
  "viewerControls": {
    "graphicCustomization": false,
    "objectSelection": true,
    "materialSelection": true,
    "surfaceProcess": true,
    "colorPicker": true,
    "pantone": true,
    "rgb": true,
    "cmyk": true,
    "gradient": true,
    "graphicCustomization": false
  }
}
```

## viewercontrols

所有配置项的容器。

## objectselection

显示部件对象切换。SDK 鼠标点选的最终条件为 `graphicCustomization && objectSelection`；程序化 `selectObject()` 不受影响。

## graphiccustomization

是否启用贴图区域的图片、文字、变换、表面工艺、保存和放弃能力，默认 `false`。只有 Viewer 的构建能力和该开关都启用时才显示面板。

本地图片上传不属于 SiteConfig。内置图文面板会把用户选择的 `File`/`Blob` 原样传给 Viewer，不由 ui-sdk 上传或压缩；宿主如需跨页面保存本地资源，应使用 `exportSceneBundle()` / `loadSceneBundle()`，把清单保存为 JSON、把 Blob 保存到 IndexedDB 等二进制存储。

## materialselection

显示材质选择。

## surfaceprocess

显示工艺 / 表面处理选择。

## colorpicker

显示颜色模块。

## pantone

显示 Pantone 色彩模式。

## rgb

显示 RGB 色彩模式。

## cmyk

显示 CMYK 色彩模式。

## gradient

显示渐变相关功能。

## graphiccustomization

显示“外观配置 / 图案与工艺”模式切换。默认关闭。开启后，SDK 会在 Viewer 加载完成时检查 Graphics2D protocol v1 和可编辑区域；只有能力可用时才显示入口。

图案与工艺面板支持添加多个贴图和多个文字，并提供当前可用字体、字重、文字颜色、表面工艺、大小、横纵位置、旋转和翻转。图片文件不会由 ui-sdk 上传；离开编辑或切换区域时默认 rollback。拖动使用低成本预览，松开后由 Viewer 按设备能力生成最高 4096 的自适应最终纹理。

新增文字默认使用 `messages["configurator.graphicsDefaultText"]`。可通过多语言 `messages` 配置业务默认文案：

```ts
const siteConfig = {
  viewerControls: { graphicCustomization: true },
  messages: {
    "configurator.graphicsDefaultText": {
      "zh-CN": "品牌名称",
      en: "Brand name",
    },
  },
};
```

完整的编程接口、事件和场景资源包约束见 [SDK API 文档](../../sdk-api/README.md)。

## loading

切换到 3D 时，在 3D 预览完成初始化前会显示 loading 状态；配置器会等待对象和工艺数据准备完成后再展示可配置项。