# General Translation Platform: formatCutoff
URL: https://generaltranslation.com/zh/docs/platform/core/reference/utility-functions/formatting/format-cutoff.mdx
---

title: formatCutoff
description: 无需 GT 实例即可按区域设置感知的截断字符截断文本。formatCutoff 的 API 参考。

---

[`formatCutoff`](/docs/platform/core/reference/gt-class-methods/formatting/format-cutoff) 是 General Translation Core 库提供的独立实用函数，可使用区域设置感知的截断标记来截断字符串。它会遵循各语言在省略号字符和间距上的惯例。

## 概览 [#overview]

直接从 `generaltranslation` 导入 `formatCutoff`，然后传入一个字符串和一个选项对象进行调用。它不需要 API 密钥，也不需要 [GT](/docs/platform/core/reference/gt-class/constructor) 实例。若要使用基于实例的截断并继承实例的区域设置，请改用 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上的 [`formatCutoff`](/docs/platform/core/reference/gt-class-methods/formatting/format-cutoff) 方法。

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

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

签名：

```typescript
formatCutoff(
  value: string,
  options?: { locales?: string | string[] } & CutoffFormatOptions
): string
```

## 工作方式 [#how-it-works]

截断标记和分隔符都会计入 `maxChars`。也就是说，返回的字符串 (包括截断标记在内) 最多只有 `maxChars` 个字符。

### 字符限制

* **正数 `maxChars`：**从开头截断，并在末尾追加 截断标记。
* **负数 `maxChars`：**从末尾截取 (遵循 `Array.prototype.slice` 的行为) ，并在开头添加 截断标记。
* **零 `maxChars`：**返回空字符串。
* **未定义的 `maxChars`：**不进行截断。

### 区域设置特定的截断标记

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

* **法语：** `…`，并以窄不换行空格 (`\u202F`) 作为分隔符。
* **中文/日语：** 双省略号 `……`，不加分隔符。
* **默认：** 单省略号 `…`，不加分隔符。

### 边界情况

* 如果截断标记加上分隔符的长度超过 `maxChars`，结果将为空字符串。
* 短于 `maxChars` 的字符串会原样返回。
* `'none'` `style` 会直接截断，不添加任何截断标记。
* 省略 `locales` 时，会回退到该 library 的默认区域设置 `en`。

## 参数 [#parameters]

| 参数                    | 描述             | Type                                                     | 可选 | 默认值  |
| --------------------- | -------------- | -------------------------------------------------------- | -- | ---- |
| [`value`](#value)     | 要截断的字符串。       | `string`                                                 | 否  | —    |
| [`options`](#options) | 截断配置，包含目标区域设置。 | `{ locales?: string \| string[] } & CutoffFormatOptions` | 是  | `{}` |

### `value` [#value]

**类型** `string` · **必填**

要截断的字符串。

### `options` [#options]

**类型** `{ locales?: string | string[] } & CutoffFormatOptions` · **可选** · **默认值** `{}`

截断配置：

| 属性           | 描述                                       | 类型                     | 可选 | 默认值          |
| ------------ | ---------------------------------------- | ---------------------- | -- | ------------ |
| `locales`    | 用于选择截断标记的区域设置。                           | `string \| string[]`   | 是  | `en`         |
| `maxChars`   | 显示的最大字符数 (包括截断标记) 。未定义表示不截断；负值表示从末尾开始截取。 | `number`               | 是  | —            |
| `style`      | 截断标记的样式。                                 | `'ellipsis' \| 'none'` | 是  | `'ellipsis'` |
| `terminator` | 自定义截断标记，会覆盖区域设置的默认值。                     | `string`               | 是  | —            |
| `separator`  | 截断标记与文本之间的自定义分隔符。没有截断标记时将被忽略。            | `string`               | 是  | —            |

## 返回值 [#returns]

**类型** `string`

应用了适当截断标记后的字符串。

## 示例 [#examples]

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

// 基本截断（省略号计入 maxChars）
console.log(formatCutoff('Hello, world!', {
  locales: 'en-US',
  maxChars: 8,
}));
// 输出："Hello, …"

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

```typescript
// 负字符限制从末尾截取

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

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

```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: Record<string, number> = {
    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 very…"

console.log(truncateByLocale('Eine sehr lange deutsche Beschreibung mit vielen Wörtern', 'de'));
// 输出："Eine sehr lange deutsche Beschreibung mit vi…"
```

## 注意事项 [#notes]

* 与 GT 类方法不同，`locales` 是可选参数，默认值为 `en`。
* 为了在重复使用相同区域设置/选项组合时提升性能，结果会在内部缓存。
* 计算字符数上限时，会将截断标记 (以及分隔符) 的长度一并计入。
* 自定义截断标记会覆盖区域设置特定的默认值。
* 如果没有截断标记，分隔符会被忽略。