导航栏设置

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

请参考

迷你应用 Logo 设置请参考 WebView 设置或 React Native 设置文档。

---

1. 导航栏基础功能

游戏

游戏用导航栏由 更多按钮与 关闭(X)按钮组成。 granite.config.ts在其中将应用类型 game设为 game 后，就可以使用游戏导航栏。

WebView

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

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

React Native

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

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

请参考

• safeArea 请参考文档进行开发，以确保 X 按钮不会与游戏画面的其他按钮重叠。

非游戏

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

更多按钮功能

可通过更多按钮直接使用下列功能，无需单独对接服务器或额外实现。

咨询 / 举报

在控制台中登记的 客服链接和主页地址会自动显示。通过举报功能，用户可以提交反馈，合作伙伴可通过控制台查看反馈内容。

分享

用户可以轻松将迷你应用分享给他人。分享时会一并发送 迷你应用名称与 深度链接地址。

权限设置

用户可以确认迷你应用请求的权限，并随时通过 ON/OFF 进行控制。

添加到主屏幕

常用的迷你应用可以直接添加到手机主屏幕。从 Toss App 5.246.0 及以上版本开始可查看。

删除迷你应用容量

可以选择性删除不常用迷你应用的存储空间。可通过迷你应用导航栏的设置按钮删除各服务的数据。

迷你应用通知 ON/OFF

可直接设置是否接收各迷你应用的通知。可通过迷你应用导航栏的设置按钮对各服务的通知进行 ON/OFF。

---

2. 导航栏自定义

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

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 — 设置是否在非游戏迷你应用中显示返回首页按钮。
• withTitle — 设置是否在导航栏左侧显示迷你应用图标和迷你应用名称。
• transparentBackground — 决定是否将导航栏背景设为透明。适用于内容延伸到导航栏下方的全屏布局。
• theme — 将导航栏主题设置为 light 或 dark。用于根据背景色调整按钮和文字颜色。
• initialAccessoryButton — 在更多按钮左侧区域初始展示一个附加图标。一次只能显示 1 个。

例如，如果想隐藏迷你应用图标和应用名称，并让导航栏覆盖在深色背景上，可以这样设置。

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

如果想初始显示首页按钮和附加图标，可以这样设置。

navigationBar: {
  withBackButton: true,
  withHomeButton: true,
  initialAccessoryButton: {
    id: 'heart',
    title: '爱心',
    icon: {
      name: 'icon-heart-mono',
    },
  },
}

如果想在非游戏中也像游戏一样提高画面的沉浸感，可以把导航栏设置为透明背景，只保留更多按钮和关闭按钮。

WebView

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

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

React Native

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,
      },
    }),
  ],
});

---

3. 设计指南

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

---

4. 添加附加图标

游戏和非游戏迷你应用都可以在右上角 更多按钮左侧区域添加一个图标。

各平台设置方式

• WebView

  • partner.addAccessoryButton()可在运行时添加按钮。
  • 点击事件通过 tdsEvent.addEventListener('navigationAccessoryEvent')接收。
  • 初始展示通过 defineConfig中 navigationBar.initialAccessoryButton 选项来使用。
• React Native

  • useTopNavigation()中 addAccessoryButton()可在运行时添加按钮。
  • 或 granite.config.ts中 navigationBar.initialAccessoryButton可用于在初始状态下显示按钮。

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

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

初始设置

Web

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

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

React Native

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: '爱心',
        },
      },
    }),
  ],
});

动态添加

Web（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();
});

Web（React）

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;
}, []);

React Native

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();
  };
}, []);

---

5. 添加首页按钮

在非游戏迷你应用中，左上角可以显示 返回首页按钮。首页按钮位于服务名称右侧，帮助用户随时返回初始页面。与首页按钮相关的动作控制请参考 事件控制 文档。

请注意

• 请不要在右侧附加按钮区域重复添加首页按钮。
• 首页按钮只承担“服务入口点”的作用，不能添加自定义功能或文案。

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

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

---

参考事项

• 附加按钮 仅使用单色图标仅支持。
• 一次只能显示 1 个附加按钮。
• 不支持添加彩色图标或自定义 UI。
• 首页按钮仅可在非游戏迷你应用中使用。