# @cosmograph/react 中文文档

规范地址：https://npmcn.com/package/%40cosmograph/react/

版本：2\.5\.1
npm 元数据更新时间：2026-08-14T18:38:13.385Z
中文译文更新时间：2026-11-10T20:16:25.675Z
软件包许可：CC-BY-NC-4\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40cosmograph/react
原文对照：https://npmcn.com/package/%40cosmograph/react/?lang=original

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

- 包体积（解压后）：571 kB，80 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=16\.8\.0 \|\| ^17 \|\| ^18，react-dom \>=16\.8\.0 \|\| ^17 \|\| ^18
- 首次发布：2023-07-04T14:17:38.082Z
- 最新版本发布：2026-08-14T18:38:13.135Z
- 近 30 天下载量：58199（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：76（近 12 个月 21 个）

## 中文简介

宇宙图回放

## 安装

```sh
npm install @cosmograph/react
```

也可以使用：`pnpm add @cosmograph/react`、`yarn add @cosmograph/react`、`bun add @cosmograph/react`

## README

# 宇宙图反应

[![npm version](https://img.shields.io/npm/v/%40cosmograph%2Freact)](https://www.npmjs.com/package/@cosmograph/react/) [![license](https://img.shields.io/badge/license-CC--BY--NC--4.0-teal)](https://github.com/cosmograph-org/cosmograph/blob/main/LICENSE) [![GitHub Issues](https://img.shields.io/github/issues/cosmograph-org/cosmograph-issues?logo=github)](https://github.com/cosmograph-org/cosmograph-issues/issues) [![Discord](https://img.shields.io/discord/988484569789513728?logo=discord&logoColor=white&label=Discord&color=5765F2)](https://discord.gg/Rv8RUQuzsx) [![Docs](https://img.shields.io/badge/documentation%20%E2%86%97-8b5fbf)](https://cosmograph.app/docs-general/)

![](https://github.com/user-attachments/assets/799f0d56-4a99-4d6a-83db-c7589f6b342e)

用于整合的方便用户图书馆 [@ cosmograph/ cosmograph](https://www.npmjs.com/package/@cosmograph/cosmograph) 输入您的反应应用程序。 准备就绪的组件和提供者使交互式知识图探险者——大型实体——与搜索、传奇和跨过滤网的关系网络——与机器学习嵌入的语义图一起在 **二维或三维**,无需重新执行版式或WebGL.

## \* 特性

-   知识-图像友好:用搜索、选择、传说、直方图和规模的实体-关系工作量时间表来编写图表
-   2D和3D GPU 通过 `spaceDimensions`,带有3D的轨道相机和嵌入的可选 Z 坐标
-   宇宙图全能的简单回放组件 API
-   准备使用的互动组件:时光线、直方图、巴斯、传奇、搜索甚至更多
-   访问 Cosmograph 实例和编写原始数据的反应钩
-   完整类型脚本支持
-   共享宇宙图状态的背景提供者

## QQ 快速启动

安装软件包 :

```bash
npm install @cosmograph/react
```

获取数据,配置图表并渲染宇宙图 :

```typescript
import React, { useEffect, useState } from 'react'
import { Cosmograph, CosmographConfig, prepareCosmographData } from '@cosmograph/react'

// Points and links data can be:
// - Array of objects
// - File (.csv/.tsv, .parquet/.pq, .arrow, .json)
// - URL string to a file
// - Apache Arrow Table (binary data Uint8Array/ArrayBuffer)
// - DuckDB table name if connection is passed into the Cosmograph constructor

const rawPoints = [{ id: 'a' }, { id: 'b' }, { id: 'c' }]

const rawLinks = [
  { source: 'a', target: 'b' },
  { source: 'b', target: 'c' },
  { source: 'c', target: 'a' },
]

export const component = (): JSX.Element => {
  const [config, setConfig] = useState<CosmographConfig>({})

  // Create a config to map your data into Cosmograph's internal format
  const dataConfig = {
    points: {
      pointIdBy: 'id',
    },
    links: {
      linkSourceBy: 'source',
      linkTargetsBy: ['target'],
    },
  }

  const loadData = async (): Promise<void> => {
    // Prepare data and config for Cosmograph
    const result = await prepareCosmographData(dataConfig, rawPoints, rawLinks)

    if (result) {
      // Update Cosmograph config with prepared output
      const { points, links, cosmographConfig } = result
      setConfig({ points, links, ...cosmographConfig })
    }
  }

  // Load data when component is mounted
  useEffect(() => { loadData() }, [])

  return <Cosmograph {...config} />
}
```

### `CosmographProvider`

`CosmographProvider` 连接 `Cosmograph` 实例, 附带组件 `CosmographTimeline` 财务报告和审定财务报表 `CosmographHistogram`。将您的组件围起来,以便实现此连接:

```javascript
import { CosmographProvider, CosmographHistogram, Cosmograph } from '@cosmograph/react'

function App() {
  ...
  return (
    <CosmographProvider>
      <Cosmograph {...config} />
      // Assuming you have a numeric column "value" in your points data
      <CosmographHistogram accessor={"value"}>
    </CosmographProvider>
  )
}
```

> **_注释:_** 总是在内部放置宇宙图伴构件 `CosmographProvider` 并确保它已经 `Cosmograph` 里面的情况.

### `useCosmograph`

环绕您的应用程序后 `CosmographProvider`,则 `useCosmograph` 钩子现在可以用来访问 `Cosmograph` 举个例子.

```javascript
import { useCosmograph, CosmographProvider } from '@cosmograph/react'

const FitButton = () => {
  const { cosmograph } = useCosmograph()
  
  return (
    <button onClick={() => cosmograph.fitView()}>
      Fit View
    </button>
  )
}

const App = () => {
  ...
  return (
    <CosmographProvider>
      <Cosmograph {...config}/>
      <FitButton />
    </CosmographProvider>
  )
}
```

> **_注释:_** `useCosmograph` 必须召见于作为人类直接后裔的组成部分 `CosmographProvider`。试图在提供者之外使用它会引发错误.

### 参考文献

`Cosmograph` 暴露一个 `ref` 属性,可用于访问基础 `Cosmograph` 例如,允许您直接接触其方法和属性.

```javascript
import React, { useRef } from 'react'
import { CosmographRef, Cosmograph } from '@cosmograph/react'

function App () {
  ...
  const cosmograph = useRef<CosmographRef>()

  const onClick = (pointIndex: number | undefined) => {
    cosmograph.current?.selectPoint(point)
  }}

  return (
    <Cosmograph {...config} onClick={onClick} ref={cosmograph}/>
  )
}
```

## 可用组件

`@cosmograph/react` 提供与宇宙图实例相连接并可供使用的一组组件:

-   [`Cosmograph`](https://cosmograph.app/docs-lib/api/classes/Cosmograph/): 主要组成部分.
-   [`CosmographTimeline`](https://cosmograph.app/docs-lib/api/classes/CosmographTimeline/): 提供一段时间可视化数据的时间表功能.
-   [`CosmographHistogram`](https://cosmograph.app/docs-lib/api/classes/CosmographHistogram/): 一个完全自定义的直方图组件.
-   [`CosmographBars`](https://cosmograph.app/docs-lib/api/classes/CosmographBars/):一个带有绝对条的可视化数据的组件,可以搜索、排序和过滤这些类别.
-   [`CosmographSizeLegend`](https://cosmograph.app/docs-lib/api/classes/CosmographSizeLegend/):用于可视化数据大小的传说组件.
-   [`CosmographTypeColorLegend`](https://cosmograph.app/docs-lib/api/classes/CosmographTypeColorLegend/): 用于可视化有颜色的数据类型的传说组件.
-   [`CosmographRangeColorLegend`](https://cosmograph.app/docs-lib/api/classes/CosmographRangeColorLegend/): 以颜色可视化数字数据的组件.
-   [`CosmographSearch`](https://cosmograph.app/docs-lib/api/classes/CosmographSearch/): 以集成的图上选择功能, 强大的搜索您的宇宙图数据 .
-   [`CosmographPopup`](https://cosmograph.app/docs-lib/api/classes/CosmographPopup/):用于显示自定义的 HTML 弹出器的组件,可以被固定在图表上的特定节点或坐标上.
-   手巧的组合 **按钮** 用于常见的图形交互:
    -   [`CosmographButton`](https://cosmograph.app/docs-lib/api/classes/CosmographButton/): 自定义动作的基础按钮组件.
    -   [`CosmographButtonFitView`](https://cosmograph.app/docs-lib/api/classes/CosmographButtonFitView/):自动调整图的缩放和位置,以适应取景口内的所有节点.
    -   [`CosmographButtonPlayPause`](https://cosmograph.app/docs-lib/api/classes/CosmographButtonPlayPause/):切换由力向布局模拟.
    -   [`CosmographButtonZoomInOut`](https://cosmograph.app/docs-lib/api/classes/CosmographButtonZoomInOut/):提供用于缩放的按钮.
    -   [`CosmographButtonRectangularSelection`](https://cosmograph.app/docs-lib/api/classes/CosmographButtonRectangularSelection/):允许用户通过绘制矩形来选择节点.
    -   [`CosmographButtonPolygonalSelection`](https://cosmograph.app/docs-lib/api/classes/CosmographButtonPolygonalSelection/):允许用户通过绘制自定义多边形来选择节点.

> **_注释:_** 所有组件包括支持参考,可通过下列途径访问: `useRef` 或者说 `useCallback` 用于开发者拥有更好的控制和管理. 请检查access-date=中的日期值 (帮助) Cosmograph React Docs了解更多细节.

## 问题和贡献

虽然目前已关闭来源,我们欢迎您的反馈! 帮助改进宇宙图,方法是提交错误报告,并在我们中突出想法 [问题存放处](https://github.com/cosmograph-org/cosmograph-issues)。 。 。 .

## 许可证

宇宙图根据 [CC-BY-NC-4.0. 许可证](https://creativecommons.org/licenses/by-nc/4.0/deed.en) 任何非商业用途都可以免费使用。 如果你想在商业项目中使用,请 [联系我们](mailto:licensing@cosmograph.app)。 。 。 .

## 宇宙空间

[@ cosmograph/ cosmograph](http://www.npmjs.com/package/@cosmograph/react) - JavaScript 和 TypeScript 的宇宙图库  
[py 相册](https://github.com/cosmograph-org/py_cosmograph) - Python 数据科学工作流程的 Jupyter 部件

## 联系人

🌎 [相册. app](https://cosmograph.app/)  
📩 [嗨@cosmograph.app](mailto:hi@cosmograph.app)  
👾 [宇宙图 Discord 频道](https://discord.gg/Rv8RUQuzsx)

## 常见问题

### @cosmograph/react 是什么？

宇宙图回放

### 如何安装 @cosmograph/react？

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

### @cosmograph/react 支持 TypeScript 吗？

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

### @cosmograph/react 支持 ESM 还是 CommonJS？

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

### @cosmograph/react 可以商用吗？

@cosmograph/react 使用 CC-BY-NC-4\.0 许可。声明的许可为 CC-BY-NC-4\.0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @cosmograph/react 的下载量有多少？

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

### @cosmograph/react 还在维护吗？

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