管理面板 API：导航与设置

🌐 Admin Panel API: Navigation & settings

Page summary:

在 register 中使用 addMenuLink 来添加侧边栏链接，在 register 中使用 createSettingSection 来创建设置组，并在 bootstrap 中使用 addSettingsLink/addSettingsLinks 来扩展现有的设置部分。

🌐 Use addMenuLink in register to add sidebar links, createSettingSection in register to create settings groups, and addSettingsLink/addSettingsLinks in bootstrap to extend existing settings sections.

插件可以自定义管理员面板的导航侧边栏和设置页面，以提供对其功能的访问。本文所述的所有功能都是在插件入口文件的 register 或 bootstrap 生命周期函数中调用的。

🌐 Plugins can customize the admin panel's navigation sidebar and settings pages to provide access to their features. All functions described on this page are called within the register or bootstrap lifecycle functions of your plugin's entry file.

Prerequisites

在深入了解本页的概念之前，请确保你已经：

🌐 Before diving deeper into the concepts on this page, please ensure you have:

• 创建了一个 Strapi 插件，
• 已阅读并理解了 管理面板 API 的基础知识

导航侧边栏（菜单链接）

🌐 Navigation sidebar (menu links)

导航侧边栏是管理员面板左侧的主菜单。插件可以使用 register 生命周期函数中的 addMenuLink() 方法向此侧边栏添加链接。

🌐 The navigation sidebar is the main menu on the left side of the admin panel. Plugins can add links to this sidebar using the addMenuLink() method in the register lifecycle function.

添加菜单链接

🌐 Adding a menu link

将链接添加到导航侧边栏是通过 addMenuLink() 函数完成的，该函数应通过插件的 register() 生命周期函数进行注册。

🌐 Adding a link to the navigation sidebar is done with the addMenuLink() function, which should be registered through the register() lifecycle function of your plugin.

菜单链接接受以下参数：

🌐 A menu link accepts the following parameters:

参数	类型	必填	描述
to	string	✅	链接应指向的路径（相对于管理面板根目录）（参见附加信息）
icon	React.Component	✅	用于在导航中显示图标的 React 组件
intlLabel	object	✅	链接的标签，遵循 React Int'l 约定，包括: id: 用于插入本地化标签的ID defaultMessage: 链接的默认标签
Component	async function	✅	返回插件主页面组件的动态导入的异步函数
permissions	Array<object>	❌	控制对链接访问的权限对象数组
position	number	❌	菜单中的数字位置（数字越小越先显示）
licenseOnly	boolean	❌	如果 true，显示 ⚡ 图标以表示该功能需要付费许可（默认值：false）

Note

intlLabel.id 值应对应位于 admin/src/translations/[locale].json 的翻译文件中的键。详情请参见 管理员本地化。

🌐 The intlLabel.id values should correspond to keys in your translation files located at admin/src/translations/[locale].json. See Admin localization for details.

Caution

permissions 参数仅控制链接是否在导航中可见。它并不能保护页面本身。知道 URL 的用户仍然可以直接访问该页面。要完全保护插件路由，你还必须在页面组件内部检查权限，并在服务器端使用 actionProvider.registerMany 注册你的 RBAC 操作。有关完整操作步骤，请参阅 插件的管理员权限 指南。

🌐 The permissions parameter only controls whether the link is visible in the navigation. It does not protect the page itself. A user who knows the URL can still access the page directly. To fully secure a plugin route, you must also check permissions inside your page component and register your RBAC actions on the server side with actionProvider.registerMany. See the Admin permissions for plugins guide for a complete walkthrough.

JavaScript

admin/src/index.js

import PluginIcon from './components/PluginIcon';

export default {
  register(app) {
    app.addMenuLink({
      to: `/plugins/my-plugin`,
      icon: PluginIcon,
      intlLabel: {
        id: 'my-plugin.plugin.name',
        defaultMessage: 'My Plugin',
      },
      Component: async () => {
        const { App } = await import('./pages/App');
        return App;
      },
      permissions: [], // Array of permission objects
      position: 3, // Position in the menu (lower numbers appear first)
      licenseOnly: false, // Set to true to show ⚡ icon for paid features
    });

    app.registerPlugin({
      id: 'my-plugin',
      name: 'My Plugin',
    });
  },
};

TypeScript

admin/src/index.ts

import PluginIcon from './components/PluginIcon';
import type { StrapiApp } from '@strapi/admin/strapi-admin';

export default {
  register(app: StrapiApp) {
    app.addMenuLink({
      to: `/plugins/my-plugin`,
      icon: PluginIcon,
      intlLabel: {
        id: 'my-plugin.plugin.name',
        defaultMessage: 'My Plugin',
      },
      Component: async () => {
        const { App } = await import('./pages/App');
        return App;
      },
      permissions: [], // Array of permission objects
      position: 3, // Position in the menu (lower numbers appear first)
      licenseOnly: false, // Set to true to show ⚡ icon for paid features
    });

    app.registerPlugin({
      id: 'my-plugin',
      name: 'My Plugin',
    });
  },
};

设置

🌐 Settings

设置 API 允许插件创建新的设置部分或向现有部分添加链接。设置部分是组织好的配置页面组，可以从导航侧边栏的 _设置_菜单项访问。

创建新的设置部分

🌐 Creating a new settings section

在 register 生命周期函数中使用 createSettingSection()：

🌐 Use createSettingSection() in the register lifecycle function:

JavaScript

admin/src/index.js

export default {
  register(app) {
    app.createSettingSection(
      {
        id: 'my-plugin',
        intlLabel: {
          id: 'my-plugin.settings.section-label',
          defaultMessage: 'My Plugin Settings',
        },
      },
      [
        {
          intlLabel: {
            id: 'my-plugin.settings.general',
            defaultMessage: 'General',
          },
          id: 'general',
          to: 'my-plugin/general',
          Component: async () => {
            const { GeneralSettings } =
              await import('./pages/Settings/General');
            return GeneralSettings;
          },
        },
        {
          intlLabel: {
            id: 'my-plugin.settings.advanced',
            defaultMessage: 'Advanced',
          },
          id: 'advanced',
          to: 'my-plugin/advanced',
          Component: async () => {
            const { AdvancedSettings } =
              await import('./pages/Settings/Advanced');
            return AdvancedSettings;
          },
        },
      ],
    );

    app.registerPlugin({
      id: 'my-plugin',
      name: 'My Plugin',
    });
  },
};

TypeScript

admin/src/index.ts

import type { StrapiApp } from '@strapi/admin/strapi-admin';

export default {
  register(app: StrapiApp) {
    app.createSettingSection(
      {
        id: 'my-plugin',
        intlLabel: {
          id: 'my-plugin.settings.section-label',
          defaultMessage: 'My Plugin Settings',
        },
      },
      [
        {
          intlLabel: {
            id: 'my-plugin.settings.general',
            defaultMessage: 'General',
          },
          id: 'general',
          to: 'my-plugin/general',
          Component: async () => {
            const { GeneralSettings } =
              await import('./pages/Settings/General');
            return GeneralSettings;
          },
        },
        {
          intlLabel: {
            id: 'my-plugin.settings.advanced',
            defaultMessage: 'Advanced',
          },
          id: 'advanced',
          to: 'my-plugin/advanced',
          Component: async () => {
            const { AdvancedSettings } =
              await import('./pages/Settings/Advanced');
            return AdvancedSettings;
          },
        },
      ],
    );

    app.registerPlugin({
      id: 'my-plugin',
      name: 'My Plugin',
    });
  },
};

createSettingSection() 函数接受以下参数：

🌐 The createSettingSection() function accepts the following parameters:

• 第一个参数是部分配置：

  参数	类型	必填	描述
  id	string	✅	设置部分的唯一标识符
  intlLabel	object	✅	部分的本地化标签，遵循 React Int'l 约定，具体为： id：用于插入本地化标签的ID defaultMessage：部分的默认标签

• 第二个参数是一个链接对象数组；每个链接对象包含以下内容：

  参数	类型	必填	描述
  id	string	✅	设置链接的唯一标识
  to	string	✅	相对于设置路由的路径（不要包含 settings/ 前缀）（参见 附加信息）
  intlLabel	object	✅	带有 id 和 defaultMessage 的本地化标签对象
  Component	async function	✅	异步函数，返回设置页面组件的动态导入
  permissions	Array<object>	❌	控制访问链接的权限对象数组
  licenseOnly	boolean	❌	如果为 true，显示 ⚡ 图标（默认值：false）

向现有设置部分添加链接

🌐 Adding links to existing settings sections

要向现有设置部分添加单个链接，请在 bootstrap() 生命周期函数中使用 addSettingsLink()。要一次添加多个链接，请使用 addSettingsLinks()。

🌐 To add a single link to an existing settings section, use addSettingsLink() in the bootstrap() lifecycle function. To add multiple links at once, use addSettingsLinks().

JavaScript

admin/src/index.js

export default {
  register(app) {
    app.registerPlugin({
      id: 'my-plugin',
      name: 'My Plugin',
    });
  },
  bootstrap(app) {
    // Add a single link to the global settings section
    app.addSettingsLink('global', {
      intlLabel: {
        id: 'my-plugin.settings.documentation',
        defaultMessage: 'Documentation',
      },
      id: 'documentation',
      to: 'my-plugin/documentation',
      Component: async () => {
        const { DocumentationPage } =
          await import('./pages/Settings/Documentation');
        return DocumentationPage;
      },
      permissions: [],
      licenseOnly: false,
    });

    // Add multiple links at once to the global settings section
    app.addSettingsLinks('global', [
      {
        intlLabel: {
          id: 'my-plugin.settings.general',
          defaultMessage: 'General',
        },
        id: 'general',
        to: 'my-plugin/general',
        Component: async () => {
          const { GeneralSettings } =
            await import('./pages/Settings/General');
          return GeneralSettings;
        },
      },
      {
        intlLabel: {
          id: 'my-plugin.settings.advanced',
          defaultMessage: 'Advanced',
        },
        id: 'advanced',
        to: 'my-plugin/advanced',
        Component: async () => {
          const { AdvancedSettings } =
            await import('./pages/Settings/Advanced');
          return AdvancedSettings;
        },
      },
    ]);
  },
};

TypeScript

admin/src/index.ts

import type { StrapiApp } from '@strapi/admin/strapi-admin';

export default {
  register(app: StrapiApp) {
    app.registerPlugin({
      id: 'my-plugin',
      name: 'My Plugin',
    });
  },
  bootstrap(app: StrapiApp) {
    // Add a single link to the global settings section
    app.addSettingsLink('global', {
      intlLabel: {
        id: 'my-plugin.settings.documentation',
        defaultMessage: 'Documentation',
      },
      id: 'documentation',
      to: 'my-plugin/documentation',
      Component: async () => {
        const { DocumentationPage } =
          await import('./pages/Settings/Documentation');
        return DocumentationPage;
      },
      permissions: [],
      licenseOnly: false,
    });

    // Add multiple links at once to the global settings section
    app.addSettingsLinks('global', [
      {
        intlLabel: {
          id: 'my-plugin.settings.general',
          defaultMessage: 'General',
        },
        id: 'general',
        to: 'my-plugin/general',
        Component: async () => {
          const { GeneralSettings } =
            await import('./pages/Settings/General');
          return GeneralSettings;
        },
      },
      {
        intlLabel: {
          id: 'my-plugin.settings.advanced',
          defaultMessage: 'Advanced',
        },
        id: 'advanced',
        to: 'my-plugin/advanced',
        Component: async () => {
          const { AdvancedSettings } =
            await import('./pages/Settings/Advanced');
          return AdvancedSettings;
        },
      },
    ]);
  },
};

addSettingsLink 和 addSettingsLinks 都将 sectionId 字符串作为第一个参数（例如，'global' 或 'permissions'）。第二个参数对于 addSettingsLink 是单个链接对象，对于 addSettingsLinks 是链接对象数组，使用与 createSettingSection()（见上表） 中的 links 数组相同的属性。

可用的设置部分

🌐 Available settings sections

Strapi 提供了内置的设置部分，插件可以扩展这些部分：

🌐 Strapi provides built-in settings sections that plugins can extend:

• global：通用应用设置
• permissions：管理面板设置

Note

创建新的设置部分必须在 register 生命周期函数中完成。向现有设置部分添加链接必须在 bootstrap 生命周期函数中完成。

🌐 Creating a new settings section must be done in the register lifecycle function. Adding links to existing settings sections must be done in the bootstrap lifecycle function.

to 的路径约定

🌐 Path conventions for to

to 参数的行为取决于上下文：

🌐 The to parameter behaves differently depending on the context: | 上下文 | to 值 | 最终网址 ||---|---|---|| addMenuLink | /plugins/my-plugin | http://localhost:1337/admin/plugins/my-plugin || createSettingSection 链接 | my-plugin/general | http://localhost:1337/admin/settings/my-plugin/general || addSettingsLink | my-plugin/documentation | http://localhost:1337/admin/settings/my-plugin/documentation |

对于菜单链接，路径是相对于管理面板根目录（/admin）。对于设置链接，路径是相对于设置路由（/admin/settings）。在设置链接路径中不要包含 settings/ 前缀。

🌐 For menu links, the path is relative to the admin panel root (/admin). For settings links, the path is relative to the settings route (/admin/settings). Do not include the settings/ prefix in settings link paths.

Securing plugin routes

链接上的 permissions 参数仅控制在导航中的可见性。要完全保护你的插件页面并注册 RBAC 操作，请参阅 插件的管理员权限 指南。

🌐 The permissions parameter on links only controls visibility in the navigation. To fully protect your plugin pages and register RBAC actions, see the Admin permissions for plugins guide.