Перейти к основному содержимому

Файл (File)

Поле типа Файл позволяет загружать и хранить один файл любого типа.

Основные характеристики​

  • Количество файлов: Один файл
  • Максимальный размер: Настраивается (по умолчанию 10 МБ)
  • Типы файлов: Любые (с возможностью ограничения)
  • Хранение: В интегрированном хранилище EMD Cloud
  • CDN: Автоматическая доставка через CDN

Поддерживаемые типы файлов​

Изображения​

  • JPG, JPEG, PNG, GIF, WebP, SVG
  • Автоматическая генерация превью
  • Поддержка изменения размера

Документы​

  • PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX
  • TXT, CSV, MD

Архивы​

  • ZIP, RAR, 7Z, TAR, GZ

Медиа​

  • MP3, WAV, MP4, AVI, MOV

Другие​

  • Любые файлы по вашему выбору

Настройки поля​

При создании поля типа "Файл" доступны следующие настройки:

  • Название поля: Отображаемое имя поля
  • Системное имя: Уникальный идентификатор для API
  • Описание: Подсказка для пользователей
  • Обязательное поле: Требовать загрузки файла
  • Максимальный размер: Ограничение размера файла (в МБ)
  • Допустимые типы: Ограничение по типам файлов (MIME types)
  • Автоматическое превью: Генерировать превью для изображений

Примеры использования​

Аватар пользователя​

{
  "name": "avatar",
  "type": "file",
  "maxSize": 5,
  "allowedTypes": ["image/jpeg", "image/png", "image/webp"],
  "generateThumbnails": true
}

Документ​

{
  "name": "contract",
  "type": "file",
  "required": true,
  "allowedTypes": ["application/pdf"],
  "maxSize": 10
}

Логотип компании​

{
  "name": "logo",
  "type": "file",
  "allowedTypes": ["image/svg+xml", "image/png"],
  "maxSize": 2
}

Работа через API​

Загрузка файла​

// Загрузка из формы
const formData = new FormData();
formData.append('file', fileInput.files[0]);

const uploadedFile = await emd.storage.upload(formData);

// Создание записи с файлом
const record = await emd.database.collection('users').create({
  name: 'Иван Иванов',
  avatar: uploadedFile.id
});

Загрузка с созданием записи (одним запросом)​

const formData = new FormData();
formData.append('name', 'Иван Иванов');
formData.append('avatar', fileInput.files[0]);

const record = await emd.database.collection('users').create(formData);

Получение информации о файле​

const record = await emd.database.collection('users').get(recordId);

console.log(record.avatar);
// {
//   id: "file_123",
//   name: "avatar.jpg",
//   size: 245678,
//   mimeType: "image/jpeg",
//   url: "https://cdn.emd.one/files/file_123.jpg",
//   thumbnails: {
//     small: "https://cdn.emd.one/files/file_123_small.jpg",
//     medium: "https://cdn.emd.one/files/file_123_medium.jpg",
//     large: "https://cdn.emd.one/files/file_123_large.jpg"
//   }
// }

Получение URL файла​

const record = await emd.database.collection('users').get(recordId);
const fileUrl = record.avatar.url;

// Использование в HTML
const img = document.createElement('img');
img.src = fileUrl;

Обновление файла​

const formData = new FormData();
formData.append('file', newFileInput.files[0]);

const newFile = await emd.storage.upload(formData);

await emd.database.collection('users').update(recordId, {
  avatar: newFile.id
});

Удаление файла​

// Удалить только ссылку на файл (файл останется в хранилище)
await emd.database.collection('users').update(recordId, {
  avatar: null
});

// Удалить файл из хранилища
const record = await emd.database.collection('users').get(recordId);
await emd.storage.delete(record.avatar.id);
await emd.database.collection('users').update(recordId, {
  avatar: null
});

Работа с изображениями​

Автоматические превью​

Для изображений автоматически генерируются превью разных размеров:

const record = await emd.database.collection('products').get(recordId);

// Оригинал
const original = record.image.url;

// Превью
const small = record.image.thumbnails.small;    // 150x150
const medium = record.image.thumbnails.medium;  // 300x300
const large = record.image.thumbnails.large;    // 600x600

Изменение размера на лету​

// Получить изображение определенного размера
const resizedUrl = emd.storage.getResizedUrl(record.image.id, {
  width: 400,
  height: 300,
  fit: 'cover' // или 'contain', 'fill'
});

Оптимизация изображений​

// Автоматическая оптимизация при загрузке
const uploadedFile = await emd.storage.upload(formData, {
  optimize: true,
  quality: 85,
  format: 'webp' // конвертировать в WebP
});

Метаданные файла​

Каждый файл содержит следующие метаданные:

{
  id: "file_123",
  name: "document.pdf",
  originalName: "Договор №123.pdf",
  size: 1245678,              // в байтах
  mimeType: "application/pdf",
  url: "https://cdn.emd.one/files/file_123.pdf",
  uploadedAt: "2025-11-25T10:30:00Z",
  uploadedBy: "user_456",
  metadata: {
    width: 1920,              // для изображений
    height: 1080,             // для изображений
    duration: 180             // для видео/аудио (в секундах)
  }
}

Валидация файлов​

Ограничение по размеру​

{
  "name": "avatar",
  "type": "file",
  "maxSize": 5  // МБ
}

Ограничение по типу​

{
  "name": "document",
  "type": "file",
  "allowedTypes": [
    "application/pdf",
    "application/msword",
    "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
  ]
}

Ограничение по расширению​

{
  "name": "image",
  "type": "file",
  "allowedExtensions": ["jpg", "jpeg", "png", "webp"]
}

Безопасность​

Приватные файлы​

// Загрузка приватного файла (требует авторизации для доступа)
const uploadedFile = await emd.storage.upload(formData, {
  private: true
});

// Получение временной ссылки на приватный файл
const temporaryUrl = await emd.storage.getTemporaryUrl(fileId, {
  expiresIn: 3600 // секунды
});

Проверка вирусов​

// Автоматическая проверка при загрузке (если включено)
const uploadedFile = await emd.storage.upload(formData, {
  scanVirus: true
});

Отображение в интерфейсе​

Превью изображений​

Изображения автоматически отображаются с превью в таблицах и формах.

Иконки файлов​

Для других типов файлов отображаются соответствующие иконки (PDF, DOC, ZIP и т.д.).

Прогресс загрузки​

const uploadedFile = await emd.storage.upload(formData, {
  onProgress: (progress) => {
    console.log(`Загружено: ${progress}%`);
  }
});

Рекомендации​

  • Используйте тип Файл для одиночных файлов
  • Для множественных файлов используйте тип Файлы
  • Устанавливайте разумные ограничения по размеру
  • Ограничивайте типы файлов для безопасности
  • Используйте WebP для изображений (меньший размер)
  • Включайте автоматическую оптимизацию изображений
  • Для приватных данных используйте приватные файлы
  • Регулярно очищайте неиспользуемые файлы

Ограничения​

  • Один файл на поле
  • Максимальный размер зависит от тарифа
  • Некоторые типы файлов могут быть заблокированы по соображениям безопасности

Отличие от других типов​

  • File vs Files: File для одного файла, Files для множественных
  • File vs String: File для бинарных данных, String для текста
  • File vs JSON: File для файлов, JSON для структурированных данных