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

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

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

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

ПараметрЗначенняТипово у звичайному режиміТипово у вбудовуванніОпис
axisz | yzzВизначає, яка з власних осей файлу спрямована вгору (z для більшості файлів STL/CAD, y для багатьох експортів з ігор і DCC). Впливає на площину автоматичного обертання та орієнтацію камери.
autoRotateboolean11Визначає, чи модель автоматично обертається після завантаження.
rendersolid | wireframe | xray | normalssolidsolidРежим рендерингу моделі. normals забарвлює кожну поверхню за напрямком, куди вона спрямована, тож перевернуті грані одразу помітні.
normalSpaceview | worldviewviewЛише з render=normals. view забарвлює поверхні відносно камери; world прив'язує кольори до осей сцени.
normalShadingface | smoothfacefaceЛише з render=normals. face використовує нормаль кожного трикутника; smooth використовує нормалі, збережені у файлі.
gridboolean10Підлогова сітка під моделлю.
axesboolean00Гізмо орієнтації XYZ у куті полотна. Обертається разом із камерою.
lightstudio | neutral | flat | dramaticstudiostudioПресет освітлення сцени.
lightAzimuth0–360 (deg)——Перевизначає азимут (горизонтальний напрямок) активного пресету освітлення, у градусах. Циклічно в межах 0–360. Якщо не вказано, використовується значення пресету.
lightElevation-90–90 (deg)——Перевизначає висоту (кут над горизонтом) активного пресету освітлення, у градусах. Обмежено діапазоном -90–90. Якщо не вказано, використовується значення пресету.
lightIntensity0–2——Перевизначає інтенсивність основного світла активного пресету. Обмежено діапазоном 0–2. Якщо не вказано, використовується значення пресету.
lightAmbient0–1——Перевизначає фонове освітлення активного пресету. Обмежено діапазоном 0–1. Якщо не вказано, використовується значення пресету.
backgroundauto | light | dark | transparent | hex | env:<id>autoautoТло полотна. auto наслідує тему сторінки; light/dark задають фіксований колір; transparent пропускає тло сторінки під вбудовуванням; 6-символьний hex (напр. 1a2b3c) задає власний колір; env:<id> використовує зображення оточення (studio, sunset, dawn, forest, city, warehouse).
materialpreset ID——Іменований пресет матеріалу. Список ідентифікаторів наведено нижче.
uinone | minimal | fullfullnoneВидимість інтерфейсу. none = лише полотно. minimal = показана панель інструментів. full = панель інструментів і бічні панелі.
attributionboolean11Показує бейдж '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>