Files you choose lets a page that is on the screen open a file that the person chooses in the system panel, and save one file where the person chooses. The system panel is the question. The page gets only the file that the person chooses. A file is saved only at the place that the person chooses. The page never gets a path.
Declare files.choose in the manifest actions of the app. Without it, Access
shows no row, the file field does not open, and files.save returns
unauthorized. Access shows one row, Files you choose, under This computer.
The levels are Off and Allow, and the default is Allow. The row has no Ask level,
because the system panel is the question. The app can keep or send a file with
its other permissions, for example to the agent or by email.
Open a file
Use a normal file field. No SDK call is needed.
const input = document.createElement('input');
input.type = 'file';
input.addEventListener('change', async () => {
const text = await input.files[0].text();
// Use the text.
});
At Allow, the system panel opens when the person clicks the field. On the iPhone, iOS shows its own menu: Photo Library, Take Photo and Choose File. "Take Photo" uses the camera text of the iPhone app.
At Off, the file field does not open. A click, input.click() and
input.showPicker() do nothing (showPicker() throws NotAllowedError), and a
file that the person drops on the page is not given to the page. The title bar
shows "Files you choose is off for this app." with a link to Access.
A page that is not on the screen gets the same result as Off.
Redac also removes showOpenFilePicker, showSaveFilePicker and
showDirectoryPicker from the page. Use the file field and files.save.
Save one file
files.save({name, content, encoding, mimeType?}) returns {saved}.
| Argument | Rule |
|---|---|
name | 1 to 255 characters. No /, no \, no NUL character. Not . and not ... It is the default name. |
content | The file text or bytes. |
encoding | utf8 (at most 1,048,576 bytes as UTF-8) or base64 (at most 1,398,104 characters, 1 MiB of bytes). |
mimeType | Optional. At most 255 characters. It is a hint only. |
The system save panel opens with name as the default name. The person chooses
the place. The result is {saved: true} after the write, and {saved: false}
when the person cancels. The path is never returned. A second call from the same
page while a panel is open returns unavailable. A name or content that is not
valid returns invalid_args. A write that fails returns unavailable. At Off,
the call returns unauthorized.
const result = await client.cap.call('files.save', {
name: 'report.csv',
content: 'name,total\nTea,3\n',
encoding: 'utf8',
mimeType: 'text/csv',
});
if (!result.saved) {
// The person cancelled. Do not show an error.
}
Only a page on the screen can save. A function cannot use files.save. On the
iPhone, the phone answers the call itself and shows "Save to Files". A phone
page uses the same Access level that the desktop shows.
Downloads
A page cannot download a file. A link with download, a blob link and a
navigation to a file are blocked on both devices. Use files.save.
Limits
A page can change state in its own realm. A page that gets around the file guard still gets only the file that the person picks in the system panel. The guard protects the Off choice, not the file.