# generaltranslation: General Translation Core SDK: formatCutoff
URL: https://generaltranslation.com/zh/docs/core/class/methods/formatting/format-cutoff.mdx
---
title: formatCutoff
description: GT formatCutoff 方法的 API 参考文档
---

## 概述

`formatCutoff` 方法会使用适配区域设置的终止符来截短字符串，并根据目标区域设置应用合适的省略号字符和间距。

该方法对于需要遵循不同语言截断文本标注惯例的 UI 文本截短非常重要。

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

const formatted = gt.formatCutoff('Hello, world!', {
  maxChars: 8
});
// 返回："Hello, w\u202F…"（法语中带窄空格）
```

***


## 参考

### 参数

<TypeTable
  type={{
  "value": {
    type: 'string',
    optional: false,
  },
  "options?": {
    type: 'object',
    optional: true,
  }
}}
/>

### 选项对象

| Property     | Type                   | Optional | Description                   |
| ------------ | ---------------------- | -------- | ----------------------------- |
| `locales`    | `string \| string[]`   | ✓        | 用于选择终止符的区域设置 (会覆盖实例默认值)       |
| `maxChars`   | `number`               | ✓        | 显示的最大字符数。未定义表示不截断。负值表示从末尾开始截取 |
| `style`      | `'ellipsis' \| 'none'` | ✓        | 终止符样式。默认为 `'ellipsis'`        |
| `terminator` | `string`               | ✓        | 用于覆盖区域设置默认终止符的自定义终止符          |
| `separator`  | `string`               | ✓        | 终止符与文本之间的自定义分隔符               |

### CutoffFormatOptions 类型

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


### 返回值

`string` - 按区域设置惯例添加适当终止符后的截断字符串。

***

## 行为

### 区域设置解析

* 默认使用实例的 `_renderingLocales` (包括 `sourceLocale`、`targetLocale` 和回退区域设置) 
* 可通过显式指定 `locales` 选项来覆盖
* 如果解析失败，则回退到库的默认区域设置

### 字符限制处理

* **正数 `maxChars`**：保留开头部分，并在末尾追加终止符
* **负数 `maxChars`**：截取末尾部分，并在前面添加终止符
* **零 `maxChars`**：返回空字符串
* **未定义的 `maxChars`**：不进行截断，返回原始字符串

### 区域设置特定行为

该方法会根据语言自动选择合适的终止符：

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

***

## 示例

### 实例级区域设置的基本用法

```typescript
const gt = new GT({ targetLocale: 'en-US' });

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


### 覆盖区域设置

```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); // "…Framework"

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


### 自定义样式选项

```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')}`);
});
```

***


## 说明

* 该方法使用 GT 实例的 `_renderingLocales` 自动检测区域设置
* 终止符和分隔符的长度也会计入字符限制的计算中
* 如果终止符 + 分隔符的长度超过 `maxChars`，则返回空字符串
* 自定义终止符会完全覆盖区域设置特定的默认值
* 通过在内部缓存格式化器实例来优化性能

## 后续步骤

* 使用独立的 [`formatCutoff`](/docs/core/functions/formatting/format-cutoff)，无需 GT 实例
* 使用 [`formatMessage`](/docs/core/class/methods/formatting/format-message) 格式化消息
* 使用 [`formatNum`](/docs/core/class/methods/formatting/format-num) 格式化数字
* 了解[区域设置属性](/docs/core/class/methods/locales/get-locale-properties)