API reference
The api object
Everything a widget receives when it mounts, at a glance.
mount(el, api) receives the api object: everything a widget can read from EdgeStation and the machine, and the helpers that tie its timers and views to its lifetime. Its type is WidgetApi, from @edgestation/sdk.
export default {
mount(el, api) {
el.textContent = api.manifest.name;
api.every(5000, async () => {
const { cpu } = await api.system();
el.title = `CPU ${Math.round(cpu.load)} %`;
});
}
};The API is deliberately small for now, and will grow. Set the manifest's minAppVersion to the EdgeStation version you build against, so an older app doesn't load a widget that calls what it lacks.
Members
| Member | What it does |
|---|---|
instanceId |
Id of this placement. Two copies of a widget get different ids. |
manifest |
The widget's manifest, with id set to its folder name. |
settings |
This placement's setting values, by key. |
system() |
The machine's CPU, memory, GPU, network and Wi-Fi. System and programs |
topPrograms(n) |
The n programs using the most CPU. System and programs |
media |
What is playing, and its playback controls. Media |
apps |
The apps of the Start menu or the app menu: list them, start them, show their icons. Apps |
audio |
Volumes, mute and levels of the output, the microphone and each app. Audio |
fetch(input, init?) |
The web's fetch, without CORS. Fetch |
storage |
Data kept across remounts and restarts. Storage |
webview(el, url, options?) |
A web page in a native browser view over el. Web views |
every(ms, fn) |
A setInterval managed for the widget. Timers and helpers |
after(ms, fn) |
A setTimeout managed for the widget. Timers and helpers |
guard(fn) |
Wraps a callback so its errors show the error card. Timers and helpers |
loading(task) |
Shows a loading indicator on the card until task settles. Timers and helpers |
onDispose(fn) |
Runs fn when the widget unmounts. Timers and helpers |
asset(path) |
URL of a file in the widget folder. Timers and helpers |
scrollbars(el) |
The app's overlay scrollbars for a scrolling element. Timers and helpers |
Permissions
system(), topPrograms(), media, apps, audio, fetch and webview work only when the manifest lists their permission. Otherwise a call shows the widget's error card and throws. The other members need nothing.
Released on unmount
Everything a widget registers through the api is released when it unmounts: every and after timers are cleared, web views close, scrollbars are removed, listeners stop and unanswered fetch requests are cancelled. Members that return a cleanup function (every, after, webview, scrollbars, media.onChange, audio.onChange, audio.onLevels) also let you release one sooner.
Read on demand
system(), topPrograms(), media.current(), apps.list() and audio.mixer() read the machine when called. Nothing monitors in between, so a widget pays for what it shows, when it shows it. Poll them with api.every, which stops while the widget's page is off screen. The audio mixer and the media sessions are the exception: the system tells the app when they change, so read them again from audio.onChange and media.onChange instead of polling.
instanceId
A string that identifies this placement of the widget, and stays the same across restarts. Two copies of the widget on the Edge get different ids. api.storage.instance already keeps data per placement; use instanceId when you need the id itself, for example as a key in data shared through api.storage.widget.