@dvina/ artifact- render
@dvina/artifact-renderer 用于在您的应用程序中嵌入 Dvina 艺术渲染器的 Iframe- first SDK .
它针对需要预览用户上传,生成文物,以及私人文档而不直接在主机app DOM内渲染出不可信内容的产品.
安装
npm install @dvina/artifact-renderer
重要
这个包是主机侧SDK. 您还需要将自备的取景器图像部署到诸如 https://viewer.example.com/。 。 。 .
docker run --pull always -p 8080:8080 kantist/artifact-renderer-viewer:latest
快速启动
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()。 。 。 .
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(...) 当您的应用主题改变时.
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。 。 。 .
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
在它的包装器中, 因为文档级别样式是不存在的 .
滚动进度
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后端集成
- 查看器部署
- 发布清单