Браузер и 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.

Обзор

TypeScript
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, который уже есть в проекте:

JSON
{ "plugins": { "browser": "*" } }

Список — объект (id → версия), один на все платформы: он становится заголовком бандла // plugins:, и плагина, которого в нём нет, нет и в сборке — одинаково в оболочке, собранной из проекта, в Web Lite и в веб-плеере; компилятор предупреждает о плагине, который приложение использует, но не перечислило. В приложении-вьюере le.codes плагин есть, что бы ни было в списке. Приложение-оболочка, которое получает вход или оплату обратно через шторку, ещё задаёт свою URL-схему, "urlScheme": "myshop" (Куда приходит URL возврата).

Открыть веб-страницу внутри приложения: Browser.open

TypeScript
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 не рендерит.
TypeScript
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.

TypeScript
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 страница возврата никогда не загружается.

TypeScript
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

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

TypeScript
// 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() на его странице ничего не делает.
Note

в вебе (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 (выше).

TypeScript
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) у вью.

TypeScript
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):

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 }, "*").

Загрузилась страница или нет: события

TypeScript
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() (у узла такого нет)

Чтобы показать состояние загрузки, заголовок страницы или ошибку, слушай события страницы:

TypeScript
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

TypeScript
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 — когда страница уходит); на iOS clearData() страницы без 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 — пустой бокс (supported false); WebView существует, только если запуск его называет (--native-view webView), как бокс-заглушка, все вызовы которого отклоняются и который не шлёт событий.

Подводные камни

  • Метод WebView, вызванный до того, как вью появилось на экране, отклоняется; первую страницу передавай параметром (UIWebViewNode принимает вызовы с самого начала):

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

Смотрите также