管理面板 API：导航与设置

🌐 Admin Panel API: Navigation & settings

Page summary:

在 register 中使用 addMenuLink 来添加侧边栏链接。使用 addSettingsLink 可以创建新的设置部分（将部分对象作为第一个参数传递）以及扩展现有部分（传递部分 ID 字符串）。传统的 createSettingSection 和 addSettingsLinks 方法已被弃用。

🌐 Use addMenuLink in register to add sidebar links. Use addSettingsLink to both create new settings sections (pass a section object as the first argument) and extend existing ones (pass a section id string). The legacy createSettingSection and addSettingsLinks methods are deprecated.

插件可以自定义管理员面板的导航侧边栏和设置页面，以提供对其功能的访问。本文所述的所有功能都是在插件入口文件的 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.ElementType	✅	用于在导航中显示图标的 React 组件
intlLabel	object	✅	链接的标签，遵循 React Int'l 约定，包括: id: 用于插入本地化标签的ID defaultMessage: 链接的默认标签
permissions	Array<Permission>	✅	控制链接可见性的权限对象数组。传递 [] 表示无限制。
Component	function	❌	返回插件主页面组件的动态 import() 的函数。页面模块必须将组件导出为 default。如果省略，则不注册路由（仅标签条目）。
position	number	❌	菜单中的数字位置（数字越小越先显示）
licenseOnly	boolean	❌	如果 true，显示 ⚡ 图标以表示该功能需要付费许可（默认值：false）
target	string	❌	标准锚点 target 属性（例如，外部链接的 _blank）
notificationsCount	number	❌	徽章数量显示在菜单标签旁边
exact	boolean	❌	活动链接匹配是否应精确

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: () => import('./pages/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: () => import('./pages/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',
    });
  },
};

Note

由 Component 引用的页面模块必须将组件作为 默认导出（例如在 admin/src/pages/App.tsx 中的 export default App;）。早期版本的 Strapi 接受返回命名导出的 async 回调，但这种模式已被弃用，并在运行时记录警告。使用 Component: () => import(path)，以便动态导入直接解析为模块的默认导出。

🌐 The page module referenced by Component must export the component as the default export (e.g. export default App; in admin/src/pages/App.tsx). Earlier versions of Strapi accepted an async callback that returned a named export, but this pattern is deprecated and logs a warning at runtime. Use Component: () => import(path) so the dynamic import directly resolves to the module's default export.

设置

🌐 Settings

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

创建新的设置部分

🌐 Creating a new settings section

要创建一个新的设置部分，请使用 section 对象（{ id, intlLabel }）作为第一个参数、链接对象数组作为第二个参数调用 addSettingsLink()。这可以在 register 或 bootstrap 生命周期函数中完成：

🌐 To create a new settings section, call addSettingsLink() with a section object ({ id, intlLabel }) as the first argument and an array of link objects as the second argument. This can be done in either the register or bootstrap lifecycle function:

JavaScript

admin/src/index.js

export default {
  register(app) {
    app.addSettingsLink(
      {
        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: () => import('./pages/Settings/General'),
        },
        {
          intlLabel: {
            id: 'my-plugin.settings.advanced',
            defaultMessage: 'Advanced',
          },
          id: 'advanced',
          to: 'my-plugin/advanced',
          Component: () => import('./pages/Settings/Advanced'),
        },
      ],
    );

    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.addSettingsLink(
      {
        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: () => import('./pages/Settings/General'),
        },
        {
          intlLabel: {
            id: 'my-plugin.settings.advanced',
            defaultMessage: 'Advanced',
          },
          id: 'advanced',
          to: 'my-plugin/advanced',
          Component: () => import('./pages/Settings/Advanced'),
        },
      ],
    );

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

当用于创建新部分时，addSettingsLink() 接受以下参数：

🌐 When used to create a new section, addSettingsLink() accepts the following parameters:

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

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

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

  参数	类型	必填	描述
  id	string	✅	设置链接的唯一标识符
  to	string	✅	相对于设置路由的路径（不要包含 settings/ 前缀）（参见 附加信息）
  intlLabel	object	✅	包含 id 和 defaultMessage 的本地化标签对象
  permissions	Array<Permission>	✅	控制链接可见性的权限对象数组。传递 [] 表示无限制。
  Component	function	❌	返回设置页面组件动态 import() 的函数。页面模块必须将组件导出为 default。如果省略，则不注册路由（仅标签条目）。
  position	number	❌	在该部分中的数字位置（数字越小越先显示）
  licenseOnly	boolean	❌	如果 true，显示 ⚡ 图标（默认：false）
  exact	boolean	❌	是否必须精确匹配活动链接

Caution

Deprecated: createSettingSection()

专用的 app.createSettingSection(section, links) 方法已被弃用。它仍然可以使用（它内部委托给 addSettingsLink），但新代码应直接调用 addSettingsLink(section, links)。请参阅 已弃用的方法。

🌐 The dedicated app.createSettingSection(section, links) method is deprecated. It still works (it delegates to addSettingsLink internally) but new code should call addSettingsLink(section, links) directly. See Deprecated methods.

向现有设置部分添加链接

🌐 Adding links to existing settings sections

要向现有的设置部分添加链接，请在 bootstrap() 生命周期函数中使用 addSettingsLink()，并将部分 ID 字符串作为第一个参数。第二个参数可以是单个链接对象，也可以是链接对象数组。两种形式都由相同的方法支持。

🌐 To add links to an existing settings section, use addSettingsLink() in the bootstrap() lifecycle function with a section id string as the first argument. The second argument can be either a single link object or an array of link objects. Both forms are supported by the same method.

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: () => import('./pages/Settings/Documentation'),
      permissions: [],
      licenseOnly: false,
    });

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

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: () => import('./pages/Settings/Documentation'),
      permissions: [],
      licenseOnly: false,
    });

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

addSettingsLink 将 sectionId 字符串作为第一个参数（例如，'global' 或 'permissions'）。第二个参数要么是单个链接对象，要么是链接对象数组，使用与 创建新设置部分 中的 links 数组相同的属性。

Caution

Deprecated: addSettingsLinks()

复数形式 app.addSettingsLinks(sectionId, links) 方法已被弃用。请改用 addSettingsLink(sectionId, links)（单数形式）并传入数组；它既接受单个链接也接受数组。参见 已弃用的方法。

🌐 The plural app.addSettingsLinks(sectionId, links) method is deprecated. Call addSettingsLink(sectionId, links) (singular) with an array instead; it accepts both single links and arrays. See Deprecated methods.

可用的设置部分

🌐 Available settings sections

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

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

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

Note

创建一个新的设置部分通常在 register 生命周期函数中完成，而向现有设置部分添加链接则在 bootstrap 中完成（因为目标部分可能由另一个插件注册）。两种形式都调用相同的 addSettingsLink() 方法，该方法在 register 的 app 参数上可用，并且在 bootstrap 参数包中作为 addSettingsLink 提供。

🌐 Creating a new settings section is typically done in the register lifecycle function, while adding links to existing settings sections is done in bootstrap (because the target section may be registered by another plugin). Both forms call the same addSettingsLink() method, which is exposed on the app argument of register and as addSettingsLink in the bootstrap argument bag.

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
addSettingsLink（带部分对象）	my-plugin/general	http://localhost:1337/admin/settings/my-plugin/general
addSettingsLink（带部分 ID）	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.

已弃用的方法

🌐 Deprecated methods

StrapiApp 实例上的以下方法已被弃用。它们仍然可以为了向后兼容而使用（内部都委托给 addSettingsLink()），但新代码应直接使用 addSettingsLink()。

🌐 The following methods on the StrapiApp instance are deprecated. They still work for backwards compatibility (both delegate to addSettingsLink() internally), but new code should use addSettingsLink() directly.

createSettingSection(section, links)

以前用于在一次调用中注册新的设置部分及其初始链接。

🌐 Previously used to register a new settings section and its initial links in one call.

// ❌ Deprecated
app.createSettingSection(
  { id: 'my-plugin', intlLabel: { id: 'my-plugin.settings.section-label', defaultMessage: 'My Plugin Settings' } },
  [{ id: 'general', to: 'my-plugin/general', intlLabel: { id: 'my-plugin.settings.general', defaultMessage: 'General' }, Component: () => import('./pages/Settings/General') }],
);

// ✅ Replacement: pass the section object as the first argument to addSettingsLink
app.addSettingsLink(
  { id: 'my-plugin', intlLabel: { id: 'my-plugin.settings.section-label', defaultMessage: 'My Plugin Settings' } },
  [{ id: 'general', to: 'my-plugin/general', intlLabel: { id: 'my-plugin.settings.general', defaultMessage: 'General' }, Component: () => import('./pages/Settings/General') }],
);

addSettingsLinks(sectionId, links)

以前用于在一次调用中向现有部分添加多个链接。现在单个 addSettingsLink() 接受单个链接对象或数组。

🌐 Previously used to add multiple links to an existing section in one call. The singular addSettingsLink() now accepts either a single link object or an array.

// ❌ Deprecated
app.addSettingsLinks('global', [
  { id: 'general', to: 'my-plugin/general', intlLabel: { id: 'my-plugin.settings.general', defaultMessage: 'General' }, Component: () => import('./pages/Settings/General') },
  { id: 'advanced', to: 'my-plugin/advanced', intlLabel: { id: 'my-plugin.settings.advanced', defaultMessage: 'Advanced' }, Component: () => import('./pages/Settings/Advanced') },
]);

// ✅ Replacement: pass the array to addSettingsLink (singular)
app.addSettingsLink('global', [
  { id: 'general', to: 'my-plugin/general', intlLabel: { id: 'my-plugin.settings.general', defaultMessage: 'General' }, Component: () => import('./pages/Settings/General') },
  { id: 'advanced', to: 'my-plugin/advanced', intlLabel: { id: 'my-plugin.settings.advanced', defaultMessage: 'Advanced' }, Component: () => import('./pages/Settings/Advanced') },
]);

Note

• addSettingsLinks 仍然在 bootstrap 参数包上公开（与 addSettingsLink、getPlugin 和 registerHook 一起），以保持向后兼容性。
• createSettingSection 只能通过传递给 register(app) 的完整 app 实例访问；它不是 bootstrap 参数包的一部分。
• 两者在内部都委托给 addSettingsLink()，并可能在未来的主要版本中被移除。请在方便时进行迁移。