73 lines
2.2 KiB
Markdown
73 lines
2.2 KiB
Markdown
|
---
|
||
|
|
title: useDocumentWorkspace
|
||
|
|
description: Manage document lists, refreshes, lazy previews, and workspace events.
|
||
|
|
---
|
||
|
|
|
||
|
|
# useDocumentWorkspace
|
||
|
|
|
||
|
|
`useDocumentWorkspace()` provides headless state for document browsers backed by local or remote storage.
|
||
|
|
|
||
|
|
It manages:
|
||
|
|
|
||
|
|
- initial, manual, focused-window, reconnect, and interval refreshes
|
||
|
|
- deduplicated refresh requests and source invalidation events
|
||
|
|
- lazy preview loading with bounded concurrency
|
||
|
|
- preview object URL creation and cleanup
|
||
|
|
- per-preview errors
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
```ts
|
||
|
|
import { useDocumentWorkspace } from '@open-pencil/vue'
|
||
|
|
|
||
|
|
const workspace = useDocumentWorkspace({
|
||
|
|
source: {
|
||
|
|
refresh: () => documentService.list(),
|
||
|
|
loadPreview: (id) => documentService.loadPreview(id),
|
||
|
|
subscribe: (listener) => documentService.subscribe(listener),
|
||
|
|
},
|
||
|
|
refreshInterval: 60_000,
|
||
|
|
})
|
||
|
|
```
|
||
|
|
|
||
|
|
The source must return items with `id`, `name`, and `updatedAt`. A changed `updatedAt` value invalidates an existing or in-flight preview.
|
||
|
|
|
||
|
|
## Lazy previews
|
||
|
|
|
||
|
|
Apply `previewDirective` to the element that should trigger loading, then resolve the current object URL with `previewURL()`:
|
||
|
|
|
||
|
|
```vue
|
||
|
|
<script setup lang="ts">
|
||
|
|
const { documents, previewDirective: vDocumentPreview, previewURL } = workspace
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<template>
|
||
|
|
<article v-for="document in documents" :key="document.id">
|
||
|
|
<div v-document-preview="document.id">
|
||
|
|
<img v-if="previewURL(document.id)" :src="previewURL(document.id) ?? undefined" alt="" />
|
||
|
|
</div>
|
||
|
|
</article>
|
||
|
|
</template>
|
||
|
|
```
|
||
|
|
|
||
|
|
When `IntersectionObserver` is unavailable, the directive loads the preview immediately.
|
||
|
|
|
||
|
|
## Errors
|
||
|
|
|
||
|
|
`error` contains the latest document-list refresh failure. Preview failures are available by document ID through `previewErrors`; use `onPreviewError` when errors should also be reported to an application service.
|
||
|
|
|
||
|
|
```ts
|
||
|
|
const workspace = useDocumentWorkspace({
|
||
|
|
source,
|
||
|
|
onPreviewError(id, error) {
|
||
|
|
reportPreviewError({ id, error })
|
||
|
|
},
|
||
|
|
})
|
||
|
|
```
|
||
|
|
|
||
|
|
Calling `loadPreview(id)` retries a failed preview. Successful loads clear the corresponding preview error.
|
||
|
|
|
||
|
|
## Cleanup
|
||
|
|
|
||
|
|
The composable revokes generated object URLs and unsubscribes from the source when its component unmounts. Call `clearPreviews()` when switching an external workspace or provider without unmounting the component.
|