# @dvina/artifact-renderer 中文文档

规范地址：https://npmcn.com/package/%40dvina/artifact-renderer/

版本：0\.0\.59
npm 元数据更新时间：2026-11-13T12:10:40.478Z
中文译文更新时间：2026-11-13T01:07:11.646Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dvina/artifact-renderer
原文对照：https://npmcn.com/package/%40dvina/artifact-renderer/?lang=original
项目主页：https://github.com/dvina/artifact-renderer#readme
源码仓库：https://github.com/kantist/artifact-renderer

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：51.5 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-04-09T08:48:04.800Z
- 最新版本发布：2026-11-13T12:10:40.269Z
- 近 30 天下载量：4877（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：59（近 12 个月 59 个）

## 中文简介

用于将 Dvina 艺术渲染器嵌入 Iframe 中的框架不可知 SDK .

## 安装

```sh
npm install @dvina/artifact-renderer
```

也可以使用：`pnpm add @dvina/artifact-renderer`、`yarn add @dvina/artifact-renderer`、`bun add @dvina/artifact-renderer`

## README

# @dvina/ artifact- render

`@dvina/artifact-renderer` 用于在您的应用程序中嵌入 Dvina 艺术渲染器的 Iframe- first SDK .

它针对需要预览用户上传,生成文物,以及私人文档而不直接在主机app DOM内渲染出不可信内容的产品.

## 安装

```bash
npm install @dvina/artifact-renderer
```

## 重要

这个包是主机侧SDK. 您还需要将自备的取景器图像部署到诸如 `https://viewer.example.com/`。 。 。 .

```bash
docker run --pull always -p 8080:8080 kantist/artifact-renderer-viewer:latest
```

## 快速启动

```ts
import { createViewer, type ViewerDocument } from "@dvina/artifact-renderer";

const container = document.querySelector("#viewer-slot");

if (!(container instanceof HTMLElement)) {
  throw new Error("Viewer container not found.");
}

const documentToPreview: ViewerDocument = {
  id: "artifact-123",
  name: "analysis.pdf",
  format: "pdf",
  source: {
    kind: "url",
    url: "https://cdn.example.com/previews/analysis.pdf",
  },
};

createViewer({
  container,
  viewerUrl: "https://viewer.example.com/",
  allowedOrigin: "https://viewer.example.com",
  document: documentToPreview,
});
```

## 私有文件

对于私人文件,请使用会话支持的文档并提供 `getSession()`。 。 。 .

```ts
createViewer({
  container,
  viewerUrl: "https://viewer.example.com/",
  allowedOrigin: "https://viewer.example.com",
  document: {
    id: "private-doc-7",
    name: "board-packet.docx",
    format: "docx",
    source: {
      kind: "session",
      sessionId: "board-packet-session",
      url: "https://api.example.com/viewer/files/private-doc-7/preview",
    },
  },
  getSession: async () => {
    const response = await fetch("https://api.example.com/viewer/sessions", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        documentId: "private-doc-7",
        scope: "artifacts:read",
      }),
      credentials: "include",
    });

    if (!response.ok) {
      throw new Error("Failed to create viewer session.");
    }

    return response.json();
  },
});
```

## 主要 API

-   `createViewer(options)`
-   `controller.loadDocument(document, options?)`
-   `controller.setTheme(theme)`
-   `controller.setSafeArea(safeArea)`
-   `controller.goToPage(page)`
-   `controller.sendArtifactData(data, options?)`
-   `controller.destroy()`
-   `controller.getDiagnostics()`

## 正在装入

查看器在文件加载时不会自行绘图 。 将自己的UI装入iframe直到 `viewer.document-loaded` 事件(或 `viewer.error` 编号 : `viewer.unsupported`)),所以你的应用程序到处都有一个回旋器.

## 主题更新

过 `theme` 改为 `createViewer(...)` 最初提交,然后打电话 `setTheme(...)` 当您的应用主题改变时.

```ts
const controller = createViewer({
  container,
  viewerUrl: "https://viewer.example.com/",
  allowedOrigin: "https://viewer.example.com",
  document: documentToPreview,
  theme: { mode: "light" },
});

controller.setTheme({
  mode: "dark",
  tokens: {
    surface: "#0f1115",
    text: "#f3f5f8",
  },
});
```

`setTheme(...)` 更新查看器的外观,而不重新装入当前文档.

## 安全区域

通过重叠和设备设置 `createViewer`每一个边是有限的, cSS 像素中的非负数; 省略边缘默认为 `0`。 。 。 .

```ts
const controller = createViewer({
  container,
  viewerUrl: "https://viewer.example.com/",
  allowedOrigin: "https://viewer.example.com",
  document: documentToPreview,
  safeArea: { top: 64, right: 0, bottom: 34, left: 0 },
});

controller.setSafeArea({ top: 80, bottom: 24 });
controller.setSafeArea({}); // Reset all edges.
```

`setSafeArea` 不重新装入文档而替换所有边缘。 最新值 保留到文档负载、 HTML 流和在准备前发出的呼叫. 消费者应测量其安全区域值中的叠加和解决装置 自有窗口(包括 `env(safe-area-inset-*)` 需要时);这些不读 或自动添加.

PDF, PPTX, DOCX, 文本, Markdown, 代码, 媒体, 和存档查看器应用套件到 他们的滚动表面,所以内容可以滚动到覆盖的主机头下. 电子表格标题和页脚尊重设置; EPUB 保留周围的空间 它的导航和分会架.

启动 HTML 在文档中应用套件并曝光 `--viewer-safe-area-top/right/bottom/left`, (中文(简体) ), `window.artifactRenderer.safeArea`, (中文(简体) ), 编辑 `dvina-artifact-renderer:safe-area` 窗口事件。 自定义固定/粘贴 布局或嵌入式滚动符可以自己使用这些值. 直接- URL HTML, 已禁用的靴子和脚本已失效的沙盒, 而不是设置了 iframe 在它的包装器中, 因为文档级别样式是不存在的 .

## 滚动进度

```ts
const controller = createViewer({
  container,
  viewerUrl,
  allowedOrigin,
  document,
  scrollProgressDistance: 48, // optional; CSS pixels, default 48
  onScroll(progress) {
    header.style.setProperty("--title-scroll", String(progress));
  },
});
```

`progress` 文档从上到下滚动了多远 `scrollProgressDistance` 像素,圆相至百分. 观众跟随 元素垂直滚动(Markdown页面,PDF视图端口,一个工作表,DOCX, PPTX,代码,档案,EPUB;侧道卷轴被忽略. 启动 HTML 报告它 自己的文档的卷轴通过桥。 它只在变化时发出,最多一次a 框,所以滚动过相距不会发出更多的信号,当一个新的时它会重排到 0 文档加载。 同样的值到达 `onEvent` 作为 `viewer.scroll`; 没有记录 在诊断.

## 运行时便笺

-   只浏览器软件包
-   准确 `allowedOrigin` 需要时间
-   私人文件应当使用短寿命的无记名会话

## 相关软件包

-   `@dvina/artifact-renderer-core`
-   `@dvina/artifact-renderer-protocol`

## 文档

参见存储文件:

-   反应整合
-   角20+ 整合
-   NestJS后端集成
-   查看器部署
-   发布清单

## 常见问题

### @dvina/artifact-renderer 是什么？

用于将 Dvina 艺术渲染器嵌入 Iframe 中的框架不可知 SDK \.

### 如何安装 @dvina/artifact-renderer？

在项目目录运行 npm install @dvina/artifact-renderer，或使用 pnpm add / yarn add / bun add。

### @dvina/artifact-renderer 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dvina/artifact-renderer 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dvina/artifact-renderer 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dvina/artifact-renderer 可以商用吗？

@dvina/artifact-renderer 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dvina/artifact-renderer 的下载量有多少？

根据 npm 官方下载统计，@dvina/artifact-renderer 在 2026/10/13 – 2026/11/11 这 30 天内被下载 4,877 次，日均约 163 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dvina/artifact-renderer 还在维护吗？

最新版本 0\.0\.59 发布于 2026/11/13（今天）；至今共发布 59 个版本，其中过去 12 个月发布了 59 个；首次发布于 2026/04/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。