Comprehensive Guide for Developers: UI & SDK Integration, Configuration, and API Reference
ReadonlyaccountEmits whenever the connection state changes (connect / disconnect).
Optional ReadonlyaccountStable id of the connected account, where the source has accounts at all — not the display label, which changes when the user renames their profile.
This is what scopes the recents history: an entry remembers the account it came from and is only listed while that same account is connected, so signing into a second OneDrive shows that account's history rather than another person's dead links. Leave unset for a source with no accounts (the device); it then matches only entries recorded the same way.
ReadonlyaccountDisplay label for the connected account, or null.
Optional ReadonlycanTrue when the source can be emptied (recents' "Clear all"). Read at render time, so it may reflect host config that arrived after construction; the bar then shows the action where a drive shows Disconnect.
Optional Readonlycanfalse for write-only targets (the device: a browser cannot enumerate it), which
are offered under "Save as" but never get a home-screen tab. Defaults to listable.
Optional Readonlycanfalse when getFileAsFile cannot deliver bytes — the device in a browser page,
where nothing on the machine is addressable. Read at render time, so it may reflect host
config that arrived later. What it gates is the history: an open is only worth recording
as a recent if the file can be loaded again. Defaults to readable.
Optional ReadonlycanReadonlyiconpwv-icon-* class for the tab and connect prompt. Empty when iconSvg carries the icon.
Optional ReadonlyiconSanitized inline <svg> markup, used instead of iconClass when set.
Only host-supplied custom clouds use this — built-ins have font glyphs.
ReadonlyidStable identifier, e.g. 'device' | 'onedrive' | 'googledrive'.
ReadonlyisTrue when a user account is currently connected. Always true for sticky sources.
ReadonlyisTrue when the host supplied this provider's config.
Optional ReadonlyisTrue when the source has no hierarchy (recents): listFolder ignores its argument and the bar shows no breadcrumb.
Optional ReadonlyisTrue for sources that are always present and have no sign-in flow (recents,
customProviders): never offered under + Connect, no Disconnect.
ReadonlynameDisplay name: a brand name, or an i18n key when translateName is set.
Optional Readonlysavei18n key explaining what choosing this target does, shown where a listable source would show its folders. Only meaningful for a write-only one.
Optional ReadonlytranslateTrue when name is an i18n key rather than a literal brand name.
OptionalcanWhether a new file ('file', an upload) or a new folder ('folder') may be put
into folder — the level on screen, null at the source's top. Asked per level,
so the bar can leave out an action that could only fail there.
Only a source with a level that is not an ordinary directory needs this.
NetExplorer's top level lists the account's root spaces, which the platform
hands out, so nothing can be created next to them; and the root of a space that
is not itself a folder takes a new folder (an administrator's "root folder") but
refuses a file outright — hence the kind, which a single flag could not express.
Omit it and every level of a writable source accepts both, which is what a drive with an ordinary root does.
OptionalclearEmpty the source. Only called when canClearAll is true.
Start the interactive sign-in flow. No-op for sticky sources.
OptionalcreateCreate an empty folder under parent (the source root when null), resolving the
folder that was created or null when it failed — the same convention as the save
methods, and a user cancel rejects with an AbortError just as they do.
Its presence, together with canSave, is what puts "Create folder" on the browser bar: a source that cannot make folders (or has none — see isFlat) simply omits it rather than showing a button that can only fail.
OptionaldisconnectDisconnect the local session (does not necessarily sign the user out globally). Its presence is what puts the Disconnect action on the source's browser bar — a source whose sign-out lives elsewhere (a connect-only custom source) omits it.
Lazily load the provider SDK and initialize. Returns false when disabled.
OptionalforgetDrop one entry from the listing without touching the file it points at (recents' per-row "Remove"). Its presence is what puts the row menu on the source's items.
Load a file's bytes as a File (reporting progress when it can), or null on failure.
When the source definitively reports the item gone — deleted, moved, no longer shared —
it rejects with a NotFoundError DOMException instead: that, and only that, is what
lets the recents history drop a dead row without dropping rows on transient failures.
OptionalonProgress: CloudDownloadProgressA displayable thumbnail URL for an item, or null when unavailable.
OptionalsaveWrite a new file into folder (the source root when null) — "Save as". Resolves the
item that was created, which is what the next "Save" then overwrites, or null when
the save failed; a user cancel rejects with an AbortError, same as saveOver —
as is the progress reporting — and claims, same as saveOver's. Set the item's
path when the source has a host-side one: that becomes the document's path.
OptionalsaveOverwrite the item the document was opened from ("Save"). Resolves the item as it now
stands — normally the one passed in — or null when the save failed, the same
convention as the read methods above. A user cancel (the device's save picker, a
host dialog) is not a failure and rejects with an AbortError instead: the caller
reports nothing and adopts nothing. onProgress reports the upload as it leaves,
same contract as getFileAsFile's — call it when the write is slow enough
to have a middle. claims carries the operations the saved contents went through
(sdk.IDocumentModel.listDocumentClaims); empty for a file with no document behind
it. Both are passed on every call — an implementation is free to declare neither.
A source of files the viewer can list and open: the host's recents, a host-owned cloud (
customProviders), or a built-in drive.The shared UI (FilesSectionTemplate) and mounting logic are driven entirely through this interface, so the sources live in one array and look the same on screen; a concrete provider only maps its own API onto IFileItem and declares its differences through the capability flags below. Every method must be defensive — failures resolve to
nullrather than throwing, so the UI can tell "failed" from "empty". The one deliberate exception: a user cancel inside a write rejects with anAbortError(see saveOver), so the UI can tell "chose not to" from "could not".