React - популярный фреймворк для создания интерактивных пользовательских интерфейсов. Он помог совершить революцию в разработке фронтенд-приложений с большим объемом данных.
Декларативная природа React делает создание пользовательских интерфейсов интуитивно понятным. А многократно используемые компоненты React повышают скорость разработки и сокращают время выпуска продукции.
Для дальнейшего улучшения опыта разработки при создании пользовательских интерфейсов появилось несколько фреймворков React. Одним из таких фреймворков является refine.
refine - это основанный на React фреймворк для создания веб-приложений. Он похож на React-admin, Redwood и Retool.
Экосистема refine поставляется с готовыми интеграциями для аутентификации пользователей, маршрутизации, сетевого взаимодействия, интернализации и многого другого.
В этой статье вы изучите refine, создав простую панель администратора. Это поможет выделить основные строительные блоки фреймворка refine. Мы также рассмотрим основные возможности и возможные сценарии использования refine.
Оглавление
Что такое Refine?
Refine - это фреймворк на основе React с открытым исходным кодом и лицензией MIT для создания front-end приложений. Он похож на React-admin, Retool и Redwood. Refine - это ”безголовый” фреймворк React. Он не принимает во внимание ваши решения по стилизации и дизайну.
Это означает, что вы можете использовать refine с пользовательским дизайном или библиотекой компонентов пользовательского интерфейса. Он поставляется с интеграциями для самых популярных библиотек компонентов и систем дизайна, таких как Material UI, Chakra UI и Ant design.
refine имеет встроенные провайдеры маршрутизации для самых популярных библиотек маршрутизации, таких как React Router, Remix Router, Next.js Router и React Location. Вы можете выбрать библиотеку маршрутизации, которая отвечает требованиям вашего проекта.
Вы можете использовать refine для создания приложений с интенсивным использованием данных, таких как панели администратора, приборные панели, внутренние инструменты и витрины магазинов. Инструмент командной строки, который является частью экосистемы React, поможет вам быстро настроить приложение refine.
Вы сможете быстро приступить к работе, если у вас есть начальные или средние знания React, поскольку refine - это фреймворк на основе React. Вы также можете использовать refine с другими фреймворками React, такими как Next и Remix.
Для выполнения некоторых примеров в этой статье вам понадобятся следующие инструменты.
Среда выполнения Node
Если у вас нет Node, загрузите и установите его со страницы загрузки Node. После установки выполните приведенную ниже команду в командной строке, чтобы проверить, успешно ли прошла установка.
node -v
Команда выше отобразит версию Node на вашей машине, если установка прошла успешно.
Последние версии Node также поставляются с npm. Выполните приведенную ниже команду в терминале, чтобы убедиться, что у вас есть npm. Она должна отобразить версию npm, которую вы установили вместе с Node.
npm -v
Текстовый редактор
Вам понадобится текстовый редактор, например VS Code или Sublime Text. Мне больше всего нравится VS Code. Вы можете загрузить его со страницы загрузки VS Code. Или же загрузите Sublime Text для вашей системы со страницы загрузок Sublime Text.
Как настроить Refine Приложение
Вы можете создать собственное приложение refine или использовать утилиту командной строки refine для быстрой загрузки приложения refine. Если вы только начинаете, я рекомендую вам использовать утилиту командной строки refine для быстрой настройки проекта.
Утилита командной строки создаст проект refine со всеми необходимыми конфигурациями. Выполните следующие шаги, чтобы создать простой проект refine с помощью инструмента командной строки. Для выполнения описанных ниже шагов у вас должны быть инструменты разработки, о которых я рассказывал в предыдущем разделе.
Шаг 1 - Создание приложения для уточнения
Перейдите в каталог, где вы хотите создать приложение refine, и выполните приведенную ниже команду в командной строке. Я использую npm в качестве менеджера пакетов. Но вы можете использовать и другой менеджер пакетов.
Также обратите внимание, что если вы впервые создаете проект refine, команда ниже предложит вам установить пакет create-refine-app.
npm create refine-app@latestПриведенная выше команда запустит процесс установки. Во время установки отвечайте на подсказки. Я выбрал шаблон проекта refine-react, интеграцию RESTful back-end и Material UI в качестве фреймворка пользовательского интерфейса для этого проекта.
Вы заметите, что я отказался от других конфигураций установки.
✔ Downloaded remote source successfully.
✔ Choose a project template · refine-react
✔ What would you like to name your project?: · refine-demo
✔ Choose your backend service to connect: · data-provider-custom-json-rest
✔ Do you want to use a UI Framework?: · mui
✔ Do you want to add example pages?: · no
✔ Do you want to add dark mode support?: · no
✔ Do you want to customize the Material UI theme?: · no
✔ Do you want to customize the Material UI layout?: · no
✔ Do you need any Authentication logic?: · none
✔ Do you need i18n (Internationalization) support?: · no
✔ Do you want to add kbar command interface support?: · no
✔ Choose a package manager: · npm
✔ Would you mind sending us your choices so that we can improve superplate? · no
Шаг 2 - Откройте проект в текстовом редакторе
После завершения установки откройте каталог проекта в текстовом редакторе. Если вы используете VS Code, используйте команду code global с именем каталога проекта, чтобы открыть каталог проекта в VS Code.
Команда ниже предполагает, что имя каталога вашего проекта - refine-demo.
code refine-demo
Шаг 3 - Запуск сервера разработки
Вы можете запустить сервер разработки, выполнив приведенную ниже команду в командной строке.
npm run dev
Приведенная выше команда запустит сервер разработки для вашего проекта refine в браузере по умолчанию на localhost, порт 3000. Приветственная страница должна выглядеть так, как показано на скриншоте ниже:
Основные концепции в refine
При работе с refine вы столкнетесь с несколькими, возможно, незнакомыми понятиями. Ниже приведены объяснения некоторых из этих распространенных понятий, с которыми вы можете столкнуться.
Поставщики данных
Чаще всего при создании фронтенд-приложений с интенсивным использованием данных на React вам приходится взаимодействовать с API. В отличие от React, refine абстрагирует HTTP-запросы к API в провайдерах данных.
Провайдер данных выполняет сетевые запросы к API и пересылает ответ компоненту, которому он нужен.
В экосистеме refine есть провайдеры данных для REST API, GraphQL API, облачных баз данных, таких как Firebase, и некоторых популярных безголовых систем управления контентом, таких как Strapi.
Вы можете объявить собственный провайдер данных, если не собираетесь использовать провайдеров данных из экосистемы refine. Провайдер данных refine должен обладать приведенными ниже формой и методами.
const dataProvider = {
create: ({ resource, variables, metaData }) => Promise,
createMany: ({ resource, variables, metaData }) => Promise,
deleteOne: ({ resource, id, variables, metaData }) => Promise,
deleteMany: ({ resource, ids, variables, metaData }) => Promise,
getList: ({
resource,
pagination,
hasPagination,
sort,
filters,
metaData,
}) => Promise,
getMany: ({ resource, ids, metaData }) => Promise,
getOne: ({ resource, id, metaData }) => Promise,
update: ({ resource, id, variables, metaData }) => Promise,
updateMany: ({ resource, ids, variables, metaData }) => Promise,
custom: ({
url,
method,
sort,
filters,
payload,
query,
headers,
metaData,
}) => Promise,
getApiUrl: () => "",
};
Имена методов в провайдере данных не требуют пояснений. Метод create создает элемент в ресурсе, как следует из его названия, и возвращает обещание. Он принимает несколько параметров. Названия других методов также не требуют пояснений.
Ваше приложение refine взаимодействует с поставщиками данных с помощью крючков данных. Чтобы выполнить операцию CRUD, вы можете вызвать методы поставщика данных с помощью крючков данных.
Data hooks
Как указывалось выше, вы можете вызвать любой из методов поставщика данных из компонента с помощью крючков данных. Каждый метод в провайдере данных имеет соответствующий крючок данных. Например, хук useCreate вызывает метод create в вашем провайдере данных.
Вы можете использовать хук useCreate в своем компоненте следующим образом:
import { useCreate } from "@pankod/refine-core";
const MyComponent = () => {
const { mutate } = useCreate();
const clickHandler = () => {
mutate({ resource: "posts", values: { title: "Refine hello world!" } });
};
return <button onClick={clickHandler}>Click to Create an item</button>;
};
Хотя хук useCreate возвращает объект с несколькими свойствами, в приведенном выше примере нас интересует функция mutate.
Вызов функции mutate, как мы это сделали, запускает метод create в вашем поставщике данных. После этого метод create выполняет сетевой запрос к вашему API и передает ответ вашему компоненту.
Существует несколько крючков данных, которые вы можете найти в документации Refine.
Ресурсы
Как было сказано выше, работа с API неизбежна при создании внешних приложений. API обычно состоит из ресурсов, к которым вы можете получить доступ через конечные точки и выполнить CRUD-операции.
Компонент Refine является точкой входа для любого приложения Refine. Когда вы создаете любое приложение Refine с помощью create-refine-app, в компоненте App.tsx всегда будет отображаться компонент Refine, как показано в примере ниже.
function App() {
return (
<Refine
dataProvider={dataProvider(apiUrl)}
routerProvider={routerProvider}
resources={[
{
name: "users",
list: List,
show: Show,
create: Create,
edit: Edit,
},
]}
/>
);
}
Одним из реквизитов, которые вы передаете компонентуRefine, является реквизит resources. Значение реквизита resources - это массив объектов ресурсов. Каждый объект ресурса должен иметь свойство name.
Как и в примере выше, вы можете передать дополнительные свойства, такие как list, show, create и edit.
Значения list, show, create и edit являются компонентами. В приведенном выше примере значение поля name - “users”.
Поле name определяет маршруты в вашем внешнем приложении. Когда вы перейдете к маршруту /users в вашем приложении, refine отобразит компонент List.
Аналогично, при переходе к маршруту /users/show refine отобразит компонент Show. В таблице ниже приведена связь между полями вышеупомянутого объекта ресурса и маршрутами в вашем приложении.
| Resource object property | Route | Rendered component |
list | /users | List |
show | /users/show | Show |
create | /users/create | Create |
edit | /users/edit | Edit |
Вместо того чтобы создавать компоненты с нуля, вы также можете генерировать их на основе ваших ресурсов с помощью Inferencer.
Inferencer
Inferencer - один из пакетов в экосистеме пакетов refine. Он увеличивает скорость разработки, генерируя страницы CRUD после анализа вашей модели данных. Затем вы можете настроить автоматически генерируемые компоненты в соответствии с требованиями вашего проекта.
Вместо того чтобы задавать значения свойств объектов ресурсов list, show, create и edit для пользовательского компонента, как в предыдущем подразделе, инференсер может генерировать компоненты за вас. Затем вы можете настроить компоненты в соответствии со своими потребностями.
import { HeadlessInferencer } from "@pankod/refine-inferencer/headless";
function App() {
return (
<Refine
dataProvider={dataProvider(apiUrl)}
routerProvider={routerProvider}
resources={[
{
name: "topics",
list: HeadlessInferencer,
show: HeadlessInferencer,
create: HeadlessInferencer,
edit: HeadlessInferencer,
},
]}
/>
);
}
Приведенный выше код предполагает, что вы используете HeadlessInferencer. Вы также можете использовать MuiInferencer, если вы используете Material UI.
Inferencer полагается на пакеты @pankod/refine-react-hook-form и @pankod/refine-react-table для генерации форм и таблиц. Поэтому не забудьте установить их.
npm i @pankod/refine-react-table @pankod/refine-react-hook-form
Как построить панель администратора с помощью refine
В этом разделе вы создадите простую панель администратора, модифицировав приложение refine, которое вы создали выше.
Помните, что при загрузке приложения с помощью create-refine-app мы выбрали интеграцию с RESTful API back-end. Поэтому для этой иллюстрации мы будем использовать ненастоящий RESTful API.
В реальном приложении вы будете работать с другой внутренней интеграцией. Это может быть RESTful API, GraphQL API, облачные базы данных, например Firebase, или система управления контентом, например Strapi.
Вам необходимо прочитать документацию refine по использованию различных внутренних интеграций, доступных в экосистеме refine.
Поддельный RESTful API имеет несколько конечных точек для доступа к доступным ресурсам. Мы создадим панель администратора для ресурса пользователей. Выполните следующие шаги, если вы открыли в текстовом редакторе проект refine, который мы создали в начале этой статьи.
Шаг 1 - Установка зависимостей Inferencer
Мы будем использовать MuiInferencer для генерации страниц CRUD. Инференсер внутренне опирается на пакеты @pankod/refine-react-hook-form и @pankod/refine-react-table. Выполните приведенную ниже команду в терминале, чтобы установить их.
npm i @pankod/refine-react-table @pankod/refine-react-hook-form
Шаг 2 - Импорт MuiInferencer
После успешной установки необходимых зависимостей откройте файл src/App.tsx и добавьте следующий оператор import в верхней части:
import { MuiInferencer } from "@pankod/refine-inferencer/mui";
Шаг 3 - Генерация компонентов с помощью Inferencer
Как объясняется в разделе ”Основные понятия”, значения свойств list, show, create и edit объекта ресурса являются компонентами. Вы можете создать эти компоненты с нуля или сгенерировать их с помощью Inferencer. В этом примере мы будем использовать MuiInferencer для их создания.
В файле src/App.tsx компонент App отображает встроенный компонент Refine. Refine - это точка входа для любого приложения Refine. Добавьте свойство resources к компоненту Refine, чтобы компонент App выглядел следующим образом:
function App() {
return (
<ThemeProvider theme={LightTheme}>
<CssBaseline />
<GlobalStyles styles={{ html: { WebkitFontSmoothing: "auto" } }} />
<RefineSnackbarProvider>
<Refine
dataProvider={dataProvider("https://api.fake-rest.refine.dev")}
notificationProvider={notificationProvider}
Layout={Layout}
ReadyPage={ReadyPage}
catchAll={<ErrorComponent />}
routerProvider={routerProvider}
resources = {[
{
name: 'users',
list: MuiInferencer,
show: MuiInferencer,
create: MuiInferencer,
edit: MuiInferencer
}
]}
/>
</RefineSnackbarProvider>
</ThemeProvider>
);
}
}
Шаг 4 - Предварительный просмотр изменений
Просмотр списка пользователей
После сохранения вышеуказанных изменений refine создаст CRUD-страницы и перенаправит их на маршрут /users. Ваша страница приветствия должна выглядеть как показано на рисунке ниже. Компонент, сгенерированный Inferencer, отображает таблицу пользователей из ресурса users.
Таблица имеет несколько столбцов, некоторые из которых скрыты от глаз, если вы используете маленький экран. Чтобы увидеть их все, прокрутите страницу по горизонтали.
Создание нового пользователя
Вы также можете перейти к маршруту users/create для создания нового пользователя, нажав кнопку “CREATE”. refine отобразит компонент, созданный Inferencer. В нем есть форма для создания нового пользователя, которая выглядит как показано на рисунке ниже.
Обновление существующего пользователя
Чтобы обновить существующий ресурс, перейдите к маршруту /users/edit/:id. Параметр маршрута id должен быть идентификатором объекта в ресурсе users.
Чтобы отредактировать данные пользователя, чей id равен 1, перейдите к конечной точке /users/edit/1, нажав на кнопку редактирования первой записи в таблице пользователей.
Кнопка редактирования находится под последней колонкой с надписью ”Действия”. Страница редактирования должна выглядеть так, как показано на рисунке ниже.
Просмотр конкретного пользователя
Для просмотра сведений о пользователе с определенным идентификатором перейдите по маршруту /users/show/:id. В качестве id должен быть указан существующий объект в ресурсе users.
Чтобы просмотреть сведения о первом пользователе, нажмите кнопку show первой записи в таблице users. Кнопка show находится под последней колонкой с надписью “Actions”.
Когда вы перейдете к конечной точке /users/show/1, вы должны увидеть подробную информацию о первом пользователе, чей id равен 1.
Шаг 5 - Просмотр кода, сгенерированного Inferencer
Inferencer создал для нас компоненты, используя ответ от конечной точки /users нашего поддельного RESTful API. На каждой из страниц, которые вы посетили выше, в правом нижнем углу есть кнопка с надписью “SHOW CODE”.
Нажмите ее, чтобы отобразить код, сгенерированный Inferencer для каждой страницы.
Шаг 6 - Настройка сгенерированных компонентов
В предыдущих шагах вы создали CRUD-страницы с помощью MuiInferencer. Использование MuiInferencer поможет вам начать работу, сгенерировав шаблонный код. Но в реальном приложении вы почти всегда захотите настроить компоненты под свои нужды.
Чтобы настроить сгенерированный код, создайте каталог src/users. В каталоге src/users создайте четыре файла со следующими именами. Вы можете назвать их по-другому, если хотите.
List.tsxCreate.tsxEdit.tsxShow.tsx
В предыдущем шаге вы узнали, как просмотреть сгенерированный код для каждой страницы.
Скопируйте и вставьте код для страницы /users в созданный вами файл List.tsx. Таким же образом скопируйте и вставьте код для страницы /users/create в файл Create.tsx. То же самое проделайте для других страниц и соответствующих им компонентов.
Импортируйте компоненты, которые вы создали выше, в файл App.tsx следующим образом:
import { UserList } from "users/List";
import { UserCreate } from "users/Create";
import { UserShow } from "users/Show";
import { UserEdit } from "users/Edit";
В файле App.tsx компонент App отображает встроенный компонент Refine. Измените реквизит resources, который вы передаете компоненту Refine, так, чтобы он выглядел следующим образом:
<Refine
...
resources={[
{
name: "users",
list: UserList,
show: UserShow,
create: UserCreate,
edit: UserEdit,
},
]}
/>;
Надеюсь, вы заметили, что значения свойств list, show, create и edit объекта ресурса изменились с MuiInferencer на UserList, UserShow, UserCreate и UserEdit соответственно. Теперь вы можете изменять код в созданных вами компонентах.
Вот так просто можно создавать приборные панели и панели администратора с помощью refine.
В течение нескольких минут вы создали шаблон проекта на основе вашей модели данных. Затем вы можете его доработать. Создание такого проекта с нуля потребовало бы много работы.
Заключение
Refine - это фреймворк на основе React с открытым исходным кодом и лицензией MIT для создания внешних приложений. Он пригодится при создании приборных панелей, панелей администратора, внутренних инструментов и витрин магазинов. Вы можете использовать его практически в любом приложении, использующем React.
refine поставляется с готовыми функциями для работы в сети, аутентификации, маршрутизации и интернационализации. Он также имеет интеграции для самых популярных облачных баз данных, таких как Firebase и Supabase, и систем управления контентом, таких как Strapi.
Если вы хотите начать использовать refine, воспользуйтесь инструментом командной строки. С помощью инструмента командной строки вы можете выбрать безголовую настройку или использовать один из встроенных компонентов или систем дизайна, таких как Material UI и Ant design.
Надеюсь, эта статья познакомила вас с самыми основами refine. У refine есть еще несколько функций и вариантов использования, которые я не осветил здесь. Ознакомьтесь с документацией, чтобы полностью понять refine и его возможности.