# FHistogramChartBuilder

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

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

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

- Requested language: `zh-CN`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

Fluent builder for a one-field raw-sample Histogram.

Select exactly one numeric field containing individual observations. The renderer
computes bins from those raw samples; do not pass pre-binned ranges or frequencies.

Histogram settings are persisted as authored. Rendering uses Scott Auto when explicit
binning is ineffective, never emits more than 1000 visible bins, and falls back to a
zero visual gap for ineffective gap values.

## Inheritance

Extends [`FCartesianChartBuilder`](https://docs.univer.ai/zh-CN/reference/facade/cartesian-chart-builder.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.Histogram)
  .setSource('A1:A100')
  .setHistogramField(0)
  .setBinCount(12)
  .setUnderflowThreshold(0)
  .setOverflowThreshold(100)
  .setBinGap(0.1)
  .build()
await fWorksheet.insertChart(chartInfo)
```

Doc

```ts
const fDocument = univerAPI.getActiveDocument()
const chartInfo = fDocument
  .newChart(univerAPI.Enum.ChartTypeString.Histogram)
  .setSource([['Duration'], [12], [18], [19], [25], [31], [35]])
  .setHistogramField(0)
  .setBinCount(12)
  .setUnderflowThreshold(0)
  .setOverflowThreshold(100)
  .setBinGap(0.1)
  .build()
await fDocument.insertChart(chartInfo)
```

Slide

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const chartInfo = fSlide
  .newChart(univerAPI.Enum.ChartTypeString.Histogram)
  .setSource([['Duration'], [12], [18], [19], [25], [31], [35]])
  .setHistogramField(0)
  .setBinCount(12)
  .setUnderflowThreshold(0)
  .setOverflowThreshold(100)
  .setBinGap(0.1)
  .build()
await fSlide.insertChart(chartInfo)
```

Board

```ts
const fBoard = univerAPI.getActiveBoard()
const chartInfo = fBoard
  .newChart(univerAPI.Enum.ChartTypeString.Histogram)
  .setSource([['Duration'], [12], [18], [19], [25], [31], [35]])
  .setHistogramField(0)
  .setBinCount(12)
  .setUnderflowThreshold(0)
  .setOverflowThreshold(100)
  .setBinGap(0.1)
  .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`

### `FHistogramChartBuilder.clearHistogramField`

Clears the active Histogram value field.

```typescript
clearHistogramField(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearHistogramField()
```

**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-histogram-chart-builder.d.ts)

### `FHistogramChartBuilder.clearOverflowThreshold`

Disables Overflow.

```typescript
clearOverflowThreshold(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearOverflowThreshold()
```

**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-histogram-chart-builder.d.ts)

### `FHistogramChartBuilder.clearUnderflowThreshold`

Disables Underflow.

```typescript
clearUnderflowThreshold(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearUnderflowThreshold()
```

**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-histogram-chart-builder.d.ts)

### `FHistogramChartBuilder.resetBinGap`

Removes the explicit gap and restores the 0.007 runtime default.

```typescript
resetBinGap(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetBinGap()
```

**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-histogram-chart-builder.d.ts)

### `FHistogramChartBuilder.resetBinning`

Removes explicit binning and restores runtime-only Scott Auto.

```typescript
resetBinning(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetBinning()
```

**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-histogram-chart-builder.d.ts)

### `FHistogramChartBuilder.setBinCount`

Stores an explicit total visible-bin count. Integers from 1 through 1000 are effective
when enabled edge bins still leave room for a regular bin. Other finite values remain
persisted and visible through `describe()` but render with Scott Auto. Non-finite calls
produce no Pending change.

```typescript
setBinCount(count: number): this
```

**Parameters**

* `count` — Required. Total visible-bin count.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setBinCount(20)
```

**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-histogram-chart-builder.d.ts)

### `FHistogramChartBuilder.setBinGap`

Stores the visual gap ratio. Values from 0 through 0.9 are effective; other finite values
remain persisted but render with the 0.007-gap default. Non-finite calls are no-op.

```typescript
setBinGap(value: number): this
```

**Parameters**

* `value` — Required. Gap ratio between adjacent bins.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setBinGap(0.15)
```

**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-histogram-chart-builder.d.ts)

### `FHistogramChartBuilder.setBinWidth`

Stores an explicit width. A positive finite width is effective only when the current
range produces at most 1000 visible bins; otherwise rendering uses Scott Auto without
rewriting the stored value. Non-finite calls produce no Pending change.

```typescript
setBinWidth(width: number): this
```

**Parameters**

* `width` — Required. Bin width in source-value units.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setBinWidth(2.5)
```

**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-histogram-chart-builder.d.ts)

### `FHistogramChartBuilder.setHistogramField`

Selects the only active Histogram value field by zero-based source index.

```typescript
setHistogramField(index: number): this
```

**Parameters**

* `index` — Required. Zero-based source field index.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setHistogramField(2)
```

**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-histogram-chart-builder.d.ts)

### `FHistogramChartBuilder.setOverflowThreshold`

Enables the exclusive `x > threshold` Overflow bin. An ineffective finite threshold
pair remains persisted but both thresholds are ignored for rendering. Non-finite calls are no-op.

```typescript
setOverflowThreshold(value: number): this
```

**Parameters**

* `value` — Required. Exclusive Overflow threshold.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setOverflowThreshold(100)
```

**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-histogram-chart-builder.d.ts)

### `FHistogramChartBuilder.setUnderflowThreshold`

Enables the inclusive `x <= threshold` Underflow bin. If both thresholds are present,
they are effective only when Underflow is less than Overflow. Non-finite calls are no-op.

```typescript
setUnderflowThreshold(value: number): this
```

**Parameters**

* `value` — Required. Inclusive Underflow threshold.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setUnderflowThreshold(0)
```

**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-histogram-chart-builder.d.ts)