Appearance

Разработка расширений для NextBox ​

Этот гайдлайн описывает полный цикл создания расширений для платформы NextBox: от выбора типа расширения и шаблона проекта до сборки, упаковки и публикации

Содержание ​

  • Что такое расширения NextBox
  • Зачем использовать расширения
  • Типы расширений: File, WorkDir, App
  • Выбор стартового шаблона
  • Минимальный пример (React + NextBox APIs)
  • Конфигурация config.json
  • Примеры config.json для разных типов
  • Публикация приложения

Что такое расширения NextBox ​

Расширения — это встраиваемые веб‑приложения, работающие внутри платформы NextBox. Они позволяют:

  • Открывать и интерпретировать файлы (PDF, PSD и т.д.);
  • Редактировать данные в конкретном файле или целые директории;
  • Встраиваться в боковое меню платформы; в случае типа App для быстрого единоличного использования.

Зачем использовать расширения ​

  • Персонализация под процессы: добавляйте специфичные инструменты (просмотрщики, редакторы, дашборды).
  • Единое рабочее место: пользователи работают в NextBox, не переключаясь между множеством сервисов.
  • Контроль данных и безопасности: логика выполняется внутри периметра платформы; доступы наследуются от NextBox.
  • Автоматизация и экономия времени: типовые операции (просмотр/редактирование/генерация) выполняются прямо в интерфейсе.
  • Интеграции: расширения типа App позволяют подключать внешние сервисы (через прокси/настройки), сохраняя единый UX.
  • Совместная работа: общий доступ к файлам/папкам + доменные инструменты внутри NextBox упрощают коллаборацию.

Типы расширений: File, WorkDir, App ​

File ​

  • Для работы с отдельным файлом: чтение/запись/совместно.
  • В config.json задаются поддерживаемые расширения (file.ext) и режим (file.mode).
  • Пример назначения: просмотрщик .pdf, .psd, .csv и т.д.

Пример фрагмента настройки:

json
{
  "type": "file",
  "file": {
    "mode": "read_and_write",
    "ext": [".html", ".htmlx"],
    "index": "index.html"
  }
}

WorkDir ​

  • Для работы с целой директорией (структура + содержимое).
  • По умолчанию предполагает чтение и редактирование.
  • Пример назначения: канбан‑доски, wiki‑документация, проекты со множеством файлов.

App ​

  • Не связан с файловым хранилищем: размещается в общем меню вне редактора.
  • Нельзя расшарить внешним пользователям напрямую.
  • Может работать с внутренним API платформы и внешними сервисами (через HTTP Proxy и др.).

Выбор стартового шаблона ​

Рекомендуется начинать с официального шаблона:

  • NextBox Extension React Template (Vite + React 18 + TypeScript + SWC + NextBox APIs)
    • Клонирование:
      bash
      git clone https://github.com/next-box-repo/ext-template-file.git
cd ext-template-file
npm i   # или bun i
npm run dev   # или bun run dev
    • Сборка:
      bash
      npm run build   # или bun run build

Альтернатива - в качестве альтернативы можно использовать и другие framework (Angular, jQuery и т.д.)

Минимальный пример (React + NextBox APIs) ​

Ниже приведён минимальный пример интеграции с платформой для типа File (просмотр .obj через react-3d-viewer). Для Vite/CRA код может отличаться путями импорта, но суть одинакова:

js
import React from 'react';
import ReactDOM from 'react-dom/client';
import { OBJModel } from 'react-3d-viewer';
import { NextBox, StorageApi } from 'next-box';

const nextBox = new NextBox();
const storageApi = new StorageApi();

nextBox.init((state) => {
  storageApi.changeState(state); // важно: инициализация контекста хранилища

  const root = ReactDOM.createRoot(document.getElementById('root'));
  root.render(
    <React.StrictMode>
      <OBJModel
        position={{ x: 0, y: -100, z: 0 }}
        src={storageApi.makeDownloadPath(state.storage.path)}
        width={document.body.offsetWidth}
        height={document.body.offsetHeight}
      />
    </React.StrictMode>
  );
});

Ключевые моменты:

  • new NextBox() — инициализация хелперов платформы;
  • new StorageApi() — доступ к функциям работы с файлами;
  • nextBox.init(cb) — сигнал платформе, что приложение готово; в state приходит контекст файла/расширения/хоста;
  • storageApi.changeState(state) — обязательный шаг для корректной работы методов StorageApi;
  • storageApi.makeDownloadPath(state.storage.path) — формирует прямую ссылку на текущий файл.

Стиль контейнера:

css
body { margin: 0; }
#root { min-height: 100vh; min-width: 100vw; }

Конфигурация config.json ​

Файл config.json описывает интеграцию расширения с платформой.

Рекомендуемая структура (поместить в публичные ассеты проекта, например public/config.json):

json
{
  "$schema": "https://next-box.ru/static/schemes/extension.json",
  "version": "1.0.0",
  "uniq_key": "react-app",
  "name": { "ru": "3D viewer" },
  "description": { "ru": "Просмотр 3D моделей .gltf, .obj и др." },
  "type": "file",
  "icon": "icon.svg",
  "file": {
    "mode": "read",
    "ext": [".gltf", ".dae", ".obj"],
    "index": "index.html"
  }
}

Пояснения по ключам:

  • $schema — опционально; описывает схему и включает автодополнение в IDE;
  • version — версия расширения; платформа не установит версию ниже или равную уже установленной;
  • uniq_key — уникальный ключ в латинице в рамках платформы/магазина;
  • name — объект локализаций; name.ru обязателен, остальные по необходимости;
  • description — аналогично name, но для описания;
  • type — file | work_dir | app;
  • icon — относительный путь к иконке из финальной сборки (рекомендуется SVG 48×64 px);
  • file — настройки для типа file:
    • mode: read | write | read_and_write;
    • ext: список поддерживаемых расширений файлов;
    • index: точка входа (файл, загружаемый в iframe).

Примеры config.json для разных типов ​

Ниже — реальные варианты конфигураций для всех типов расширений, иллюстрирующие полезные поля.

File (просмотр PDF, режим read) ​

Ключевые моменты: type: file, список расширений, режим read, локализации, теги, readme_path.

json
{
  "version": "1.4.16",
  "uniq_key": "pdf",
  "icon": "icon.svg",
  "type": "file",
  "name": { "ru": "PDF", "en": "PDF" },
  "tags": ["просмотр"],
  "description": {
    "ru": "PDF - инструмент для просмотра файлов в формате .pdf",
    "en": "PDF is a tool for viewing files in .pdf format"
  },
  "file": {
    "mode": "read",
    "ext": [".pdf"],
    "index": "index.html"
  },
  "readme_path": { "en": "readme_en.md", "ru": "readme.md" }
}

File (редактор Gantt, режим read_and_write) ​

Особенности: default_ext для меню «создать файл», режим редактирования.

json
{
  "version": "1.2.1",
  "uniq_key": "gantt",
  "name": { "ru": "Gantt", "en": "Gantt" },
  "tags": ["управление"],
  "description": {
    "ru": "Gantt — инструмент для управления проектами, задачами и ресурсами",
    "en": "Gantt is a tool for managing projects, tasks, and resources"
  },
  "type": "file",
  "icon": "icon.svg",
  "file": {
    "mode": "read_and_write",
    "default_ext": ".gantt",
    "ext": [".gantt"],
    "index": "index.html"
  },
  "readme_path": { "en": "readme_en.md", "ru": "readme.md" }
}

WorkDir (Wiki, работа с директорией) ​

json
{
  "$schema": "https://next-box.ru/static/schemes/extension.json",
  "version": "1.4.27",
  "uniq_key": "wiki",
  "name": { "ru": "Wiki", "en": "Wiki" },
  "tags": ["документы"],
  "description": {
    "ru": "Wiki — инструмент для ведения базы знаний с улучшением текста через ИИ",
    "en": "Wiki is a tool for maintaining a knowledge base with text improvement through AI"
  },
  "type": "work_dir",
  "icon": "icon.svg",
  "work_dir": {
    "mode": "read_and_write",
    "ext": [".wiki"],
    "index": "index.html"
  },
  "readme_path": { "en": "readme_en.md", "ru": "readme.md" }
}

App (отдельное приложение в меню) ​

Особенности: секция app.menu — иконка и локализованная метка для бокового меню.

json
{
  "version": "1.0.2",
  "uniq_key": "puzzles",
  "name": { "ru": "Пазлы", "en": "Puzzles" },
  "tags": ["приложения"],
  "description": {
    "ru": "Пазлы — расширение для сборки изображений из фрагментов",
    "en": "Puzzles — an extension for assembling images from fragments"
  },
  "type": "app",
  "icon": "icon.svg",
  "app": {
    "menu": {
      "index": "./index.html",
      "icon": "icon.svg",
      "label": { "ru": "Пазлы", "en": "Puzzles" }
    }
  },
  "readme_path": { "en": "readme_en.md", "ru": "readme.md" }
}

Иконка ​

Разместите icon.svg среди публичных ассетов и укажите путь в config.json (icon).

Публикация приложения ​

Свяжитесь с нами, для того чтобы получить аккаунт разработчика - info@next-box.ru и узнать правила публикации расширения