# @buildcores/render-client 中文文档

规范地址：https://npmcn.com/package/%40buildcores/render-client/

版本：1\.7\.1
npm 元数据更新时间：2026-05-08T00:07:45.133Z
中文译文更新时间：2026-11-08T19:07:06.157Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40buildcores/render-client
原文对照：https://npmcn.com/package/%40buildcores/render-client/?lang=original
项目主页：https://github.com/buildcores/buildcores-render-client#readme
源码仓库：https://github.com/buildcores/buildcores-render-client

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：897 kB，27 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react \>=16\.8\.0，react-dom \>=16\.8\.0
- 首次发布：2025-08-04T18:03:25.884Z
- 最新版本发布：2026-05-08T00:07:45.002Z
- 近 30 天下载量：4559（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 7 个）

## 中文简介

交互式360度视频渲染的反射组件

## 安装

```sh
npm install @buildcores/render-client
```

也可以使用：`pnpm add @buildcores/render-client`、`yarn add @buildcores/render-client`、`bun add @buildcores/render-client`

## README

# @ buildcores/ render- 客户端

[文档](https://buildcores.github.io/buildcores-render-client/) | [技术 API 文件](https://buildcores.github.io/buildcores-render-client/technical-documentation/)

用于交互式360度PC构建渲染的 React 组件库,具有拖至scrub 功能. 创建计算机的浸入式3D可视化构建,用户可以旋转并探索.

![BuildRender Component](https://npmcn.com/package/%40buildcores/render-client/render-preview.png)

_交互式 三维 PC 构建, 用户可以通过拖放旋转_

## \* 安装

```bash
npm install @buildcores/render-client
```

## QQ 快速启动

```tsx
import React from "react";
import { BuildRender, getAvailableParts } from "@buildcores/render-client";

function App() {
  const parts = {
    parts: {
      CPU: ["7xjqsomhr"], // AMD Ryzen 7 9800X3D
      GPU: ["z7pyphm9k"], // ASUS GeForce RTX 5080 ASTRAL
      RAM: ["dpl1iyvb5"], // PNY DDR5
      Motherboard: ["iwin2u9vx"], // Asus ROG STRIX X870E-E GAMING WIFI
      PSU: ["m4kilv190"], // LIAN LI 1300W
      Storage: ["0bkvs17po"], // SAMSUNG 990 EVO
      PCCase: ["qq9jamk7c"], // MONTECH KING 95 PRO
      CPUCooler: ["62d8zelr5"], // ARCTIC LIQUID FREEZER 360
    },
  };

  return (
    <div>
      <BuildRender
        parts={parts}
        size={500}
        mouseSensitivity={0.2}
        touchSensitivity={0.2}
      />
    </div>
  );
}
```

## QQ 认证模式

`@buildcores/render-client` 支持两个认证模式:

-   `legacy` (后向相容性):从 `apiConfig.authToken`。 。 。 .
-   `session` (建议):从您的后端取出寿命短的委托符号 `apiConfig.getRenderSessionToken`。 。 。 .

```tsx
const apiConfig = {
  environment: "prod",
  authMode: "session",
  getRenderSessionToken: async () => {
    // Your backend endpoint should broker BuildCores /auth/render-session
    const res = await fetch("/buildcores/session", { method: "POST" });
    if (!res.ok) throw new Error("Failed to mint BuildCores session");
    const data = await res.json();
    return {
      token: data.session_token,
      expiresAt: data.expires_at,
    };
  },
};
```

遗留浏览器 API 密钥流被贬值,只应用于临时相容. `/render-build-experimental` 行为不变.

## API 参考

### `BuildRender` 构成部分

渲染交互式3D PC的主要反应组件构建.

#### 道具

| Prop | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `parts` | `RenderBuildRequest` | ✅ | \- 说吧 | PC 部件配置对象 |
| `size` | `number` | ✅ | \- 说吧 | 视频大小, 像素( 平方尺寸) |
| `mouseSensitivity` | `number` | ❌ | `0.2` | 鼠标拖曳灵敏度( 0.001-1) |
| `touchSensitivity` | `number` | ❌ | `0.2` | 触摸拖曳敏感性(0.001-1) |
| `modelQuality` | `"low" | "medium" | "high"` | ❌ | API 默认 | 服务器的 三维模型资产质量 |
| `showInteractiveConfigButton` | `boolean` | ❌ | `false` | 显示基于部件的扇/ 辐射器配置菜单 |
| `interactiveConfigPanelPosition` | `"top-left" | "top-right" | "bottom-left" | "bottom-right"` | ❌ | `"top-left"` | 嵌入式配置菜单打开的角落 |
| `interactiveConfigPanelHeight` | `"compact" | "max" | number | string` | ❌ | `"max"` | 嵌入式配置菜单的高度 |

#### 部件配置

这个 `parts` 道具使用 `RenderBuildRequest` 接口 :

```tsx
interface RenderBuildRequest {
  parts: {
    [K in PartCategory]?: string[];
  };
  format?: "video" | "sprite";
  width?: number;  // Optional: Canvas pixel width (256-2000)
  height?: number; // Optional: Canvas pixel height (256-2000)
  scene?: "sunset" | "dawn" | "night" | "warehouse" | "forest" | "apartment" | "studio" | "studio_v2" | "city" | "park" | "lobby";
  showBackground?: boolean;
  showGrid?: boolean;
  winterMode?: boolean; // mutually exclusive with springMode
  springMode?: boolean; // mutually exclusive with winterMode
}

// Available part categories
enum PartCategory {
  CPU = "CPU",
  GPU = "GPU",
  RAM = "RAM",
  Motherboard = "Motherboard",
  PSU = "PSU",
  Storage = "Storage",
  PCCase = "PCCase",
  CPUCooler = "CPUCooler",
}
```

**目前的限制**:每个类别数组必须包含精确的一部分ID. 今后版本将支持每个类别多个部分.

**分辨率控制**: 您可以指定自定义 `width` 财务报告和审定财务报表 `height` (两者必须一起提供,256-2000像素),以便提高或降低质量。 如果没有指定,则使用默认分辨率.

**环境控制**: 您可以配置 `scene`, (中文(简体) ), `showBackground`, (中文(简体) ), `showGrid`和季节性切换(`winterMode` 编号 : `springMode`用于合成成终点.

#### 实例

**完整构建( 所有组件)**

```tsx
const completeBuild = {
  parts: {
    CPU: ["7xjqsomhr"], // AMD Ryzen 7 9800X3D
    GPU: ["z7pyphm9k"], // ASUS GeForce RTX 5080 ASTRAL
    RAM: ["dpl1iyvb5"], // PNY DDR5
    Motherboard: ["iwin2u9vx"], // Asus ROG STRIX X870E-E GAMING WIFI
    PSU: ["m4kilv190"], // LIAN LI 1300W
    Storage: ["0bkvs17po"], // SAMSUNG 990 EVO
    PCCase: ["qq9jamk7c"], // MONTECH KING 95 PRO
    CPUCooler: ["62d8zelr5"], // ARCTIC LIQUID FREEZER 360
  },
};

<BuildRender parts={completeBuild} size={500} />;
```

**仅限大小写( 最小)**

```tsx
const caseOnly = {
  parts: {
    PCCase: ["qq9jamk7c"], // MONTECH KING 95 PRO
  },
};

<BuildRender parts={caseOnly} size={500} />;
```

**自定义分辨率( 高质量)**

```tsx
const highResBuild = {
  parts: {
    CPU: ["7xjqsomhr"],
    GPU: ["z7pyphm9k"],
    RAM: ["dpl1iyvb5"],
    Motherboard: ["iwin2u9vx"],
    PSU: ["m4kilv190"],
    Storage: ["0bkvs17po"],
    PCCase: ["qq9jamk7c"],
    CPUCooler: ["62d8zelr5"],
  },
  width: 1920,   // Custom resolution width
  height: 1080,  // Custom resolution height
};

<BuildRender parts={highResBuild} size={500} />;
```

### `getAvailableParts()` 函数

从 BuildCores API 中获取所有可用的 PC 部件.

```tsx
function getAvailableParts(): Promise<AvailablePartsResponse>;
```

#### 返回类型

```tsx
interface PartDetails {
  id: string; // Unique part identifier
  name: string; // Human-readable part name
  image: string; // URL to part image
}

type AvailablePartsResponse = {
  [K in PartCategory]: PartDetails[];
};
```

#### 示例答复

```json
{
  "CPU": [
    {
      "id": "7xjqsomhr",
      "name": "AMD Ryzen 7 9800X3D",
      "image": "https://example.com/cpu1.jpg"
    },
    {
      "id": "x2thvstj3",
      "name": "AMD Ryzen 7 9700X",
      "image": "https://example.com/cpu2.jpg"
    }
  ],
  "GPU": [
    {
      "id": "z7pyphm9k",
      "name": "ASUS GeForce RTX 5080 ASTRAL",
      "image": "https://example.com/gpu1.jpg"
    },
    {
      "id": "4a0mjb360",
      "name": "PNY GeForce RTX 5060 Ti 16GB",
      "image": "https://example.com/gpu2.jpg"
    }
  ],
  "RAM": [
    {
      "id": "dpl1iyvb5",
      "name": "PNY DDR5",
      "image": "https://example.com/ram1.jpg"
    }
  ],
  "Motherboard": [
    {
      "id": "iwin2u9vx",
      "name": "Asus ROG STRIX X870E-E GAMING WIFI",
      "image": "https://example.com/mb1.jpg"
    }
  ],
  "PSU": [
    {
      "id": "m4kilv190",
      "name": "LIAN LI 1300W",
      "image": "https://example.com/psu1.jpg"
    }
  ],
  "Storage": [
    {
      "id": "0bkvs17po",
      "name": "SAMSUNG 990 EVO",
      "image": "https://example.com/storage1.jpg"
    }
  ],
  "PCCase": [
    {
      "id": "qq9jamk7c",
      "name": "MONTECH KING 95 PRO",
      "image": "https://example.com/case1.jpg"
    }
  ],
  "CPUCooler": [
    {
      "id": "62d8zelr5",
      "name": "ARCTIC LIQUID FREEZER 360",
      "image": "https://example.com/cooler1.jpg"
    }
  ]
}
```

#### 用法示例

```tsx
import { useState, useEffect } from "react";
import {
  BuildRender,
  getAvailableParts,
  type AvailablePartsResponse,
} from "@buildcores/render-client";

function PCBuildConfigurator() {
  const [availableParts, setAvailableParts] = useState<AvailablePartsResponse>(
    {} as AvailablePartsResponse
  );
  const [selectedParts, setSelectedParts] = useState<Record<string, string>>(
    {}
  );
  const [isLoading, setIsLoading] = useState(true);

  useEffect(() => {
    const fetchParts = async () => {
      try {
        const parts = await getAvailableParts();
        setAvailableParts(parts);

        // Set default selections (first part of each category)
        const defaults: Record<string, string> = {};
        Object.entries(parts).forEach(([category, partList]) => {
          if (partList.length > 0) {
            defaults[category] = partList[0].id;
          }
        });
        setSelectedParts(defaults);
      } catch (error) {
        console.error("Failed to fetch available parts:", error);
      } finally {
        setIsLoading(false);
      }
    };

    fetchParts();
  }, []);

  if (isLoading) return <div>Loading parts...</div>;

  // Build the parts object for BuildRender
  const buildParts = {
    parts: Object.fromEntries(
      Object.entries(selectedParts).map(([category, partId]) => [
        category,
        [partId], // Wrap in array as required
      ])
    ),
  };

  return (
    <div>
      <BuildRender parts={buildParts} size={500} />

      {/* Part selection UI */}
      {Object.entries(availableParts).map(([category, parts]) => (
        <div key={category}>
          <h3>{category}</h3>
          <select
            value={selectedParts[category] || ""}
            onChange={(e) =>
              setSelectedParts((prev) => ({
                ...prev,
                [category]: e.target.value,
              }))
            }
          >
            {parts.map((part) => (
              <option key={part.id} value={part.id}>
                {part.name}
              </option>
            ))}
          </select>
        </div>
      ))}
    </div>
  );
}
```

## \* 特性

-   **QQ 交互式控制**: 拖动鼠标或触摸来旋转 三维模型
-   **移动支持**: 优化移动设备触控
-   **实时渲染**: 基于部分选择的动态视频生成
-   **QQ 用户指导**: 显示用户可以交互的动画提示
-   **响应**: 适应您指定的任何大小
-   **QQ 类型脚本**: 包含全类型脚本支持

## QQ 配置

### 敏感性设置

微调不同用途的拖动灵敏度 :

```tsx
<BuildRender parts={parts} size={500} mouseSensitivity={0.003} />
<BuildRender parts={parts} size={500} mouseSensitivity={0.01} />
<BuildRender parts={parts} size={500} mouseSensitivity={0.02} />
```

### 大小配置

根据您的布局需要设置显示大小 :

```tsx
<BuildRender parts={parts} size={500} />
```

## 许可证

公务员制度委员会

**你必须有 自由到蓝色的API使用这个**

为了联系我们,访问: [www.buildingcores.com/api (中文(简体) )](https://www.buildcores.com/api)

## 捐款

欢迎提问和拉票请求! 请确保 TypeScript 类型得到适当维护 .

* * *

为PC大楼社区所建

## 常见问题

### @buildcores/render-client 是什么？

交互式360度视频渲染的反射组件

### 如何安装 @buildcores/render-client？

在项目目录运行 npm install @buildcores/render-client，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=16\.8\.0）、react-dom（\>=16\.8\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @buildcores/render-client 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @buildcores/render-client 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @buildcores/render-client 可以商用吗？

@buildcores/render-client 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @buildcores/render-client 的下载量有多少？

根据 npm 官方下载统计，@buildcores/render-client 在 2026/10/09 – 2026/11/07 这 30 天内被下载 4,559 次，日均约 152 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @buildcores/render-client 还在维护吗？

最新版本 1\.7\.1 发布于 2026/05/08（6 个月前）；至今共发布 22 个版本，其中过去 12 个月发布了 7 个；首次发布于 2025/08/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。