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

title: formatCutoff
description: 使用符合区域设置的截断字符和终止标记截断文本。formatCutoff 的 API 参考。

---

在 [GT](/docs/platform/core/reference/gt-class/constructor) 实例上，使用符合区域设置的终止标记截断 string，并根据目标区域设置应用合适的省略号字符和间距。General Translation 使用此功能截断 UI 文本，以遵循不同语言对文本截断的表示惯例。

## 概览 [#overview]

在 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上调用 `formatCutoff`，传入要截断的字符串，以及通过 `maxChars` 指定的选项对象。它会返回应用了截断标记的截断字符串。

```typescript
const gt = new GT({ sourceLocale: 'en', targetLocale: 'fr-FR' });

const formatted = gt.formatCutoff('Hello, world!', {
  maxChars: 8,
});
// "Hello,\u202F…"（法语中省略号前的窄不换行空格）
```

签名：

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

*注意：`formatCutoff` 在本地运行，无需 API 密钥。默认情况下，它会使用实例的目标区域设置；如果不可用，则依次回退到源区域设置和库默认值 (`en`) 。传入 `locales` 可覆盖此设置。若要在没有 `GT` 实例的情况下进行格式化，请参阅独立使用的 [`formatCutoff`](/docs/platform/core/reference/utility-functions/formatting/format-cutoff)。*

*注意：截断标记和分隔符都会计入 `maxChars`。下方示例输出反映了当前库的行为，并修正了源文档中若干未将截断标记计入字符数的示例 (例如，`maxChars: 8` 的结果是 `"Hello, …"`，而不是 `"Hello, w…"`) 。*

## 工作原理 [#how-it-works]

### 区域设置解析

* 默认使用该实例的目标区域设置；如果不可用，则依次回退到源区域设置，再回退到库的默认值 (`en`) 。
* 也可以通过显式指定 `locales` 选项来覆盖。

### 字符数限制处理

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

### 区域设置相关行为

该方法会根据语言自动选择合适的截断标记：

* **French (`fr`)：** `…`，并带有一个窄不换行空格 (`\u202F`) 。
* **Chinese (`zh`)：** 双省略号 `……`，不带分隔符。
* **Japanese (`ja`)：** 双省略号 `……`，不带分隔符。
* **默认：** 单省略号 `…`，不带分隔符。

## 参数 [#parameters]

| 参数                    | 描述       | 类型       | 可选 | 默认值 |
| --------------------- | -------- | -------- | -- | --- |
| [`value`](#value)     | 要截断的字符串。 | `string` | 否  | —   |
| [`options`](#options) | 截断配置。    | `object` | 是  | —   |

### `value` [#value]

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

要截短的字符串。

### `options` [#options]

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

截断配置：

| 名称           | 描述                                                | 类型                     | 可选 | 默认值          |
| ------------ | ------------------------------------------------- | ---------------------- | -- | ------------ |
| `locales`    | 用于选择截断标记的区域设置 (覆盖实例默认值) 。                         | `string \| string[]`   | 是  | 实例渲染区域设置     |
| `maxChars`   | 要显示的最大字符数。`undefined` 表示不截断；负值表示从末尾截取；`0` 返回空字符串。 | `number`               | 是  | —            |
| `style`      | 截断标记样式。                                           | `'ellipsis' \| 'none'` | 是  | `'ellipsis'` |
| `terminator` | 用于覆盖区域设置默认值的自定义截断标记。                              | `string`               | 是  | —            |
| `separator`  | 截断标记与文本之间的自定义分隔符。如果未提供截断标记，则会忽略。                  | `string`               | 是  | —            |

`CutoffFormatOptions` 类型：

```typescript
interface CutoffFormatOptions {
  maxChars?: number;
  style?: 'ellipsis' | 'none';
  terminator?: string;
  separator?: string;
}
```

## 返回值 [#returns]

**类型** `string`

根据区域设置的惯例应用了适当截断标记的字符串。

## 示例 [#examples]

```typescript
// 使用实例区域设置的基本用法
const gt = new GT({ targetLocale: 'en-US' });

const truncated = gt.formatCutoff('Hello, world!', {
  maxChars: 8,
});
console.log(truncated); // "Hello, …"
```

```typescript
// 区域设置覆盖
const gt = new GT({ targetLocale: 'en-US' });

const french = gt.formatCutoff('Bonjour le monde', {
  locales: 'fr-FR',
  maxChars: 10,
});
console.log(french); // "Bonjour \u202F…"
```

```typescript
// 负字符限制
const gt = new GT({ targetLocale: 'en-US' });

// 从末尾截取
const fromEnd = gt.formatCutoff('JavaScript Framework', {
  maxChars: -9,
});
console.log(fromEnd); // "…ramework"

// 更大的负数截取
const moreFromEnd = gt.formatCutoff('Hello, world!', {
  maxChars: -3,
});
console.log(moreFromEnd); // "…d!"
```

```typescript
// 自定义样式选项
const gt = new GT({ targetLocale: 'en-US' });

// 自定义截断标记
const custom = gt.formatCutoff('Long description text', {
  maxChars: 12,
  terminator: '...',
});
console.log(custom); // "Long desc..."

// 带分隔符的自定义截断标记
const customSep = gt.formatCutoff('Another example', {
  maxChars: 10,
  terminator: '[...]',
  separator: ' ',
});
console.log(customSep); // "Anot [...]"

// 无截断标记
const none = gt.formatCutoff('Clean cut text', {
  maxChars: 5,
  style: 'none',
});
console.log(none); // "Clean"
```

```typescript
// 多语言应用
class UserInterface {
  private gt: GT;

  constructor(locale: string) {
    this.gt = new GT({ targetLocale: locale });
  }

  truncateTitle(title: string, maxLength = 20): string {
    return this.gt.formatCutoff(title, { maxChars: maxLength });
  }

  truncateDescription(description: string): string {
    return this.gt.formatCutoff(description, { maxChars: 100 });
  }
}

const englishUI = new UserInterface('en-US');
const chineseUI = new UserInterface('zh-CN');

console.log(englishUI.truncateTitle('Very Long English Title Here', 15));
// 输出："Very Long Engl…"

console.log(chineseUI.truncateTitle('很长的中文标题在这里', 8));
// 输出："很长的中文标……"
```

```typescript
// 动态区域设置处理
const gt = new GT({ sourceLocale: 'en', targetLocale: 'en' });

function adaptiveText(text: string, userLocale: string, context: 'title' | 'body') {
  const limits = {
    title: { en: 50, fr: 45, de: 40, zh: 25 },
    body: { en: 200, fr: 180, de: 160, zh: 100 },
  };

  const maxChars = limits[context][userLocale] || limits[context]['en'];

  return gt.formatCutoff(text, {
    locales: userLocale,
    maxChars,
  });
}

const userPrefs = [
  { locale: 'fr-FR', text: 'Une très longue description française' },
  { locale: 'zh-CN', text: '这是一个非常长的中文描述文本' },
  { locale: 'de-DE', text: 'Eine sehr lange deutsche Beschreibung' },
];

userPrefs.forEach(({ locale, text }) => {
  console.log(`${locale}: ${adaptiveText(text, locale, 'title')}`);
});
```

## 注意事项 [#notes]

* 该方法会使用 GT 实例的目标区域设置进行自动区域设置检测，并依次回退到源区域设置以及库的默认值 (`en`) 。
* 计算字符数限制时，会将 截断标记 和 分隔符 的长度一并计入。
* 如果 截断标记 与 分隔符 的总长度超过 `maxChars`，该方法将返回空字符串。
* 自定义 截断标记 会完全覆盖区域设置特定的默认值。
* 通过在内部缓存 formatter 实例来提升性能。