# FChordChartBuilder

> Language fallback: requested `zh-CN`; content is `en-US`.

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

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

- Requested language: `zh-CN`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

Fluent semantic builder for an undirected Source/Target/optional-Value edge list.

Final display labels own node identity. Duplicate and reverse rows aggregate,
omitted Value means unit-weight counts, and blank endpoints, self-links, and
non-positive/non-finite mapped weights are skipped without coercion. Aggregate
values are formatted after summing. Defaults are renderer-owned and require the
native ECharts 6.1 Chord series; no renderer nodes, links, or layout are persisted.

## Inheritance

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

## Example

Sheet

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const chartInfo = fWorksheet
  .newChart(univerAPI.Enum.ChartTypeString.Chord)
  .setSource('A1:C8')
  .setChordMapping({ sourceIndex: 0, targetIndex: 1, valueIndex: 2 })
  .setChordLayout({ startAngle: 90, clockwise: true, innerRadiusRatio: 0.4, outerRadiusRatio: 0.8 })
  .setChordNode({ color: '#2563eb', opacity: 0.8 })
  .setChordLabel({
    visible: true,
    position: univerAPI.Enum.ChartChordLabelPosition.Outside,
    color: '#334155',
  })
  .setChordRibbon({ color: univerAPI.Enum.ChartChordRibbonColorMode.Gradient, opacity: 0.6 })
  .setChordEmphasis({ focus: univerAPI.Enum.ChartChordFocusMode.Adjacency })
  .build()
await fWorksheet.insertChart(chartInfo)
```

Doc

```ts
const fDocument = univerAPI.getActiveDocument()
const chartInfo = fDocument
  .newChart(univerAPI.Enum.ChartTypeString.Chord)
  .setSource([
    ['Source', 'Target', 'Value'],
    ['A', 'B', 5],
    ['A', 'C', 3],
    ['B', 'C', 2],
  ])
  .setChordMapping({ sourceIndex: 0, targetIndex: 1, valueIndex: 2 })
  .setChordLayout({ startAngle: 90, clockwise: true, innerRadiusRatio: 0.4, outerRadiusRatio: 0.8 })
  .setChordNode({ color: '#2563eb', opacity: 0.8 })
  .setChordLabel({
    visible: true,
    position: univerAPI.Enum.ChartChordLabelPosition.Outside,
    color: '#334155',
  })
  .setChordRibbon({ color: univerAPI.Enum.ChartChordRibbonColorMode.Gradient, opacity: 0.6 })
  .setChordEmphasis({ focus: univerAPI.Enum.ChartChordFocusMode.Adjacency })
  .build()
await fDocument.insertChart(chartInfo)
```

Slide

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const chartInfo = fSlide
  .newChart(univerAPI.Enum.ChartTypeString.Chord)
  .setSource([
    ['Source', 'Target', 'Value'],
    ['A', 'B', 5],
    ['A', 'C', 3],
    ['B', 'C', 2],
  ])
  .setChordMapping({ sourceIndex: 0, targetIndex: 1, valueIndex: 2 })
  .setChordLayout({ startAngle: 90, clockwise: true, innerRadiusRatio: 0.4, outerRadiusRatio: 0.8 })
  .setChordNode({ color: '#2563eb', opacity: 0.8 })
  .setChordLabel({
    visible: true,
    position: univerAPI.Enum.ChartChordLabelPosition.Outside,
    color: '#334155',
  })
  .setChordRibbon({ color: univerAPI.Enum.ChartChordRibbonColorMode.Gradient, opacity: 0.6 })
  .setChordEmphasis({ focus: univerAPI.Enum.ChartChordFocusMode.Adjacency })
  .build()
await fSlide.insertChart(chartInfo)
```

Board

```ts
const fBoard = univerAPI.getActiveBoard()
const chartInfo = fBoard
  .newChart(univerAPI.Enum.ChartTypeString.Chord)
  .setSource([
    ['Source', 'Target', 'Value'],
    ['A', 'B', 5],
    ['A', 'C', 3],
    ['B', 'C', 2],
  ])
  .setChordMapping({ sourceIndex: 0, targetIndex: 1, valueIndex: 2 })
  .setChordLayout({ startAngle: 90, clockwise: true, innerRadiusRatio: 0.4, outerRadiusRatio: 0.8 })
  .setChordNode({ color: '#2563eb', opacity: 0.8 })
  .setChordLabel({
    visible: true,
    position: univerAPI.Enum.ChartChordLabelPosition.Outside,
    color: '#334155',
  })
  .setChordRibbon({ color: univerAPI.Enum.ChartChordRibbonColorMode.Gradient, opacity: 0.6 })
  .setChordEmphasis({ focus: univerAPI.Enum.ChartChordFocusMode.Adjacency })
  .build()
await fBoard.insertChart(chartInfo)
```

## Setup

Register [`@univerjs-pro/engine-chart`](https://docs.univer.ai/zh-CN/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/zh-CN/guides/sheets/getting-started/facade.md).

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

### `FChordChartBuilder.resetChordEmphasis`

Resets Chord emphasis behavior to renderer defaults.

```typescript
resetChordEmphasis(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetChordEmphasis()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/zh-CN/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-chord-chart-builder.d.ts)

### `FChordChartBuilder.resetChordLabel`

Resets Chord labels to renderer defaults.

```typescript
resetChordLabel(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetChordLabel()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/zh-CN/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-chord-chart-builder.d.ts)

### `FChordChartBuilder.resetChordLayout`

Resets the Chord layout to renderer defaults.

```typescript
resetChordLayout(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetChordLayout()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/zh-CN/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-chord-chart-builder.d.ts)

### `FChordChartBuilder.resetChordNode`

Resets Chord node styling to renderer defaults.

```typescript
resetChordNode(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetChordNode()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/zh-CN/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-chord-chart-builder.d.ts)

### `FChordChartBuilder.resetChordRibbon`

Resets Chord ribbon styling to renderer defaults.

```typescript
resetChordRibbon(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetChordRibbon()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/zh-CN/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-chord-chart-builder.d.ts)

### `FChordChartBuilder.setChordEmphasis`

Sets hover emphasis and focus behavior.

```typescript
setChordEmphasis(value: IChartChordEmphasisSpec): this
```

**Parameters**

* `value` — Required. Chord emphasis settings.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setChordEmphasis({ focus: univerAPI.Enum.ChartChordFocusMode.Adjacency })
```

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

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/zh-CN/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-chord-chart-builder.d.ts)

### `FChordChartBuilder.setChordLabel`

Sets Chord node-label visibility, position, and styling.

```typescript
setChordLabel(value: IChartChordLabelSpec): this
```

**Parameters**

* `value` — Required. Chord label settings.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setChordLabel({
  visible: true,
  position: univerAPI.Enum.ChartChordLabelPosition.Outside,
  color: '#334155',
})
```

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

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/zh-CN/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-chord-chart-builder.d.ts)

### `FChordChartBuilder.setChordLayout`

Sets the Chord radius, rotation, and spacing layout.

```typescript
setChordLayout(value: IChartChordLayoutSpec): this
```

**Parameters**

* `value` — Required. Chord layout settings.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setChordLayout({ startAngle: 90, clockwise: true })
```

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

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/zh-CN/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-chord-chart-builder.d.ts)

### `FChordChartBuilder.setChordMapping`

Sets the Source, Target, and optional Value field indexes for Chord edges.

```typescript
setChordMapping(value: IChartChordMappingSpec): this
```

**Parameters**

* `value` — Required. Zero-based field indexes for each edge component.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setChordMapping({ sourceIndex: 0, targetIndex: 1, valueIndex: 2 })
```

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

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/zh-CN/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-chord-chart-builder.d.ts)

### `FChordChartBuilder.setChordNode`

Sets Chart-wide Chord node styling.

```typescript
setChordNode(value: IChartChordNodeStyleSpec): this
```

**Parameters**

* `value` — Required. Chord node appearance settings.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setChordNode({ color: '#2563eb', opacity: 0.8 })
```

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

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/zh-CN/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-chord-chart-builder.d.ts)

### `FChordChartBuilder.setChordRibbon`

Sets Chord ribbon color, opacity, and border styling.

```typescript
setChordRibbon(value: IChartChordRibbonStyleSpec): this
```

**Parameters**

* `value` — Required. Chord ribbon appearance settings.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setChordRibbon({
  color: univerAPI.Enum.ChartChordRibbonColorMode.Gradient,
  opacity: 0.6,
})
```

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

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/zh-CN/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-chord-chart-builder.d.ts)