# vue: useGT
URL: https://generaltranslation.com/zh/docs/vue/reference/composables/use-gt.mdx
---

title: useGT
description: 获取用于内联翻译字符串的函数。useGT 的 API 参考。

---

`useGT` 组合式函数会返回一个同步的纯字符串目录查找函数。可在 Vue 组件中将其用于标签、占位符和其他独立字符串。

## 概述 [#overview]

在组件 setup 阶段调用 `useGT`，然后在模板或其他响应式副作用中调用其返回的函数：

```vue
<script setup lang="ts">
import { useGT } from 'gt-vue';

const gt = useGT();
</script>

<template>
  <input :placeholder="gt('Search products')" />
</template>
```

当文本和嵌套标记应构成一条富文本翻译时，请改用 [`<T>`](/docs/vue/reference/components/t)。对于仅限在浏览器中运行的 SPA 中的模块级字符串，请使用 [`t()`](/docs/vue/reference/functions/t)。

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

* **同步查找。** 返回的函数会对源字符串和可选上下文计算哈希值，然后读取当前插件已加载的目录。
* **源文本后备。** 如果条目缺失，或条目的目录结构不正确，则返回原始字符串。
* **仅支持普通字符串。** 花括号会保持原义。该函数不支持 ICU 语法、插值变量、`$id`、`$maxChars` 或 `$format`。
* **插件层级。** 请在 [`createGT()`](/docs/vue/reference/functions/create-gt) 或 [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) 返回的插件下的组件中调用该组合式函数。未安装插件时调用会抛出错误。请求级 [`createGT()`](/docs/vue/reference/functions/create-gt) 插件也支持服务器端渲染的组件。

提取器要求字符串必须可静态分析，例如字符串字面量、不含表达式的模板字面量，或可解析为上述任一形式的不可变标识符。上下文也必须是静态的，以确保生成的目录与运行时哈希值一致。

## 参数 [#parameters]

`useGT` 不接受任何参数。

## 返回值 [#returns]

**类型** `(message: string, options?: GTStringOptions) => string`

一个接受以下参数的同步函数：

| 参数                    | 描述              | 类型                                                               | 可选 | 默认值  |
| --------------------- | --------------- | ---------------------------------------------------------------- | -- | ---- |
| [`message`](#message) | 要翻译的静态源字符串。     | `string`                                                         | 否  | —    |
| [`options`](#options) | 用于消除源字符串歧义的上下文。 | [`GTStringOptions`](/docs/vue/reference/types/gt-string-options) | 是  | `{}` |

### `message`

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

由提取器注册、在运行时查找的静态源字符串。

### `options`

**类型** [`GTStringOptions`](/docs/vue/reference/types/gt-string-options) · **可选** · **默认值** `{}`

唯一支持的字段是 `$context?: string`。它会改变目录标识，使相同的源字符串可具有不同的翻译。

```vue
<button>{{ gt('Open', { $context: 'Verb: open the settings panel' }) }}</button>
```

## 响应性 [#reactivity]

调用返回的函数时，它会读取响应式的 目录 和区域设置状态。模板表达式会自动重新执行：

```vue
<p>{{ gt('Hello World') }}</p>
```

对于在 setup 中创建的值，请将调用包裹在 `computed` 中：

```ts
import { computed } from 'vue';

const gt = useGT();
const message = computed(() => gt('Hello World'));
```

调用一次即可创建普通字符串翻译快照：

```ts
const gt = useGT();
const message = gt('Hello World');
```

使用 [`createGT()`](/docs/vue/reference/functions/create-gt) 插件时，初始 目录 加载完成或区域设置变更后，该翻译快照不会更新。使用 [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) 初始化的浏览器 SPA 会在组件运行前预加载，并在区域设置变更时重新加载页面，因此会使用已加载的区域设置重新创建设置阶段的翻译快照。

## 示例 [#example]

```vue title="SearchForm.vue"
<script setup lang="ts">
import { computed } from 'vue';
import { useGT } from 'gt-vue';

const gt = useGT();
const emptyMessage = computed(() =>
  gt('No results', { $context: 'Empty search results' })
);
</script>

<template>
  <form>
    <input :placeholder="gt('Search products')" />
    <p>{{ emptyMessage }}</p>
  </form>
</template>
```