#Стандартные компоненты и расширения

Интерфейс Portal состоит из двух частей: src/components/ui даёт базовые компоненты, а src/extensions содержит бизнес-модули. Эта страница о том, как пользоваться и тем, и другим.

#База компонентов

В src/components/ui лежит более 60 компонентов shadcn/ui — кнопки, формы, диалоги, выдвижные панели, таблицы, диаграммы, все привычные. Стиль настраивается в components.json, иконки берутся из lucide.

В отличие от подключения библиотеки компонентов, исходный код этих компонентов принадлежит вашему проекту. Он лежит в вашем репозитории, вы можете свободно его менять, и обновления из upstream его не перезапишут.

Именно поэтому настраивать их лучше композицией, а не прямой правкой:

// Рекомендуется: обернуть, чтобы базовый компонент оставался заменяемым
import { Button } from "@/components/ui/button";

export function SubmitButton(props) {
  return <Button variant="default" size="lg" {...props} />;
}

Править src/components/ui/button.tsx напрямую тоже можно, но потом будет сложнее подхватывать исправления ошибок из upstream. Когда базовый компонент всё же нужно изменить, сначала сравните его с версией из upstream и переносите изменения выборочно, а не перезаписывайте свои правки целиком.

#Механизм расширений

Бизнес-функции пишутся как расширения в src/extensions/, по одному каталогу на функциональный модуль:

src/extensions/
├── nocobase-acl/               Компоненты прав доступа
├── nocobase-ai/                Возможности ИИ-диалога
├── nocobase-route-surfaces/    Страницы, выдвижные панели и модальные окна как носители маршрутов
└── nocobase-users-example/     Пример управления пользователями

В каждом каталоге есть extension.tsx с экспортом по умолчанию — объектом AppExtension. Шаблон сканирует и загружает их автоматически: положили в каталог — работает, никакой регистрационный код править не нужно.

#AppExtension

Расширение может предоставлять следующее:

Минимальное расширение выглядит так:

import type { AppExtension } from "@/app/extension";
import { Route } from "react-router";
import { Package } from "lucide-react";
import { ProductList } from "./list";

const productsExtension: AppExtension = {
  id: "products",
  resources: [
    {
      name: "products",
      list: "/products",
      meta: {
        label: "Products",
        icon: <Package />,
        acl: { type: "collection" }, // Участвует в проверке прав доступа к таблицам данных NocoBase
      },
    },
  ],
  routes: <Route path="/products" element={<ProductList />} />,
};

export default productsExtension;

#Встроенные расширения

В шаблоне есть четыре расширения. Ими можно пользоваться сразу, и они же — лучший образец при написании нового кода:

nocobase-users-example — законченный модуль операций с данными на стандартной таблице users из NocoBase, со списком, созданием, редактированием и просмотром деталей. Указывайте на него ИИ, когда делаете новую страницу.

nocobase-acl — компоненты прав доступа: CanAccess, AclPage, AclRegion, AclField и RoleSwitcher.

nocobase-route-surfaces — три носителя маршрутов: страница целиком, выдвижная панель и модальное окно. Одно и то же содержимое может открываться как отдельная страница или всплывать выдвижной панелью внутри страницы со списком, а состояние маршрута остаётся согласованным.

nocobase-ai — переносит возможности ИИ-диалога NocoBase на фронтенд: окно чата, потоковую передачу, историю диалогов и контекст страницы. С его помощью можно встроить ИИ-помощника в собственный Portal.

#Правила импорта

При написании расширения действуют два соглашения о путях:

• Для всего, что относится к приложению-хосту, используйте псевдоним @/, например @/components/ui/button
• Относительные импорты внутри расширения не должны выходить за пределы его собственного каталога

Так каждое расширение остаётся самодостаточным: его каталог можно целиком скопировать в другой Portal и продолжать им пользоваться.

#Официальные расширения для установки

Помимо четырёх встроенных, NocoBase будет предоставлять набор официальных расширений, которые можно установить по мере надобности. После установки исходный код окажется в src/extensions/ и станет собственным кодом вашего проекта, как и у встроенного расширения — его можно менять и коммитить вместе с приложением.

#Локализация

Строки лежат в src/locales/, в шаблоне есть английский и китайский. У расширения тоже может быть собственный языковой пакет: создайте внутри расширения каталог locales/ и импортируйте его из extension.tsx.

#Связанные ссылки

• Быстрый старт AI Portal — запустите первую точку входа с фронтендом, написанным ИИ
• Структура проекта и технологический стек — полные соглашения о каталогах и часто используемые команды
• Совместная разработка с ИИ агентом — пусть ИИ пишет новый модуль по образцу встроенного расширения