# generaltranslation: General Translation Core SDK: formatCutoff
URL: https://generaltranslation.com/zh/docs/core/functions/formatting/format-cutoff.mdx
---
title: formatCutoff
description: 使用区域设置感知的终止符截断字符串的独立函数
---

## 概述

独立运行的 `formatCutoff` 函数无需 GT 实例，即可使用符合特定区域设置的截断结尾符来截断字符串。
它提供具备区域设置感知能力的文本截断，并遵循不同语言在省略号及空格用法上的惯例。

```typescript
import { formatCutoff } from 'generaltranslation';

const formatted = formatCutoff('Hello, world!', {
  locales: 'en-US',
  maxChars: 8
});
// 返回: "Hello, w…"
```


## 参考

### 参数

| 名称        | 类型                                                       | 描述      |
| --------- | -------------------------------------------------------- | ------- |
| `value`   | `string`                                                 | 要截断的字符串 |
| `options` | `CutoffFormatOptions & { locales?: string \| string[] }` | 截断配置    |

### CutoffFormatOptions

| 名称            | 类型                     | 描述                          |
| ------------- | ---------------------- | --------------------------- |
| `locales?`    | `string \| string[]`   | 用于选择截断终止符的区域设置              |
| `maxChars?`   | `number`               | 最多显示的字符数。未定义表示不截断。负值表示从末尾截取 |
| `style?`      | `'ellipsis' \| 'none'` | 终止符样式。默认为 `'ellipsis'`      |
| `terminator?` | `string`               | 用于覆盖区域设置默认终止符的自定义终止符        |
| `separator?`  | `string`               | 终止符与文本之间的自定义分隔符             |

### 返回值

`string` - 截断后的字符串，并附加适当的终止符。

***

## 行为

### 字符限制

* **正数 `maxChars`**：从开头截取，并在末尾追加终止符
* **负数 `maxChars`**：从末尾截取，并在开头添加终止符
* **零 `maxChars`**：返回空字符串
* **未定义 `maxChars`**：不进行截断

### 区域设置特定的终止符

不同区域设置的省略号用法不同：

* **法语**：`…`，前面带窄不换行空格 (`\u202F`) 
* **中文/日文**：双省略号 `……`，中间不加分隔符
* **默认**：单省略号 `…`，不加分隔符

### 边界情况

* 如果终止符和分隔符的总长度超过 `maxChars`，则返回空字符串
* 原始字符串短于 `maxChars` 时，保持不变
* `'none'` 样式会直接截断，不添加任何终止符

***

## 示例

### 基本用法

```typescript
import { formatCutoff } from 'generaltranslation';

// 基本截断
console.log(formatCutoff('Hello, world!', {
  locales: 'en-US',
  maxChars: 8
}));
// 输出："Hello, w…"

// 无需截断
console.log(formatCutoff('Short', {
  locales: 'en-US', 
  maxChars: 10
}));
// 输出："Short"
```


### 负数字符限制

```typescript
// 从末尾截取
console.log(formatCutoff('Hello, world!', {
  locales: 'en-US',
  maxChars: -3
}));
// 输出: "…ld!"

// 更大的负数截取
console.log(formatCutoff('JavaScript', {
  locales: 'en-US',
  maxChars: -6
}));
// 输出: "…Script"
```


### 区域设置特定的终止符

```typescript
// 法语格式化
console.log(formatCutoff('Bonjour le monde', {
  locales: 'fr-FR',
  maxChars: 10
}));
// 输出："Bonjour\u202F…"（省略号前的窄空格）

// 中文格式化
console.log(formatCutoff('你好世界', {
  locales: 'zh-CN',
  maxChars: 3
}));
// 输出："你好……"

// 日语格式化  
console.log(formatCutoff('こんにちは', {
  locales: 'ja-JP',
  maxChars: 4
}));
// 输出："こん……"
```

### 自定义终止符

```typescript
// 自定义终止符
console.log(formatCutoff('Long text here', {
  locales: 'en-US',
  maxChars: 10,
  terminator: '...'
}));
// 输出："Long te..."

// 带分隔符的自定义终止符
console.log(formatCutoff('Another example', {
  locales: 'en-US',
  maxChars: 12,
  terminator: '[more]',
  separator: ' '
}));
// 输出："Anoth [more]"

// 无终止符
console.log(formatCutoff('Clean cut', {
  locales: 'en-US',
  maxChars: 5,
  style: 'none'
}));
// 输出："Clean"
```


### 工具函数

```typescript
import { formatCutoff } from 'generaltranslation';

// 截断以用于 UI 显示
function displayText(text: string, maxLength: number, locale = 'en-US') {
  return formatCutoff(text, {
    locales: locale,
    maxChars: maxLength
  });
}

// 多区域设置截断
function truncateByLocale(text: string, locale: string) {
  const limits = {
    'en': 50,
    'de': 45, // 德语单词往往较长
    'zh': 30, // 中文字符密度更高
  };
  
  return formatCutoff(text, {
    locales: locale,
    maxChars: limits[locale] || 50
  });
}

console.log(displayText('This is a very long description', 15));
// 输出："This is a ve…"

console.log(truncateByLocale('Eine sehr lange deutsche Beschreibung', 'de'));
// 输出："Eine sehr lange deutsche Besch…"
```

***


## 说明

* 与 GT 类方法不同，`locales` 参数是可选的，默认值为 `'en'`
* 为提升重复使用相同区域设置/选项组合时的性能，结果会在内部缓存
* 终止符长度会计入字符限制的计算
* 自定义终止符会覆盖特定区域设置的默认值
* 如果没有终止符，则会忽略分隔符

## 后续步骤

* 如需基于实例使用，请使用 GT 类的 [`formatCutoff`](/docs/core/class/methods/formatting/format-cutoff)
* 查看其他格式化函数，例如 [`formatMessage`](/docs/core/functions/formatting/format-message)
* 数字格式化请参见 [`formatNum`](/docs/core/functions/formatting/format-num)