> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/common/navigationbar.md).

# 导航栏设置

导航栏是固定在屏幕顶部的通用 UI 组件。应用 Toss SDK 后，导航栏会自动显示，无需单独实现。

{% hint style="info" %}
**请参考**

请参考 Mini App Logo 设置的 WebView 设置或 React Native 设置文档。
{% endhint %}

***

### 1. 导航栏基本功能

#### 游戏

游戏导航栏由 **更多按钮**和 **关闭(X)按钮**组成。 `granite.config.ts`在中将应用类型 `game`设置为即可使用游戏导航栏。

{% tabs %}
{% tab title="WebView" %}

```typescript
import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  // ...
  webViewProps: {
    type: 'game',
  },
});
```

{% endtab %}

{% tab title="React Native" %}

```typescript
import { appsInToss } from '@apps-in-toss/framework/plugins';
import { defineConfig } from '@granite-js/react-native/config';

export default defineConfig({
  // ...
  plugins: [
    appsInToss({
      // ...
      appType: 'game',
    }),
  ],
});
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**请参考**

* [safeArea](/documentation/api-and-sdk-zh/common/screen/safe-area.md) 请参考文档开发，确保 X 按钮不会与游戏画面中的其他按钮重叠。
  {% endhint %}

#### 非游戏

在非游戏 Mini App 中，默认提供白色背景的导航栏。左侧是 **Mini App Logo**和 **名称**，右侧是 **更多按钮**和 **X 按钮**。

#### 更多按钮功能

通过更多按钮，无需单独的服务器联动或额外实现，就能直接使用以下功能。

**联系客服 / 举报**

在控制台注册的 **客服链接和官网地址**会自动显示。通过举报功能，用户可以发送举报内容，合作方可以通过控制台查看举报内容。

**分享**

用户可以轻松将 Mini App 分享给他人。分享时 **Mini App 名称**和 **深度链接地址**会一并发送。

**权限设置**

用户可以查看 Mini App 请求的权限，并随时通过 ON/OFF 进行控制。

**添加到主屏幕**

常用的 Mini App 可以直接添加到手机主屏幕。从 Toss App 5.246.0 以上版本起可确认。

**删除 Mini App 容量**

可以有选择地删除不常用 Mini App 的容量。可通过 Mini App 导航栏的设置按钮删除各服务的数据。

**Mini App 通知 ON/OFF**

可以直接设置是否接收各个 Mini App 的通知。可通过 Mini App 导航栏的设置按钮对各服务通知进行 ON/OFF。

***

### 2. 导航栏自定义

`granite.config.ts`的 `navigationBar` 可通过选项设置导航栏的显示方式。

```typescript
interface NavigationBarOptions {
  withBackButton?: boolean;
  withHomeButton?: boolean;
  withTitle?: boolean;
  transparentBackground?: boolean;
  theme?: 'light' | 'dark';
  initialAccessoryButton?: InitialAccessoryButton;
}

interface InitialAccessoryButton {
  id: string;
  title?: string;
  icon: {
    name: string;
  };
}
```

* **`withBackButton`** — 设置是否在导航栏左侧显示返回按钮。
* **`withHomeButton`** — 设置是否在非游戏 Mini App 中显示返回主页的按钮。
* **`withTitle`** — 设置是否在导航栏左侧显示 Mini App 图标和 Mini App 名称。
* **`transparentBackground`** — 决定是否将导航栏背景设为透明。适用于内容延伸到导航栏下方的全屏布局。
* **`theme`** — 将导航栏主题设置为 `light` 或 `dark`。用于根据背景色调整按钮和文字颜色。
* **`initialAccessoryButton`** — 在更多按钮左侧区域初始显示辅助图标。一次只能显示 1 个。

例如，如果想隐藏 Mini App 图标和应用名称，并在深色背景上显示导航栏，可以按如下方式设置。

```typescript
navigationBar: {
  theme: 'dark',
  transparentBackground: true,
  withTitle: false,
}
```

如果想初始显示主页按钮和辅助图标，请按如下方式设置。

```typescript
navigationBar: {
  withBackButton: true,
  withHomeButton: true,
  initialAccessoryButton: {
    id: 'heart',
    title: 'Heart',
    icon: {
      name: 'icon-heart-mono',
    },
  },
}
```

如果希望在非游戏中也像游戏一样提升画面沉浸感，可以配置只保留更多按钮和关闭按钮、并使用透明背景的导航栏。

{% tabs %}
{% tab title="WebView" %}

```typescript
import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  // ...
  navigationBar: {
    withBackButton: false,
    withHomeButton: false,
    withTitle: false,
    transparentBackground: true,
  },
});
```

{% endtab %}

{% tab title="React Native" %}

```typescript
import { appsInToss } from '@apps-in-toss/framework/plugins';
import { defineConfig } from '@granite-js/react-native/config';

export default defineConfig({
  // ...
  plugins: [
    appsInToss({
      // ...
      navigationBar: {
        withBackButton: false,
        withHomeButton: false,
        withTitle: false,
        transparentBackground: true,
      },
    }),
  ],
});
```

{% endtab %}
{% endtabs %}

***

### 3. 设计指南

为了向用户传达一致的信息结构，顶部导航仅使用 **单色图标**。因为彩色图标会过度分散视觉注意力，并可能因不必要的强调造成混乱。除特殊情况外，全部 **统一使用单色图标**。

***

### 4. 添加辅助图标

游戏和非游戏 Mini App 都可以在右上角 **更多按钮左侧区域**添加一个图标。

#### 各平台设置方式

* **WebView**
  * `partner.addAccessoryButton()`可在运行时添加按钮。
  * 点击事件通过 `tdsEvent.addEventListener('navigationAccessoryEvent')`接收。
  * 初始显示通过 `defineConfig`的 `navigationBar.initialAccessoryButton` 选项使用。
* **React Native**
  * `useTopNavigation()`的 `addAccessoryButton()`可在运行时添加按钮。
  * 或 `granite.config.ts`的 `navigationBar.initialAccessoryButton`可用于在初始状态下显示按钮。

```typescript
interface NavigationBarOptions {
  withBackButton?: boolean; // 是否有返回按钮
  withHomeButton?: boolean; // 是否有主页按钮
  withTitle?: boolean; // 是否显示 Mini App 图标和应用名称
  transparentBackground?: boolean; // 背景是否透明
  theme?: 'light' | 'dark'; // 导航栏主题
  initialAccessoryButton?: InitialAccessoryButton; // 只能显示 1 个
}

interface InitialAccessoryButton {
  id: string;
  title?: string;
  icon: {
    name: string;
  };
}
```

#### 初始设置

{% tabs %}
{% tab title="Web" %}

```tsx
import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  // ...
  navigationBar: {
    withBackButton: true,
    withHomeButton: true,
    initialAccessoryButton: {
      id: 'heart',
      title: 'Heart',
      icon: {
        name: 'icon-heart-mono',
      },
    },
  },
});
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { appsInToss } from '@apps-in-toss/framework/plugins';
import { defineConfig } from '@granite-js/react-native/config';

export default defineConfig({
  // ...
  plugins: [
    appsInToss({
      // ...
      navigationBar: {
        withBackButton: true,
        withHomeButton: true,
        initialAccessoryButton: {
          icon: {
            name: 'icon-heart-mono',
          },
          id: 'heart',
          title: '心形',
        },
      },
    }),
  ],
});
```

{% endtab %}
{% endtabs %}

#### 动态添加

{% tabs %}
{% tab title="Web（JS）" %}

```js
import { partner, tdsEvent } from '@apps-in-toss/web-framework';

partner.addAccessoryButton({
  id: 'heart',
  title: '心形',
  icon: {
    name: 'icon-heart-mono',
  },
});

const cleanup = tdsEvent.addEventListener('navigationAccessoryEvent', {
  onEvent: ({ id }) => {
    if (id === 'heart') {
      console.log('按钮点击');
    }
  },
});

window.addEventListener('pagehide', () => {
  cleanup();
});
```

{% endtab %}

{% tab title="Web（React）" %}

```tsx
import { partner, tdsEvent } from '@apps-in-toss/web-framework';

useEffect(() => {
  partner.addAccessoryButton({
    id: 'heart',
    title: '心形',
    icon: {
      name: 'icon-heart-mono',
    },
  });

  const cleanup = tdsEvent.addEventListener('navigationAccessoryEvent', {
    onEvent: ({ id }) => {
      if (id === 'heart') {
        console.log('按钮点击');
      }
    },
  });

  return cleanup;
}, []);
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { useTopNavigation } from '@apps-in-toss/framework';
import { tdsEvent } from '@toss/tds-react-native';

const { addAccessoryButton } = useTopNavigation();

addAccessoryButton({
  id: 'heart',
  title: '心形',
  icon: {
    name: 'icon-heart-mono',
  },
  onPress: () => console.log('按钮点击'),
});

useEffect(() => {
  const cleanup = tdsEvent.addEventListener('navigationAccessoryEvent', {
    onEvent: ({ id }) => {
      if (id === 'heart') {
        console.log('heart 已点击');
      }
    },
  });

  return () => {
    cleanup();
  };
}, []);
```

{% endtab %}
{% endtabs %}

***

### 5. 添加主页按钮

在非游戏 Mini App 中，左上角可以显示 **返回主页的按钮**。主页按钮位于服务名称右侧，帮助用户随时返回首屏。与主页按钮相关的操作控制是 [控制事件](/documentation/api-and-sdk-zh/common/screen/event.md) 文档。

{% hint style="info" %}
**请注意**

* 请勿在右侧辅助按钮区域重复添加主页按钮。
* 主页按钮仅作为“服务入口”使用，不能添加自定义功能或文案。
  {% endhint %}

```typescript
interface NavigationBarOptions {
  withHomeButton?: boolean; // 是否显示主页按钮
}
```

```tsx
navigationBar: {
  withBackButton: true,
  withHomeButton: true,
}
```

***

### 参考事项

* 辅助按钮 **单色图标**仅支持
* 一次只能显示 1 个辅助按钮。
* 不支持添加彩色图标或自定义 UI。
* 主页按钮仅可在非游戏 Mini App 中使用。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/common/navigationbar.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.