# Svelte 集成 (/zh/guide/quickstart-svelte)



## 安装 [#安装]

最轻入口按需选择 preset：

```bash
npm install @file-viewer/svelte @file-viewer/preset-office
```

一步到位完整能力使用 full 包：

```bash
npm install @file-viewer/svelte-full
```

`@file-viewer/svelte-full` 默认启用 `@file-viewer/preset-all`，组件、action、事件和 controller API 与标准包一致。

包根入口的默认导出固定为 Svelte 组件；action 和底层 controller helper 分别从明确的 `/action`、`/controller` 子路径导入。

## 组件用法 [#组件用法]

```svelte
<script lang="ts">
  import FileViewer from '@file-viewer/svelte'
  import officePreset from '@file-viewer/preset-office'

  const options = {
    preset: officePreset,
    rendererMode: 'replace',
    theme: 'light',
    styleIsolation: 'shadow',
    toolbar: { position: 'bottom-right' },
    archive: { cache: true }
  }

  function handleViewerEvent(event) {
    console.log(event.detail.type, event.detail.payload)
  }
</script>

<section style="height: 100vh">
  <FileViewer
    url="/files/report.docx"
    {options}
    on:viewerEvent={handleViewerEvent}
  />
</section>
```

Svelte 默认使用 Shadow DOM，宿主全局 CSS 不会破坏工具栏或 renderer 内容。只有依赖深层 class 覆盖的旧项目才使用 `styleIsolation:'none'`；tokens 和 `::part()` 主题定制见 [样式隔离与主题定制](/zh/guide/style-isolation)。

full 包写法只替换包名，不需要手动 import preset：

```svelte
<script lang="ts">
  import FileViewer from '@file-viewer/svelte-full'

  const options = {
    theme: 'light',
    toolbar: { position: 'bottom-right' }
  }
</script>

<section style="height: 100vh">
  <FileViewer url="/files/demo.pdf" {options} />
</section>
```

## Action 用法 [#action-用法]

如果你不想使用组件，可以直接把 action 挂到已有容器：

```svelte
<script lang="ts">
  import { fileViewer } from '@file-viewer/svelte/action'
  import officePreset from '@file-viewer/preset-office'

  const viewerOptions = {
    url: '/files/report.pdf',
    options: {
      preset: officePreset,
      rendererMode: 'replace',
      theme: 'light'
    }
  }
</script>

<div use:fileViewer={viewerOptions} style="height: 720px"></div>
```

Full 包的 action 使用对应的明确入口：

```ts
import { fileViewer } from '@file-viewer/svelte-full/action'
```

## Vite 自动装配 [#vite-自动装配]

SvelteKit / Vite 项目可以注册插件，让已安装 preset 自动激活，并复制 Worker / WASM / 字体 / vendor 资源：

```bash
npm install -D @file-viewer/vite-plugin
```

```ts
import { fileViewerRenderers } from '@file-viewer/vite-plugin'

export default {
  plugins: [
    fileViewerRenderers({
      copyAssets: true
    })
  ]
}
```

安装 `@file-viewer/svelte-full` 时，同一配置会识别 Full 包并在 dev/build 自动发布完整同版本资产；Full 已内置 `preset-all`，不要再安装或传入 preset。非 Vite Full 项目运行随包安装的同版本 CLI：

```bash
npx --no-install file-viewer-copy-assets ./public/file-viewer
```

非 Vite 标准包项目继续使用 `options.preset` / `options.renderers` 显式注入能力即可。