---
name: "useTopBarTitle"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "useTopBarTitle - 设置小程序顶部标题"
summary: "设置小程序顶部标题的 Hook，支持初始标题和动态更新。"
questions:
  - "useTopBarTitle 如何设置小程序顶部标题？"
  - "useTopBarTitle 的 title 参数是什么类型？"
  - "useTopBarTitle 返回的 updateTitle 函数如何动态更新标题？"
  - "如何在按钮点击事件中通过 updateTitle 切换顶部标题？"
  - "useTopBarTitle 传入的初始标题会在什么时机生效？"
  - "如何从 @ray-js/panel-sdk 导入 useTopBarTitle？"
  - "useTopBarTitle 返回值的数组结构中包含哪些元素？"
  - "多次调用 updateTitle 是否会立即更新顶部标题显示？"
  - "useTopBarTitle 在不同页面中使用时标题是否独立管理？"
  - "useTopBarTitle 适合在面板小程序的哪些场景下使用？"
---

## useTopBarTitle

> [VERSION] @ray-js/panel-sdk >= 1.0.0

> 💡 该 Hook 会在 title 变化时自动更新导航栏标题。
> 底层依赖 @ray-js/ray 提供的 setNavigationBarTitle API 设置小程序导航栏标题。
> 若标题长度超过 ellipsis 指定的字符数，将自动截断并添加 ... 后缀。

### 描述

设置小程序顶部导航栏标题，支持超长文本自动截断

### 参数

`Params`

| 参数 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| `title` | `string` | 是 | 要设置的标题文本 |
| `ellipsis` | `number` | 否 | 标题最大字符数，超出后自动添加省略号，默认为 14 |

### 返回值

类型: `(titleRes: string) => void[]`

元组 [setTitle]，包含一个可手动设置标题的函数

### 示例代码

#### 示例

```tsx
import { useTopBarTitle } from '@ray-js/panel-sdk';

function DevicePage() {
  // 自动设置顶部标题，超过 14 个字符会截断
  const [setTitle] = useTopBarTitle('智能灯光控制面板');

  // 也可以手动更新标题
  const handleRename = (newName: string) => setTitle(newName);
}
```