• Русский

      • Разработка Component-компонентов

      В NocoBase компоненты страниц, монтируемые через маршруты, — это обычные React-компоненты. Их можно писать прямо на React + Antd, как при обычной фронтенд-разработке.

      Дополнительно NocoBase предоставляет:

      • observable + observer — рекомендуемый способ управления состоянием, лучше подходит для экосистемы NocoBase, чем useState
      • useFlowContext() — получение возможностей контекста NocoBase (запросы, интернационализация, маршрутная навигация и т.д.)

      Базовый синтаксис

      Простейший компонент страницы:

      // pages/HelloPage.tsx
export default function HelloPage() {
  return <h1>Hello, NocoBase!</h1>;
}

      После написания зарегистрируйте его в load() плагина через this.router.add(). Подробности см. в Router (Маршрутизация).

      Управление состоянием: observable

      В NocoBase для управления состоянием компонентов рекомендуется использовать observable + observer вместо React-овского useState. Преимущества:

      • Прямое изменение свойств объекта вызывает обновление, не нужен setState
      • Автоматическое отслеживание зависимостей: компонент перерисовывается только при изменении используемых свойств
      • Соответствует реактивному механизму нижележащего слоя NocoBase (FlowModel, FlowContext и т.д.)

      Базовое использование: создаёте реактивный объект через observable.deep(), оборачиваете компонент в observer(). И observable, и observer импортируются из @nocobase/flow-engine:

      import React from 'react';
import { Input } from 'antd';
import { observable, observer } from '@nocobase/flow-engine';

// 创建一个响应式状态对象
const state = observable.deep({
  text: '',
});

// 用 observer 包裹组件，状态变化时自动更新
const DemoPage = observer(() => {
  return (
    <div>
      <Input
        placeholder="输入点什么..."
        value={state.text}
        onChange={(e) => {
          state.text = e.target.value;
        }}
      />
      {state.text && <div style={{ marginTop: 8 }}>你输入了：{state.text}</div>}
    </div>
  );
});

export default DemoPage;

      Предварительный просмотр:

      import { Application, Plugin } from '@nocobase/client-v2';

class MyPlugin extends Plugin {
  async load() {
    this.router.add('root', {
      path: '/',
      componentLoader: () => import('@docs/cn/plugin-development/client/component/_demos/observable-basic-page'),
    });
  }
}

// 下面的代码只是为了让这个 demo 能在文档中独立运行，实际开发插件时无需关注 app 的实例化。
const app = new Application({
  // 代码示例里用了 memory router，实际项目里用户无需关注这个，app 实例化由 Nocobase 内部完成。
  router: { type: 'memory', initialEntries: ['/'] },
  plugins: [MyPlugin],
});

export default app.getRootComponent();

      Больше способов использования см. в Реактивный механизм Observable.

      Использование useFlowContext

      useFlowContext() — это точка входа для подключения возможностей NocoBase. Импортируется из @nocobase/flow-engine, возвращает объект ctx:

      import { useFlowContext } from '@nocobase/flow-engine';

export default function MyPage() {
  const ctx = useFlowContext();
  // ctx.api — 发请求
  // ctx.t — 国际化
  // ctx.router — 路由导航
  // ctx.logger — 日志
  // ...
}

      Ниже приведены примеры распространённых возможностей.

      Отправка запросов

      Через ctx.api.request() вызываются бэкенд-интерфейсы, использование совпадает с Axios:

      const response = await ctx.api.request({
  url: 'users:list',
  method: 'get',
});
console.log(response.data);

      Интернационализация

      Через ctx.t() получаем переведённый текст:

      const label = ctx.t('Hello');
// 指定命名空间
const msg = ctx.t('Save success', { ns: '@my-project/plugin-hello' });

      Маршрутная навигация

      Через ctx.router.navigate() выполняется переход между страницами:

      ctx.router.navigate('/some-page'); // -> /v/some-page

      Получение параметров текущего маршрута:

      // 比如路由定义为 /users/:id
const { id } = ctx.route.params; // 获取动态参数

      Получение имени текущего маршрута:

      const { name } = ctx.route; // 获取路由名字

      Подробнее про уровни логирования и использование см. в Context → Распространённые возможности.

      Полный пример

      Объединим observable, useFlowContext и Antd — компонент страницы, который получает данные с бэкенда и отображает их:

      // pages/PostListPage.tsx
import React, { useEffect } from 'react';
import { Button, Card, List, Spin } from 'antd';
import { observable, observer, FlowContext, useFlowContext } from '@nocobase/flow-engine';

interface Post {
  id: number;
  title: string;
}

// 用 observable 管理页面状态
const state = observable.deep({
  posts: [] as Post[],
  loading: true,
});

const PostListPage = observer(() => {
  const ctx = useFlowContext();

  useEffect(() => {
    loadPosts(ctx);
  }, []);

  return (
    <Card title={ctx.t('Post list')}>
      <Spin spinning={state.loading}>
        <List
          dataSource={state.posts}
          renderItem={(post: Post) => (
            <List.Item
              actions={[
                <Button danger onClick={() => handleDelete(ctx, post.id)}>
                  {ctx.t('Delete')}
                </Button>,
              ]}
            >
              {post.title}
            </List.Item>
          )}
        />
      </Spin>
    </Card>
  );
});

async function loadPosts(ctx: FlowContext) {
  state.loading = true;
  try {
    const response = await ctx.api.request({
      url: 'posts:list',
      method: 'get',
    });
    state.posts = response.data?.data || [];
  } catch (error) {
    ctx.logger.error('加载文章列表失败', { error });
  } finally {
    state.loading = false;
  }
}

async function handleDelete(ctx: FlowContext, id: number) {
  await ctx.api.request({
    url: `posts:destroy/${id}`,
    method: 'post',
  });
  loadPosts(ctx); // 刷新列表
}

export default PostListPage;

      Что дальше

      • Полные возможности, предоставляемые useFlowContext — см. Context (Контекст)
      • Стилизация компонентов и кастомизация темы — см. Styles & Themes (Стили и темы)
      • Если Ваш компонент должен появиться в меню «Добавить блок / поле / действие» NocoBase и поддерживать визуальную конфигурацию пользователем, нужно обернуть его в FlowModel — см. FlowEngine
      • Не уверены, использовать Component или FlowModel? — см. Component vs FlowModel

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