Opcje osadzania | STLViewer

Ostatnia aktualizacja: 2026-06-05

Dodanie ?embed=true do dowolnego adresu /view/:shareId przełącza przeglądarkę w czysty tryb osadzania: bez nagłówka, stopki i panelu informacji, z samym płótnem 3D oraz opcjonalnym paskiem narzędzi. Dodatkowe parametry w adresie URL pozwalają sterować najważniejszymi ustawieniami renderowania bez pisania JavaScriptu.

Format adresu URL

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

Zasady używania adresu URL

Nieznane parametry są po cichu pomijane, więc przyszłe opcje nie popsują istniejących osadzeń.
Nieprawidłowe wartości wracają do ustawień domyślnych bez wyświetlania błędu.
Parametry logiczne przyjmują 1, 0, true albo false.
Parametry zostają zachowane podczas nawigacji w przeglądarce oraz przy użyciu przycisków wstecz/dalej.

Osadzanie modelu hostowanego zewnętrznie (?url=)

Jeśli plik STL lub 3MF jest już dostępny na GitHubie, CDN-ie albo Twoim serwerze, możesz pokazać go bez wcześniejszego przesyłania do STLViewer. Użyj formy /view?url= z zakodowanym adresem pliku i dodaj &embed=true, aby włączyć czysty tryb osadzania. Wszystkie parametry osadzania działają także z ?url=, na przykład &background=transparent&autoRotate=0.

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

Adres pliku musi używać HTTPS i kończyć się na .stl albo .3mf; inne protokoły i rozszerzenia są odrzucane i przekierowują na stronę główną.
Model jest pobierany po stronie klienta, bezpośrednio z przeglądarki odwiedzającego; bajty modelu nie przechodzą przez serwery STLViewer.
Ponieważ pobieranie odbywa się między różnymi originami, serwer z plikiem musi zwracać liberalne nagłówki CORS, np. Access-Control-Allow-Origin: *. Bez nich osadzenie pokaże komunikat 'Cannot load this model' zamiast modelu.
Zakoduj adres pliku przed wstawieniem go do parametru url, aby jego własny query string, np. podpisany URL z S3, pozostał nienaruszony.
Cały plik trafia do pamięci przeglądarki, więc dla stabilnego działania na typowych urządzeniach trzymaj zewnętrzne modele poniżej około 100 MB.

Lista parametrów

Wszystkie parametry są opcjonalne. Wartości domyślne różnią się między zwykłym widokiem a trybem osadzania.

Parametr	Wartości	Domyślnie poza osadzeniem	Domyślnie w osadzeniu	Opis
`axis`	`z \| y`	z	z	Określa, która oś świata jest skierowana w górę. Wpływa na płaszczyznę automatycznego obrotu i orientację kamery.
`autoRotate`	`boolean`	1	1	Decyduje, czy model ma obracać się automatycznie po załadowaniu.
`render`	`solid \| wireframe \| xray`	solid	solid	Tryb renderowania modelu.
`grid`	`boolean`	1	0	Siatka podłogi pod modelem.
`light`	`studio \| neutral`	studio	studio	Preset oświetlenia sceny.
`background`	`auto \| light \| dark \| transparent \| hex \| env:<id>`	auto	auto	Tło płótna. auto podąża za motywem strony; light/dark wymusza stały kolor; transparent przepuszcza tło strony pod osadzeniem; 6-znakowy hex (np. 1a2b3c) ustawia własny kolor; env:<id> używa obrazu otoczenia (studio, sunset, dawn, forest, city, warehouse).
`material`	`preset ID`	—	—	Nazwany preset materiału. Listę identyfikatorów znajdziesz niżej.
`ui`	`none \| minimal \| full`	full	none	Widoczność interfejsu. none = samo płótno. minimal = widoczny pasek narzędzi. full = pasek narzędzi i panele boczne.
`attribution`	`boolean`	1	1	Pokazuje plakietkę 'Powered by STLViewer'. false ukrywa plakietkę, ale zostawia faviconę i podpowiedź.

Identyfikatory presetów materiału

Jako wartość parametru material podaj identyfikator wybranego presetu.

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

Przykłady

Najprostsze osadzenie (ustawienia domyślne):

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

Model ze stali z automatycznym obrotem:

<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>

Statyczne osadzenie bez interfejsu (bez paska narzędzi i plakietki):

<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>

Przezroczyste tło (za modelem widać stronę, na której jest osadzony):

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

Plik hostowany zewnętrznie (bez przesyłania — wymagany host z 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>