Браузер и WebView
Веб-страницы внутри приложения, из плагина browser. Browser.open(url) показывает страницу в
системной шторке браузера (или, с embedded: true, на отдельном экране: панель закрытия над
UIWebViewNode) и резолвится URL возврата, до которого она дошла; UIWebViewNode(props) — это
веб-страница как бокс в раскладке экрана, а WebView(params) — веб-страница на весь экран с твоими
контролами поверх.
openURL, наоборот, отдаёт URL системе — внешнему браузеру, а
tel:, sms:, mailto: — звонилке, сообщениям, почте; страница, показанная ВНУТРИ приложения, —
шторка, вход через OAuth, оплата, — это Browser.open.
- открыть веб-страницу внутри приложения, не уходя из него
- войти через страницу OAuth-провайдера и вернуться в приложение
- провести оплату на хостед-чекауте и узнать, прошла ли она
- показать веб-страницу как часть экрана
- показать веб-страницу на весь экран со своими кнопками поверх
- обмениваться сообщениями между приложением и JavaScript страницы
- узнать, загрузилась страница или не смогла
Платформы: iOS, Android, веб и веб-плеер (там это попап и iframe, которые мало что видят на странице другого origin); нет на десктопе — там используй openURL; в приложении-вьюере le.codes URL возврата приходит в шторке только на iOS с кастомной схемой, поэтому там используй embedded: true. Проверяй Browser.supported / WebView.supported. Страница внутри экрана (UIWebViewNode, а значит и embedded: true): iOS, Android и веб (Web Lite, iframe); нет в веб-плеере — проверяй UIWebViewNode.supported.
Обзор
const status = UIText("").style({ fontSize: 14 })
const help = UIButton(UIText("Help center")).onClick(() => {
Browser.open("https://example.com/help") // системная шторка браузера поверх приложения
.then(() => { status.text = "Back in the app" }) // резолвится, когда пользователь её закрыл
.catch(e => { status.text = `Couldn't open it: ${e.message}` })
})
const page = UIWebViewNode.supported
? UIWebViewNode({ url: "https://example.com" }).style({ height: 320 }) // страница внутри экрана
: UIText("No web view on this device")
UIScreen(help, status, page).style({ pt: "safe-top", p: 16, gap: 12 }).open()Подключение плагина: plugins в app.json
Browser, UIWebViewNode и WebView нужен плагин browser, перечисленный в app.json приложения — впиши его туда
или дай lecodes app plugin add browser вписать его в app.json, который уже есть в проекте:
{ "plugins": { "browser": "*" } }Список — объект (id → версия), один на все платформы: он становится заголовком бандла
// plugins:, и плагина, которого в нём нет, нет и в сборке — одинаково в оболочке, собранной из
проекта, в Web Lite и в веб-плеере; компилятор предупреждает о плагине, который приложение
использует, но не перечислило. В приложении-вьюере le.codes плагин есть, что бы ни было в списке.
Приложение-оболочка, которое получает вход или оплату обратно через шторку, ещё задаёт свою
URL-схему, "urlScheme": "myshop"
(Куда приходит URL возврата).
Открыть веб-страницу внутри приложения: Browser.open
Browser.supported: boolean // у этого хоста есть системная шторка
Browser.open(url: string, options?: {
returnUrl?: string | string[] // префиксы URL, завершающие страницу: open резолвится тем, до которого дошли
embedded?: boolean // экран с панелью закрытия над UIWebViewNode вместо шторки
ephemeral?: boolean // приватная сессия: никаких общих с браузером cookie
color?: string // панель шторки, "#RRGGBB"
title?: string // embedded: заголовок панели, пока страница не сообщит свой
}): Promise<string | null> // достигнутый URL возврата или null, если пользователь ушёлЧтобы показать страницу, не уходя из приложения, открой её в системной шторке встроенного браузера:
SFSafariViewController на iOS, Chrome Custom Tab на Android, попап-окно в вебе. Она появляется
поверх приложения с сохранёнными в браузере логинами, ключами доступа и Apple Pay; приложение ничего
не видит на странице, а open резолвится, когда пользователь её закрывает (null без returnUrl).
urlдолжен быть http(s): всё остальное отклоняется сinvalid— в вебе так же отклоняется попап, заблокированный браузером, поэтому вызывайopenиз тапа.- Одна шторка за раз: второй
open, пока первая открыта, отклоняется сbusy. - В вебе переход на страницу собственного origin приложения сразу завершает попап, и
openрезолвится этим URL: страницу собственного сайта приложения показывай там вWebView(илиembedded: true). colorтонирует панель шторки на Android и на iOS (но не iOS-шторку входа дляreturnUrlс кастомной схемой); веб его игнорирует.- PDF открывается так же: шторка показывает его на iOS и в браузере с просмотрщиком PDF; на Android
это зависит от браузера за Custom Tab, а веб-вью Android (
embedded,UIWebViewNode,WebView) PDF не рендерит.
const openPage = (url: string) => {
if (!Browser.supported) { openURL(url); return } // десктоп: вместо этого системный браузер
Browser.open(url, { color: "#1E88E5" }) // панель шторки твоего цвета
.catch(e => toast(`Couldn't open the page: ${e.message}`))
}
UIScreen(
UIButton(UIText("Terms of service")).onClick(() => openPage("https://example.com/terms")),
).style({ pt: "safe-top", p: 16 }).open()Вход через OAuth-провайдера и возврат: returnUrl
Чтобы пользователь вошёл на странице логина OAuth-провайдера (Google, GitHub, корпоративный
single sign-on) и вернулся в приложение, открой страницу в шторке встроенного браузера — это
поверхность, которую провайдеры принимают, с сохранёнными в браузере логинами, — и передай в
returnUrl redirect URL, зарегистрированный у провайдера. Когда провайдер перенаправит туда,
шторка закроется, а open резолвится этим URL; code — в его query.
import { signInWithCode } from "./auth.server" // твой сервер: code → токен → db.auth.signIn
const RETURN = "myshop://oauth" // app.json "urlScheme": "myshop"
const authUrl = "https://auth.example.com/authorize?response_type=code&client_id=YOUR_CLIENT_ID" +
"&redirect_uri=" + encodeURIComponent(RETURN)
const signIn = async () => {
const back = await Browser.open(authUrl, { returnUrl: RETURN }) // "myshop://oauth?code=…" или null
const code = back && /[?&]code=([^&#]+)/.exec(back)?.[1]
if (!code) return toast("Sign-in cancelled")
await signInWithCode(decodeURIComponent(code))
toast("Signed in")
}
UIScreen(UIButton(UIText("Sign in")).onClick(() => { signIn() }))
.style({ pt: "safe-top", p: 16 }).open()- Для возврата используй кастомную схему (
myshop://oauth) и задай её в app.json как"urlScheme": "myshop";lecodes app syncвпишет её в iOS- и Android-оболочки. На iOS шторка входа (ASWebAuthenticationSession) ловит редирект сама; на Android редирект приходит в приложение его событиемurl(диплинки), для чего схема должна быть зарегистрирована; в вебе кастомная схема никогда не возвращается, поэтому там редирект должен вести на страницу собственного origin приложения. УreturnUrlодной шторки одна схема, иначеopenотклоняется. - Обменять code — работа твоего сервера: серверная функция меняет его у провайдера (client secret
остаётся на сервере) и логинит человека через
db.auth.signIn(userId)— Вход. ephemeral: trueпросит приватную сессию без сохранённых логинов — учитывается только на iOS, сreturnUrlна кастомной схеме.- Если человек вместо этого закрыл шторку,
openрезолвитсяnull.
Хостед-чекаут: узнать, прошла ли оплата
Чтобы принять платёж на хостед-странице оплаты платёжного провайдера и узнать, чем всё кончилось,
передай в returnUrl URL успеха и неудачи, на которые чекаут перенаправляет: open резолвится тем,
до которого дошли, или null, если человек закрыл страницу. С embedded: true страница работает на
отдельном экране — панель закрытия над UIWebViewNode, — который сам ловит URL возврата — https
тоже, без URL-схемы и app links, и в приложении-вьюере le.codes тоже, — так что на iOS и Android
страница возврата никогда не загружается.
const PAID = "https://shop.example.com/checkout/paid" // URL, на которые твой платёжный провайдер
const FAILED = "https://shop.example.com/checkout/failed" // перенаправляет в конце
const pay = async (checkoutUrl: string) => {
const back = await Browser.open(checkoutUrl, { returnUrl: [PAID, FAILED], embedded: true, title: "Payment" })
if (back?.startsWith(PAID)) toast("Paid, thank you")
else if (back?.startsWith(FAILED)) toast("The payment did not go through")
else toast("Checkout closed") // null: пользователь закрыл
}
Router.init(UIScreen(
UIButton(UIText("Pay 9.99")).onClick(() => { pay("https://pay.example.com/session/123") }),
).style({ pt: "safe-top", p: 16 }))- URL возврата говорит, куда ушла страница, а не что деньги пришли: подтверди платёж на своём сервере (вебхук или API провайдера), прежде чем отгружать заказ.
- Встроенная страница кладётся на Router, когда на экране страница Router'а, — её кнопка закрытия,
кнопка «назад» и свайп назад завершают её с
null, как и вызов страницейwindow.close(); иначе она открывается вместо текущего destination, который потом возвращается. Её панель следуетthemeприложения;color— для шторки. - Экран — это
UIScreen(bar, UIWebViewNode({ url, stops: returnUrls }).style({ flex: 1 })); для другого обрамления собери свой (ниже). В вебе (Web Lite) узел на этом экране — iframe страницы; веб-плеерUIWebViewNodeне рисует, поэтомуembedded: trueтам отклоняется. - На iOS Apple Pay работает во встроенной странице, пока у страницы нет моста и
evaluate, аBrowser.openне использует ни того, ни другого. Безembeddedчекаут идёт в шторке, с Apple Pay и сохранёнными логинами браузера; тогда его возврат подчиняется таблице ниже. - В вебе iframe видит возврат только на собственном origin приложения: там URL возврата должны быть адресами самого приложения.
Куда приходит URL возврата, по платформам
Резолвится ли open URL возврата, зависит от поверхности, вида URL и хоста:
шторка, кастомная схема (myshop://…) |
шторка, https | embedded: true |
|
|---|---|---|---|
| iOS | ловит сама шторка, регистрация не нужна | только как верифицированная ссылка приложения | любой URL |
| Android | событие приложения url: нужен urlScheme в app.json |
только как верифицированная ссылка приложения | любой URL |
| веб (Web Lite) | никогда | первая страница собственного origin приложения, до которой дошёл попап | URL собственного origin приложения |
| веб-плеер | никогда | первая страница собственного origin приложения, до которой дошёл попап | нет хостового узла: open отклоняется |
| приложение-вьюер le.codes | только iOS | никогда | любой URL |
| десктоп | плагина нет: используй openURL |
— | — |
urlSchemeотносится к приложению-оболочке (Своя URL-схема):lecodes app syncвписывает её в iOS Info.plist и в Android-манифест. Строчные латинские буквы, цифры,+ - ., начинается с буквы, никогда неhttpилиhttps. Оболочки регистрируют эту схему, а не верифицированные https-ссылки (universal links, App Links): для них в app.json ключа нет.- Приложение-вьюер le.codes не регистрирует ни схем, ни ссылок проекта:
embedded: true— способ получить там возврат (и, на iOS, кастомная схема в шторке). - В вебе попап резолвится первым URL собственного origin приложения, на который попадёт, —
совпадает он с
returnUrlили нет; кастомная схема никогда не возвращается.
Веб-страница как часть экрана: UIWebViewNode
UIWebViewNode.supported: boolean // статик — iOS, Android, Web Lite; false в веб-плеере, на десктопе, в headless
UIWebViewNode(props?: {
url?: string // вживую: запись загружает его
stops?: string[] // вживую: префиксы URL, завершающие поток, — не загружаются, вместо этого `onStop`
externalLinks?: "open" | "block" // вживую: tel:, mailto:, intent:, другие приложения — системе (по умолчанию) или выбрасываются
bridge?: boolean // window.lecodes на странице; по умолчанию false — только при создании
userAgent?: string // только при создании
ephemeral?: boolean // приватная сессия: ничего не хранится после ухода узла — только при создании
}): UIWebViewNode
node.url = "https://example.com/next" // загружает его; повторная запись того же URL перезагружает
node.stops = [PAID, FAILED] // то же, что setStops
node.externalLinks = "block"Чтобы показать веб-страницу между своими элементами — условия над кнопкой «Принять», страницу в
карточке, — используй UIWebViewNode: узел раскладки экрана, бокс среди его детей, как UIImage, с
нарисованной внутри страницей. Страница, которая заполняет экран с контролами поверх, остаётся
WebView, открытым как destination (ниже); у узла
нет open, onBack и widgets.
// app.json: "plugins": { "browser": "*" }
const terms = UIWebViewNode({ url: "https://example.com/terms" })
.style({ flex: 1, borderRadius: 12 }) // бокс раскладки: размер задают его стили
UIScreen(
UIText("Terms of service").style({ fontSize: 20, fontWeight: 700 }),
UIWebViewNode.supported ? terms : UIText("No web view on this device"),
UIButton(UIText("Accept")).onClick(() => toast("Accepted")), // между твоими элементами
).style({ pt: "safe-top", p: 16, gap: 12 }).open()- Размещается, как любой элемент: дай ему
heightилиflex: 1в колонке, аborderRadiusскругляет страницу (узел обрезает содержимое:overflow: "hidden"у него по умолчанию). О безопасной зоне он ничего не знает: держи его внутри паддингов экрана. url,stopsиexternalLinksработают вживую; геттер отвечает то, что записали последним, а не то, куда перешла страница, — для этогоonNavigate.bridge,userAgentиephemeralсоздают платформенный веб-вью, поэтому читаются один раз, при первом показе узла: передай их вUIWebViewNode(...)(более поздние записи игнорируются, со строкой в логе устройства).- Его вызовы (
load,evaluate, …) работают с самого начала, даже в том тике, где узел создан. - Его события — методы:
onNavigate,onLoad,onError,onStop,onMessage(события); у узла нетexit—window.close()на его странице ничего не делает.
в вебе (Web Lite) узел — это iframe в своём боксе, та же страница, что и у
полноэкранного WebView: о странице другого origin он не знает ни навигации, ни заголовка, ни
ссылок (onLoad сообщает запрошенный URL; onStop срабатывает только для стоп-URL собственного
origin приложения; externalLinks действует только на ссылки страницы того же origin),
userAgent игнорируется, а ephemeral — это credentialless фрейма (Chromium). В веб-плеере, на
десктопе и в headless-тестах узел — пустой бокс своего размера, а UIWebViewNode.supported равен
false (создание узла там один раз выдаёт предупреждение) — ветвись по нему, как выше. WebView
никогда не бывает частью экрана: переданный экрану дочерним элементом, он попадает в отчёт и
пропускается — страница на экране — это UIWebViewNode.
Веб-страница на весь экран: Router.push и виджеты
Чтобы показать веб-страницу на весь экран, открой сам WebView: как карта или превью камеры, это
отдельный destination (NativeView) — Router.push(view) его показывает,
кнопка «назад» и свайп назад снимают его со стека, а твои контролы плавают поверх как его
виджеты. Страница, которая является частью экрана, — это UIWebViewNode
(выше).
const MENU = "https://example.com/menu"
const page = WebView({ url: MENU })
const close = UIWidget(
UIButton(UIText("Close").style({ color: "white" })).onClick(() => Router.pop()),
).style({ top: "safe-top", right: 16, px: 12, py: 8, borderRadius: 8, bgColor: "rgba(0,0,0,0.6)" })
page.widgets(close) // плавает над страницей, пока она показана
Router.init(UIScreen(
UIButton(UIText("Open the menu")).onClick(() => {
if (WebView.supported) Router.push(page) // страница — это destination
else openURL(MENU) // десктоп: системный браузер
}),
).style({ pt: "safe-top", p: 16 }))Если нужна своя шапка над страницей, а не поверх неё, положи UIWebViewNode на экран под панелью
(flex: 1) — то, что строит Browser.open с embedded: true, — и открой этот экран.
Общение со страницей: bridge, postMessage, evaluate
Чтобы передавать данные между приложением и JavaScript страницы, создай страницу с bridge: true:
страница получает window.lecodes, чей postMessage(data) вызывает событие message, а
page.postMessage(data) приложения вызывает window.lecodes.onMessage(data) страницы. Данные —
JSON. evaluate(js) выполняет скрипт на странице и резолвится его значением, как JSON. У
UIWebViewNode и WebView одни и те же вызовы; события — onMessage(cb) у узла и
on("message", cb) у вью.
const page = UIWebViewNode({ url: "https://example.com/widget.html", bridge: true }).style({ flex: 1 })
page.onMessage(({ data }) => { // страница вызвала window.lecodes.postMessage(data)
if (data === "ready") page.postMessage({ theme: "dark" }) // → window.lecodes.onMessage(data) на странице
else console.log("from the page:", JSON.stringify(data))
})
page.onLoad(() => {
page.evaluate("document.title") // выполнить JavaScript на странице, получить JSON
.then(title => console.log("page title:", title))
.catch(e => console.log("evaluate failed:", e.message))
})
UIScreen(page).style({ pt: "safe-top" }).open()Сторона страницы (https://example.com/widget.html):
<script>
// на iOS и Android window.lecodes есть ещё до запуска скриптов страницы; в вебе и в
// старых веб-вью Android он появляется позже — дождись его
const withBridge = (f) => window.lecodes ? f(window.lecodes) : setTimeout(() => withBridge(f), 50)
withBridge((bridge) => {
bridge.onMessage = (data) => { document.body.dataset.theme = data.theme }
bridge.postMessage("ready")
})
</script>- Мост принадлежит главному фрейму: у iframe внутри страницы его нет.
- На iOS мост выключает Apple Pay на этой странице, как и каждый
evaluateдо следующей навигации страницы, — на странице оплаты не включай ни то, ни другое. - В вебе мосту,
evaluateиpostMessageнужна страница собственного origin приложения (иначе оба вызова отклоняются сfailed); страница другого origin всё равно может отправлять черезparent.postMessage({ lecodes: data }, "*").
Загрузилась страница или нет: события
node.onNavigate(({ url }) => {}) // началась навигация главного фрейма — view.on("navigate", …)
node.onLoad(({ url, title }) => {}) // страница загрузилась; title "", если его нет
node.onError(({ url, message }) => {}) // страница не загрузилась
node.onStop(({ url }) => {}) // достигнут URL из `stops`: не загружен
node.onMessage(({ data }) => {}) // window.lecodes.postMessage(data) — bridge: true
view.on("exit", () => {}) // страница WebView вызвала window.close() (у узла такого нет)Чтобы показать состояние загрузки, заголовок страницы или ошибку, слушай события страницы:
const heading = signal("Loading…")
const canGoBack = signal(false)
const page = UIWebViewNode({ url: "https://example.com" }).style({ flex: 1 })
page.onNavigate(() => { heading.value = "Loading…" }) // началась новая страница
page.onLoad(({ title, url }) => { // она загрузилась
heading.value = title || url
page.canGoBack().then(can => { canGoBack.value = can })
})
page.onError(({ message }) => { heading.value = `Couldn't load: ${message}` })
const back = UIButton(UIText("‹ Back"))
.style({ opacity: () => canGoBack.value ? 1 : 0.3 })
.onClick(() => { page.goBack() })
UIScreen(UIRow(back, UIText(() => heading.value).style({ flex: 1 })).style({ gap: 8, p: 8 }), page)
.style({ pt: "safe-top" }).open()stops(илиsetStops) завершают поток, не загружая его последнюю страницу: навигация на URL, который начинается с одного из них, — ссылка, редирект, отправка формы — отменяется и сообщается какstop. Так встроенныйBrowser.openловит свойreturnUrl.- В вебе iframe видит меньше:
navigateприходит только для загрузок самого приложения,errorиexitне срабатывают никогда, а страница другого origin сообщает толькоload, с URL, который запросило приложение, и без заголовка, — стоп ловится только в собственномloadприложения или, когда страница уже загрузилась, на собственном origin приложения.
Управление страницей: load, goBack, reload, clearData
page.load(url, headers?): Promise<void> // заголовки идут с первым запросом; "invalid" для не-веб URL
page.loadHtml(html, baseUrl?): Promise<void> // относительные URL в нём разрешаются от baseUrl
page.setStops(stops): Promise<void> // заменить список стопов (и `stops` узла тоже)
page.reload(): Promise<void>
page.stopLoading(): Promise<void>
page.goBack(): Promise<void>
page.goForward(): Promise<void>
page.canGoBack(): Promise<boolean>
page.evaluate(js): Promise<Json> // отклоняется с "failed"
page.postMessage(data): Promise<void> // → window.lecodes.onMessage(data)
page.clearData(): Promise<void> // cookie и хранилище
WebView.supports(method): boolean // false на хосте, чья половина старше методаЧтобы загрузить другую страницу, пройти по истории страницы или стереть то, что она сохранила,
вызывай методы страницы — у UIWebViewNode и WebView они одинаковые; каждый возвращает промис.
clearData()иephemeralдействуют шире страницы: на Android cookie и веб-хранилище принадлежат приложению и общие для всех его веб-вью, так что оба чистят всё (ephemeral— когда страница уходит); на iOSclearData()страницы безephemeralчистит общие веб-данные приложения; в вебеclearData()ничего не делает.externalLinks: "open"(по умолчанию) отдаёт не-веб ссылки —tel:,mailto:,intent:, приложение банка при оплате — системе;"block"их выбрасывает.- Ссылка с
target="_blank"на iOS и Android открывается в той же странице: второго окна нет. - В вебе заголовки
load,userAgent,ephemeralиexternalLinksигнорируются, аgoBack/goForward/stopLoadingна странице другого origin ничего не делают.
По платформам
Что такое шторка и веб-вью на каждом хосте:
- iOS — шторка — это SFSafariViewController, а для
returnUrlс кастомной схемой — ASWebAuthenticationSession (системная шторка входа);UIWebViewNodeиWebView— это WKWebView. - Android — шторка — это Chrome Custom Tab (
ephemeralигнорируется);UIWebViewNodeиWebView— системный WebView. - Веб (Web Lite) — шторка — это попап-окно (
colorиephemeralигнорируются);UIWebViewNodeиWebView— iframe, который встроенныйBrowser.openкладёт на свой экран; страница другого origin видна только снаружи (таблица и события выше). - Веб-плеер — шторка — попап, а
WebView— iframe, как в Web Lite;UIWebViewNodeнет (supportedравен false, пустой бокс), поэтомуBrowser.open({ embedded: true })там отклоняется. - Десктоп — плагина браузера нет:
Browser.supported,UIWebViewNode.supportedиWebView.supportedравны false, аopenотклоняется; используйopenURL. - Приложение-вьюер le.codes (iOS, Android, iOS App Clip) — плагин есть, что бы ни было в
app.json, а URL-схемы проекта нет: возврат получай через
embedded: true. - Headless-тесты (
lecodes render/lecodes test) — шторки нет:Browser.openотклоняется сBrowser.open isn't available on this host — it needs the "browser" plugin …;UIWebViewNode— пустой бокс (supportedfalse);WebViewсуществует, только если запуск его называет (--native-view webView), как бокс-заглушка, все вызовы которого отклоняются и который не шлёт событий.
Подводные камни
-
Метод
WebView, вызванный до того, как вью появилось на экране, отклоняется; первую страницу передавай параметром (UIWebViewNodeпринимает вызовы с самого начала):const page = WebView(); page.load("https://example.com") // ✗ вью ещё нет на экране: отклоняется const page = WebView({ url: "https://example.com" }) // ✓ -
bridge,userAgentиephemeralуUIWebViewNodeчитаются при первом показе: пиши их вUIWebViewNode({ … }), а не позже. -
returnUrlс кастомной схемой в шторке на Android никогда не возвращается в проекте безurlScheme, как и в приложении-вьюере le.codes:openрезолвитсяnull, когда человек закрывает шторку. Там используйembedded: true.
Смотрите также
- NativeView — что такое
WebView: destination - UIWidget — контролы поверх полноэкранной страницы
- Жизненный цикл приложения и openURL —
openURL; диплинки:app.launchUrl, событиеurl - Вход — логин человека на твоём сервере после возврата из OAuth
- Серверные функции — серверный код, который обменивает code