# FRelationChartBuilder

- Human documentation: [https://docs.univer.ai/reference/facade/relation-chart-builder](https://docs.univer.ai/reference/facade/relation-chart-builder)

- Agent Markdown: [https://docs.univer.ai/reference/facade/relation-chart-builder.md](https://docs.univer.ai/reference/facade/relation-chart-builder.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [facade/relation-chart-builder.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/relation-chart-builder.mdx)

---

Configures a relation chart.

## Inheritance

Extends [`FChartBuilderBase`](https://docs.univer.ai/reference/facade/chart-builder-base.md). Its inherited members are available on this object.

## Example

Sheet
A worksheet range `A1:C4` can contain this weighted edge list:

| Source | Target | Weight |
| ------ | ------ | -----: |
| A      | B      |      5 |
| A      | C      |      3 |
| C      | B      |      2 |

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const chartInfo = fWorksheet
  .newChart(univerAPI.Enum.ChartTypeString.Relation)
  .setSource({
    range: 'A1:C4',
    orientation: univerAPI.Enum.ChartSourceOrientation.Columns,
  })
  .setLayout(univerAPI.Enum.ChartRelationChartLayoutEnum.Force)
  .setUseValueAsSymbolSize(true)
  .setEmphasisEnabled(true)
  .setForce({ gravity: 0.2, repulsion: 50 })
  .setNodeShape(univerAPI.Enum.ChartLinePointShape.Circle)
  .build()
await fWorksheet.insertChart(chartInfo)
```

Doc

```ts
const fDocument = univerAPI.getActiveDocument()
const chartInfo = fDocument
  .newChart(univerAPI.Enum.ChartTypeString.Relation)
  .setSource([
    ['Source', 'Target', 'Weight'],
    ['A', 'B', 5],
    ['A', 'C', 3],
    ['C', 'B', 2],
  ])
  .setLayout(univerAPI.Enum.ChartRelationChartLayoutEnum.Force)
  .setUseValueAsSymbolSize(true)
  .setEmphasisEnabled(true)
  .setForce({ gravity: 0.2, repulsion: 50 })
  .setNodeShape(univerAPI.Enum.ChartLinePointShape.Circle)
  .build()
await fDocument.insertChart(chartInfo)
```

Slide

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const chartInfo = fSlide
  .newChart(univerAPI.Enum.ChartTypeString.Relation)
  .setSource([
    ['Source', 'Target', 'Weight'],
    ['A', 'B', 5],
    ['A', 'C', 3],
    ['C', 'B', 2],
  ])
  .setLayout(univerAPI.Enum.ChartRelationChartLayoutEnum.Force)
  .setUseValueAsSymbolSize(true)
  .setEmphasisEnabled(true)
  .setForce({ gravity: 0.2, repulsion: 50 })
  .setNodeShape(univerAPI.Enum.ChartLinePointShape.Circle)
  .build()
await fSlide.insertChart(chartInfo)
```

Board

```ts
const fBoard = univerAPI.getActiveBoard()
const chartInfo = fBoard
  .newChart(univerAPI.Enum.ChartTypeString.Relation)
  .setSource([
    ['Source', 'Target', 'Weight'],
    ['A', 'B', 5],
    ['A', 'C', 3],
    ['C', 'B', 2],
  ])
  .setLayout(univerAPI.Enum.ChartRelationChartLayoutEnum.Force)
  .setUseValueAsSymbolSize(true)
  .setEmphasisEnabled(true)
  .setForce({ gravity: 0.2, repulsion: 50 })
  .setNodeShape(univerAPI.Enum.ChartLinePointShape.Circle)
  .build()
await fBoard.insertChart(chartInfo)
```

## Setup

Register [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) or a preset that includes it. In plugin mode, import `@univerjs-pro/engine-chart/facade`. Additional methods below require their listed plugin packages. See [Facade setup](https://docs.univer.ai/guides/sheets/getting-started/facade.md).

## `@univerjs-pro/engine-chart`

### `FRelationChartBuilder.clearForce`

Clears the force configuration and returns this builder for chaining.

Force layout then uses gravity `0.1`, repulsion `5000`, and an edge length equal to one fifth
of the chart's shorter side.

This method executes synchronously.

```typescript
clearForce(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearForce()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-relation-chart-builder.d.ts)

### `FRelationChartBuilder.resetCircularLabelRotation`

Restores the default of keeping circular-layout labels unrotated and returns this builder for chaining.

This method executes synchronously.

```typescript
resetCircularLabelRotation(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetCircularLabelRotation()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-relation-chart-builder.d.ts)

### `FRelationChartBuilder.resetEmphasisEnabled`

Restores the default of emphasizing adjacent nodes and links on hover and returns this builder for chaining.

This method executes synchronously.

```typescript
resetEmphasisEnabled(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetEmphasisEnabled()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-relation-chart-builder.d.ts)

### `FRelationChartBuilder.resetLayout`

Restores the layout to `None`, which uses Univer's fixed relation layout, and returns this builder for chaining.

This method executes synchronously.

```typescript
resetLayout(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetLayout()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-relation-chart-builder.d.ts)

### `FRelationChartBuilder.resetNodeShape`

Removes the node-shape override so relation nodes use the renderer's circular symbol.

This method executes synchronously.

```typescript
resetNodeShape(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetNodeShape()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-relation-chart-builder.d.ts)

### `FRelationChartBuilder.resetUseValueAsSymbolSize`

Restores the default of scaling node symbols from their values and returns this builder for chaining.

This method executes synchronously.

```typescript
resetUseValueAsSymbolSize(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetUseValueAsSymbolSize()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-relation-chart-builder.d.ts)

### `FRelationChartBuilder.setCircularLabelRotation`

Sets the circular label rotation configuration and returns this builder for chaining.

This method executes synchronously.

```typescript
setCircularLabelRotation(value: boolean): this
```

**Parameters**

* `value` — Required. The semantic value to record.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setCircularLabelRotation(true)
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-relation-chart-builder.d.ts)

### `FRelationChartBuilder.setEmphasisEnabled`

Sets the emphasis enabled configuration and returns this builder for chaining.

This method executes synchronously.

```typescript
setEmphasisEnabled(value: boolean): this
```

**Parameters**

* `value` — Required. The semantic value to record.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setEmphasisEnabled(true)
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-relation-chart-builder.d.ts)

### `FRelationChartBuilder.setForce`

Sets the force configuration and returns this builder for chaining.

Omitted fields keep their current values. Without explicit overrides, force layout uses
gravity `0.1`, repulsion `5000`, and an edge length equal to one fifth of the chart's shorter side.

This method executes synchronously.

```typescript
setForce(value: IChartRelationForceSpec): this
```

**Parameters**

* `value` — Required. The semantic value to record.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setForce({ gravity: 0.2, repulsion: 50 })
```

**Types:** [`IChartRelationForceSpec`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/chart-builder/chart-types.d.ts)

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-relation-chart-builder.d.ts)

### `FRelationChartBuilder.setLayout`

Sets the layout configuration and returns this builder for chaining.

This method executes synchronously.

```typescript
setLayout(value: RelationChartLayoutEnum): this
```

**Parameters**

* `value` — Required. The semantic value to record.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setLayout(univerAPI.Enum.ChartRelationChartLayoutEnum.Force)
```

**Types:** [`RelationChartLayoutEnum`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/enum.d.ts)

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-relation-chart-builder.d.ts)

### `FRelationChartBuilder.setNodeShape`

Sets the node shape configuration and returns this builder for chaining.

This method executes synchronously.

```typescript
setNodeShape(value: LinePointShape): this
```

**Parameters**

* `value` — Required. The semantic value to record.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setNodeShape(univerAPI.Enum.ChartLinePointShape.Circle)
```

**Types:** [`LinePointShape`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/enum.d.ts)

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-relation-chart-builder.d.ts)

### `FRelationChartBuilder.setUseValueAsSymbolSize`

Sets the use value as symbol size configuration and returns this builder for chaining.

This method executes synchronously.

```typescript
setUseValueAsSymbolSize(value: boolean): this
```

**Parameters**

* `value` — Required. The semantic value to record.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setUseValueAsSymbolSize(true)
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-relation-chart-builder.d.ts)