Пользовательское поле файла

Создайте поля для файлов, чтобы прикрепить документы, изображения и другие файлы к записям

Пользовательские поля файлов позволяют вам прикреплять несколько файлов к записям. Файлы хранятся безопасно в AWS S3 с полным отслеживанием метаданных, проверкой типа файла и соответствующими контролями доступа.

Простой пример

Создайте простое поле файла:

mutation CreateFileField {
  createCustomField(input: {
    name: "Attachments"
    type: FILE
  }) {
    id
    name
    type
  }
}

Расширенный пример

Создайте поле файла с описанием:

mutation CreateDetailedFileField {
  createCustomField(input: {
    name: "Project Documents"
    type: FILE
    description: "Upload project-related documents, images, and files"
  }) {
    id
    name
    type
    description
  }
}

Входные параметры

CreateCustomFieldInput

Параметр	Тип	Обязательный	Описание
`name`	String!	✅ Да	Отображаемое имя поля файла
`type`	CustomFieldType!	✅ Да	Должно быть `FILE`
`description`	String	Нет	Текст помощи, отображаемый пользователям

Примечание: Пользовательские поля автоматически ассоциируются с проектом на основе текущего контекста проекта пользователя. Параметр projectId не требуется.

Процесс загрузки файлов

Шаг 1: Загрузить файл

Сначала загрузите файл, чтобы получить UID файла:

mutation UploadFile {
  uploadFile(input: {
    file: $file  # File upload variable
    companyId: "company_123"
    projectId: "proj_123"
  }) {
    id
    uid
    name
    size
    type
    extension
    status
  }
}

Шаг 2: Присоединить файл к записи

Затем прикрепите загруженный файл к записи:

mutation AttachFileToRecord {
  createTodoCustomFieldFile(input: {
    todoId: "todo_123"
    customFieldId: "file_field_456"
    fileUid: "file_uid_from_upload"
  }) {
    id
    file {
      uid
      name
      size
      type
    }
  }
}

Управление вложениями файлов

Добавление одиночных файлов

mutation AddFileToField {
  createTodoCustomFieldFile(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    fileUid: "file_uid_789"
  }) {
    id
    position
    file {
      uid
      name
      size
      type
      extension
    }
  }
}

Удаление файлов

mutation RemoveFileFromField {
  deleteTodoCustomFieldFile(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    fileUid: "file_uid_789"
  })
}

Пакетные операции с файлами

Обновите несколько файлов одновременно, используя customFieldOptionIds:

mutation SetMultipleFiles {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    customFieldOptionIds: ["file_uid_1", "file_uid_2", "file_uid_3"]
  })
}

Входные параметры загрузки файла

UploadFileInput

Параметр	Тип	Обязательный	Описание
`file`	Upload!	✅ Да	Файл для загрузки
`companyId`	String!	✅ Да	Идентификатор компании для хранения файла
`projectId`	String	Нет	Идентификатор проекта для файлов, специфичных для проекта

Входные параметры управления файлами

Параметр	Тип	Обязательный	Описание
`todoId`	String!	✅ Да	Идентификатор записи
`customFieldId`	String!	✅ Да	Идентификатор пользовательского поля файла
`fileUid`	String!	✅ Да	Уникальный идентификатор загруженного файла

Хранение файлов и ограничения

Ограничения по размеру файла

Тип ограничения	Размер
Maximum file size	256MB per file
Batch upload limit	10 files max, 1GB total
GraphQL upload limit	256MB

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

Изображения

jpg, jpeg, png, gif, bmp, webp, svg, ico, tiff, tif

Видео

mp4, avi, mov, wmv, flv, webm, mkv, 3gp

Аудио

mp3, wav, flac, aac, ogg, wma

Документы

pdf, doc, docx, xls, xlsx, ppt, pptx, txt, rtf

Архивы

zip, rar, 7z, tar, gz

Код/Текст

json, xml, csv, md, yaml, yml

Архитектура хранения

Хранение: AWS S3 с организованной структурой папок
Формат пути: companies/{companySlug}/projects/{projectSlug}/uploads/{year}/{month}/{username}/{fileUid}_{filename}
Безопасность: Подписанные URL для безопасного доступа
Резервное копирование: Автоматическая избыточность S3

Поля ответа

Ответ файла

Поле	Тип	Описание
`id`	ID!	Идентификатор базы данных
`uid`	String!	Уникальный идентификатор файла
`name`	String!	Исходное имя файла
`size`	Float!	Размер файла в байтах
`type`	String!	MIME тип
`extension`	String!	Расширение файла
`status`	FileStatus	В ОЖИДАНИИ или ПОДТВЕРЖДЕНО (может быть null)
`shared`	Boolean!	Является ли файл общим
`createdAt`	DateTime!	Время загрузки

Ответ TodoCustomFieldFile

Поле	Тип	Описание
`id`	ID!	Идентификатор соединительной записи
`uid`	String!	Уникальный идентификатор
`position`	Float!	Порядок отображения
`file`	File!	Связанный объект файла
`todoCustomField`	TodoCustomField!	Родительское пользовательское поле
`createdAt`	DateTime!	Когда файл был прикреплен

Создание записей с файлами

При создании записей вы можете прикреплять файлы, используя их UID:

mutation CreateRecordWithFiles {
  createTodo(input: {
    title: "Project deliverables"
    todoListId: "list_123"
    customFields: [{
      customFieldId: "file_field_id"
      customFieldOptionIds: ["file_uid_1", "file_uid_2"]
    }]
  }) {
    id
    title
    customFields {
      id
      customField {
        name
        type
      }
      todoCustomFieldFiles {
        id
        position
        file {
          uid
          name
          size
          type
        }
      }
    }
  }
}

Проверка файлов и безопасность

Проверка загрузки

Проверка MIME типа: Проверяет разрешенные типы
Проверка расширения файла: Резервный вариант для application/octet-stream
Ограничения по размеру: Применяются во время загрузки
Санитация имени файла: Удаляет специальные символы

Контроль доступа

Разрешения на загрузку: Требуется членство в проекте/компании
Ассоциация файла: Роли ADMIN, OWNER, MEMBER, CLIENT
Доступ к файлу: Унаследован от разрешений проекта/компании
Безопасные URL: Подписанные URL с ограниченным временем доступа к файлу

Необходимые разрешения

Действие	Необходимое разрешение
Create file field	`OWNER` or `ADMIN` project-level role
Update file field	`OWNER` or `ADMIN` project-level role
Upload files	Project or company membership
Attach files	ADMIN, OWNER, MEMBER, or CLIENT role
View files	Standard record view permissions
Delete files	Same as attach permissions

Ответы на ошибки

Файл слишком большой

{
  "errors": [{
    "message": "File \"filename.pdf\": Size exceeds maximum limit of 256MB",
    "extensions": {
      "code": "BAD_USER_INPUT"
    }
  }]
}

Файл не найден

{
  "errors": [{
    "message": "File not found",
    "extensions": {
      "code": "FILE_NOT_FOUND"
    }
  }]
}

Поле не найдено

{
  "errors": [{
    "message": "Custom field not found",
    "extensions": {
      "code": "CUSTOM_FIELD_NOT_FOUND"
    }
  }]
}

Общие случаи использования

Управление документами
- Спецификации проекта
- Контракты и соглашения
- Записи встреч и презентации
- Техническая документация
Управление активами
- Дизайнерские файлы и макеты
- Брендовые активы и логотипы
- Маркетинговые материалы
- Изображения продуктов
Соответствие и записи
- Юридические документы
- Аудиторские следы
- Сертификаты и лицензии
- Финансовые записи
Сотрудничество
- Общие ресурсы
- Документы с контролем версий
- Обратная связь и аннотации
- Справочные материалы

Интеграционные функции

С автоматизацией

Запускайте действия, когда файлы добавляются/удаляются
Обрабатывайте файлы на основе типа или метаданных
Отправляйте уведомления о изменениях файлов
Архивируйте файлы на основе условий

С обложками изображений

Используйте поля файлов в качестве источников обложек
Автоматическая обработка изображений и миниатюр
Динамическое обновление обложек при изменении файлов

С поиском

Ссылайтесь на файлы из других записей
Суммируйте количество и размеры файлов
Находите записи по метаданным файлов
Перекрестная ссылка на вложения файлов

Ограничения

Максимум 256 МБ на файл
Зависит от доступности S3
Нет встроенного версионирования файлов
Нет автоматической конвертации файлов
Ограниченные возможности предварительного просмотра файлов
Нет совместного редактирования в реальном времени

Связанные ресурсы

API загрузки файлов - Конечные точки загрузки файлов
Обзор пользовательских полей - Общие концепции
API автоматизации - Автоматизация на основе файлов
Документация AWS S3 - Хранение данных