docs: clarify file upload example with _payload & field explanation (#12025)

### What?

This PR updates the `Uploading Files` section in the `Uploads` docs to:

- Use `_payload` in the file upload example, which is required for
non-file fields to be parsed correctly by Payload.
- Add a clear comment explaining that the fields inside `_payload`
should match the schema of the upload-enabled collection.

### Why?

These changes aim to reduce confusion when uploading files via the REST
API.

Fixes #11681
This commit is contained in:
Patrik
2025-04-07 14:06:03 -04:00
committed by GitHub
parent 77210251f4
commit 83319be752
2 changed files with 17 additions and 2 deletions

View File

@@ -21,10 +21,9 @@ When a user starts editing a document, Payload locks it for that user. If anothe
The lock will automatically expire after a set period of inactivity, configurable using the `duration` property in the `lockDocuments` configuration, after which others can resume editing.
<Banner type="info">
{' '}
**Note:** If your application does not require document locking, you can
disable this feature for any collection or global by setting the
`lockDocuments` property to `false`.{' '}
`lockDocuments` property to `false`.
</Banner>
### Config Options

View File

@@ -334,12 +334,28 @@ To upload a file, use your collection's [`create`](/docs/rest-api/overview#colle
Send your request as a `multipart/form-data` request, using [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) if possible.
<Banner type="info">
**Note:** To include any additional fields (like `title`, `alt`, etc.), append
a `_payload` field containing a JSON-stringified object of the required
values. These values must match the schema of your upload-enabled collection.
</Banner>
```ts
const fileInput = document.querySelector('#your-file-input')
const formData = new FormData()
formData.append('file', fileInput.files[0])
// Replace with the fields defined in your upload-enabled collection.
// The example below includes an optional field like 'title'.
formData.append(
'_payload',
JSON.stringify({
title: 'Example Title',
description: 'An optional description for the file',
}),
)
fetch('api/:upload-slug', {
method: 'POST',
body: formData,