Параметри вбудовування

Останнє оновлення: 2026-06-05

Додавши ?embed=true до будь-якого URL /view/:shareId, ви перемикаєте переглядач у чистий режим вбудовування: без шапки, футера й інформаційної панелі, лише з 3D-полотном і, за потреби, панеллю інструментів. Додаткові параметри в URL дають змогу керувати основними налаштуваннями рендерингу без JavaScript.

Формат URL

https://stlviewer.online/view/{shareId}?embed=true&param=value&...

Правила роботи з URL

Невідомі параметри тихо ігноруються, тому майбутні опції не зламають уже наявні вбудовування.
Некоректні значення повертаються до типових без помилок.
Логічні параметри приймають 1, 0, true або false.
Параметри зберігаються під час навігації всередині переглядача та при використанні кнопок назад/вперед у браузері.

Вбудовування моделі із зовнішнього хостингу (?url=)

Якщо ваш STL або 3MF уже лежить на GitHub, CDN чи власному сервері, його можна показати без попереднього завантаження до STLViewer. Використайте форму /view?url= із закодованим посиланням на файл і додайте &embed=true, щоб увімкнути чисте вбудовування. Усі параметри вбудовування працюють і разом із ?url=, наприклад &background=transparent&autoRotate=0.

https://stlviewer.online/view?url={encodedFileUrl}&embed=true&param=value&...

URL файлу має використовувати HTTPS і закінчуватися на .stl або .3mf; інші протоколи та розширення відхиляються й перенаправляють на головну сторінку.
Модель завантажується на боці клієнта, прямо з браузера відвідувача; байти моделі не проходять через сервери STLViewer.
Оскільки це міждоменний запит, сервер із файлом має повертати відкриті заголовки CORS, наприклад Access-Control-Allow-Origin: *. Без них у вбудовуванні з'явиться повідомлення 'Cannot load this model' замість моделі.
Закодуйте посилання на файл перед вставленням у параметр url, щоб його власний query string, наприклад підписаний URL з S3, залишився цілим.
Увесь файл завантажується в пам'ять браузера, тому для стабільної роботи на звичайних пристроях тримайте зовнішні моделі приблизно до 100 MB.

Довідник параметрів

Усі параметри необов'язкові. Типові значення відрізняються для звичайного режиму й режиму вбудовування.

Параметр	Значення	Типово у звичайному режимі	Типово у вбудовуванні	Опис
`axis`	`z \| y`	z	z	Визначає, яка вісь світу спрямована вгору. Впливає на площину автоматичного обертання та орієнтацію камери.
`autoRotate`	`boolean`	1	1	Визначає, чи модель автоматично обертається після завантаження.
`render`	`solid \| wireframe \| xray`	solid	solid	Режим рендерингу моделі.
`grid`	`boolean`	1	0	Підлогова сітка під моделлю.
`light`	`studio \| neutral`	studio	studio	Пресет освітлення сцени.
`background`	`auto \| light \| dark \| transparent \| hex \| env:<id>`	auto	auto	Тло полотна. auto наслідує тему сторінки; light/dark задають фіксований колір; transparent пропускає тло сторінки під вбудовуванням; 6-символьний hex (напр. 1a2b3c) задає власний колір; env:<id> використовує зображення оточення (studio, sunset, dawn, forest, city, warehouse).
`material`	`preset ID`	—	—	Іменований пресет матеріалу. Список ідентифікаторів наведено нижче.
`ui`	`none \| minimal \| full`	full	none	Видимість інтерфейсу. none = лише полотно. minimal = показана панель інструментів. full = панель інструментів і бічні панелі.
`attribution`	`boolean`	1	1	Показує бейдж 'Powered by STLViewer'. false ховає бейдж, але залишає favicon і підказку.

Ідентифікатори пресетів матеріалу

Як значення параметра material використовуйте ідентифікатор потрібного пресета.

color

color-blue — Blue
color-pastel-green — Green
color-pastel-red — Red
color-pastel-yellow — Yellow

metal

metal-steel — Steel
metal-copper — Copper
metal-gold — Gold
metal-aluminium — Aluminium
metal-chrome — Chrome

wood

wood-oak — Oak
wood-walnut — Walnut
wood-pine — Pine

stone

stone-marble — Marble
stone-granite — Granite
stone-concrete — Concrete

plastic

plastic-white — White
plastic-black — Black

ceramic

ceramic-white-glossy — Porcelain

Приклади

Мінімальне вбудовування (типові налаштування):

<iframe src="https://stlviewer.online/view/{shareId}?embed=true"
  title="My part" style="width:100%;height:600px;border:0;"
  loading="lazy" allowfullscreen></iframe>

Сталева модель з автоматичним обертанням:

<iframe src="https://stlviewer.online/view/{shareId}?embed=true&material=metal-steel&autoRotate=1"
  title="My part" style="width:100%;height:600px;border:0;"
  loading="lazy" allowfullscreen></iframe>

Статичне вбудовування без інтерфейсу (без панелі інструментів і бейджа):

<iframe src="https://stlviewer.online/view/{shareId}?embed=true&autoRotate=0&attribution=0"
  title="My part" style="width:100%;height:600px;border:0;"
  loading="lazy" allowfullscreen></iframe>

Прозоре тло (за моделлю видно сторінку, куди її вбудовано):

<iframe src="https://stlviewer.online/view/{shareId}?embed=true&background=transparent"
  title="My part" width="800" height="600"
  frameborder="0" loading="lazy" allowfullscreen></iframe>

Файл із зовнішнього хостингу (без завантаження — потрібен хост із CORS):

<iframe src="https://stlviewer.online/view?url=https%3A%2F%2Fcdn.example.com%2Fmodel.stl&embed=true&autoRotate=0"
  title="My part" style="width:100%;height:600px;border:0;"
  loading="lazy" allowfullscreen></iframe>