Эта страница переведена машинным способом и может содержать ошибки. Читать оригинал на английском

Элементы

WebView

Веб-представление показывает веб-страницу или переданный HTML внутри приложения: WKWebView на iOS и Mac Catalyst, android.webkit.WebView на Android. Поскольку NSH отрисовывает интерфейс нативными представлениями, веб-представление располагается в раскладке как любое другое представление, по порядку среди соседних. В Rust его создают с помощью web_view(url) или web_view_html(html, base_url), в TSX — с помощью <WebView> из nsh.

el-web-view.tsx
el-web-view.tsxLive
import { mount, signal, Text, View, WebView, type WebViewNavigation, type WebViewRef } from "nsh";
import { platform, windowSize } from "nsh";
import { button, buttonText, ui } from "./palette";

// The page: a button that posts to the app, and a line that shows what the
// app posts back.
const page = (c: ReturnType<typeof ui>) => `<!doctype html>
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Inline page</title>
<style>
  body { font: 15px system-ui, sans-serif; margin: 0; padding: 16px; background: ${c.page}; color: ${c.text}; }
  button { font: inherit; font-weight: 600; padding: 10px 14px; border-radius: 10px; border: 1px solid ${c.border}; background: ${c.accent}; color: ${c.page}; }
  .muted { color: ${c.muted}; }
  #got { margin-top: 12px; }
  #box { margin-top: 12px; height: 48px; border-radius: 10px; background: ${c.border}; transition: background 0.3s; }
</style>
<p class="muted">This is HTML in a web view.</p>
<button id="post">postMessage to the app</button>
<p id="got" class="muted">Nothing from the app yet.</p>
<div id="box"></div>
<script>
  let taps = 0;
  document.getElementById("post").onclick = () =>
    window.nsh.postMessage("tap " + ++taps + " from the page");
  window.addEventListener("message", (e) => { document.getElementById("got").textContent = "App says: " + e.data; });
</script>`;

function Button(props: { label: string; onPress: () => void }) {
  return (
    <View
      onPress={props.onPress}
      {...button()}
    >
      <Text style={buttonText()}>{props.label}</Text>
    </View>
  );
}

const colors = () => [ui().accent, ui().info, ui().violet, ui().down, ui().warn];

function App() {
  const messages = signal<string[]>([]);
  const nav = signal<WebViewNavigation | null>(null);
  const sent = signal(0);
  let painted = 0;
  let web!: WebViewRef;
  const wide = () => windowSize().width >= 700;

  return (
    <View style={{ flex: 1, backgroundColor: ui().page, padding: 20, paddingTop: 24, gap: 14 }}>
      <Text style={{ fontSize: 22, fontWeight: "700", color: ui().text }}>web-view</Text>
      <View style={{ flex: 1, flexDirection: wide() ? "row" : "column", gap: 16 }}>
        <WebView
          ref={web}
          html={page(ui())}
          // Runs after each load: the page reports its title.
          injectedJavaScript={`window.nsh.postMessage("loaded: " + document.title)`}
          onLoad={(e) => nav.set(e)}
          onMessage={(e) => messages.set([e.data, ...messages()].slice(0, 4))}
          style={{ flex: 1, minHeight: 240, borderRadius: 14, overflow: "hidden", borderWidth: 1, borderColor: ui().border }}
        />
        <View style={{ gap: 12, width: wide() ? 320 : undefined }}>
          <Text style={{ color: ui().muted }}>
            {platform.desktop ? "Click" : "Tap"} the button in the page to post to the app; these buttons call the ref's methods.
          </Text>
          <View style={{ flexDirection: "row", flexWrap: "wrap", gap: 8 }}>
            <Button
              label="postMessage"
              onPress={() => {
                sent.update((n) => n + 1);
                web.postMessage(`hello #${sent()}`);
              }}
            />
            <Button
              label="injectJavaScript"
              onPress={() => {
                const color = colors()[painted++ % colors().length];
                web.injectJavaScript(`document.getElementById("box").style.background = "${color}"`);
              }}
            />
            <Button label="reload" onPress={() => web.reload()} />
          </View>
          <View style={{ ...ui().card, borderRadius: 12, padding: 12, gap: 4 }}>
            <Text style={{ color: ui().muted, fontSize: 12 }}>onLoad</Text>
            <Text style={{ numberOfLines: 1, color: ui().text, fontFamily: "monospace", fontSize: 13 }}>
              {nav() ? `title "${nav()!.title}"` : "…"}
            </Text>
            <Text style={{ color: ui().muted, fontSize: 12, marginTop: 6 }}>onMessage, newest first</Text>
            <Each of={messages()}>
              {(m) => <Text style={{ color: ui().text, fontFamily: "monospace", fontSize: 13 }}>{m()}</Text>}
            </Each>
          </View>
        </View>
      </View>
    </View>
  );
}

mount(App);
use nsh_core::prelude::*;

fn browser() -> impl IntoElement {
    let title = signal(SharedString::from("Loading…"));
    view()
        .flex_1()
        .child(text(title).number_of_lines(1))
        .child(
            web_view("https://example.com")
                .flex_1()
                .on_navigation_state_change(move |e: &WebNavigation| title.set(e.title.clone().into())),
        )
}

В TSX веб-представление принимает одно из свойств src и html (см. WebView API). В руководстве по веб-представлению и видео описаны шаблоны обмена сообщениями и capabilities.

#Свойства

Веб-представление принимает свойства представления (дочерних элементов у него нет) плюс следующие:

СвойствоRustТипПо умолчаниюОписание
srcweb_view(url)stringURL отображаемой страницы.
htmlweb_view_html(html, base_url), .html(html, base_url)stringВстроенный HTML, отображается вместо src.
baseUrlbase_url из web_view_html / .htmlstringБазовый адрес, относительно которого разрешаются относительные ссылки html.
injectedJavaScript.injected_java_script(..)stringВыполняется после загрузки каждой страницы.
injectedJavaScriptBeforeContentLoaded.injected_java_script_before_content(..)stringВыполняется перед собственными скриптами каждой страницы.
userAgent.user_agent(..)stringСтрока user agent браузера.
javaScriptEnabled.java_script_enabled(..)booleantrueСтраницы выполняют скрипты.
scrollable.scrollable(..)booleantrueПользователь может прокручивать страницу.
Ключ iosRustТипОписание
allowsBackForwardNavigationGestures.back_forward_gestures(..)booleanСвайп от краёв для перехода назад и вперёд.
Ключ desktopRustТипОписание
allowsBackForwardNavigationGestures.back_forward_gestures(..)booleanmacOS: свайп двумя пальцами по трекпаду для перехода назад и вперёд; Windows: свайп по сенсорному экрану; Linux: свайп по тачпаду.

#События

СобытиеRustДанныеКогда
onLoadStart.on_load_startWebViewNavigationСтраница начала загружаться.
onLoad.on_loadWebViewNavigationСтраница завершила загрузку.
onError.on_error{ message, code? } (&str, сообщение)Загрузка не удалась; code равно "ERR_ACCESS_DENIED" для страницы или html, не разрешённых capabilities приложения.
onNavigationStateChange.on_navigation_state_changeWebViewNavigationИзменился URL, заголовок, состояние загрузки или история.
onMessage.on_message{ data: string } (&str)Страница вызвала window.nsh.postMessage(data).
onDownloadWebViewDownloadЗагрузка файла началась, завершилась или не удалась (macOS).

WebViewNavigation — это { url, title, loading, canGoBack, canGoForward }; в Rust — WebNavigation с url, title, loading, can_go_back и can_go_forward.

WebViewDownload — это { state, id, url, filename, path, bytes?, message? }: state равно "started", "finished" (с bytes файла) или "failed" (с его message). При наличии слушателя onDownload всё, что страница скачивает (вложение, тип, который веб-представление не отображает, ссылка download), сохраняется в каталоге данных приложения как downloads/<id>/<filename>, куда указывает path, и приложение читает файл с помощью fs/promises.

На macOS добавление слушателя позволяет любой загруженной странице, разрешённой capability webview, сохранять загрузки автоматически. Приложение отвечает за свой лимит хранилища и за удаление завершённых файлов из downloads/ после того, как они перестали использоваться. Удаление веб-представления отменяет текущие загрузки и удаляет их временные каталоги. О загрузках сообщается через onDownload; превращение навигации в загрузку оставляет onError для настоящих ошибок навигации. Из имён файлов удаляются управляющие символы и символы управления двунаправленным форматированием, а длинные имена сокращаются до 200 байт с сохранением расширения, если оно помещается.

#Методы ref

МетодRustОписание
reload()reload()Перезагружает страницу.
goBack() / goForward()go_back() / go_forward()Перемещается по истории страницы.
stopLoading()stop_loading()Останавливает загрузку.
injectJavaScript(script)inject_java_script(script)Выполняет JavaScript на странице.
postMessage(data)post_message(data)Отправляет строку странице, которая получает событие message на window.

#Обмен сообщениями

Приложение и страница обмениваются строками. Страница отправляет сообщение через window.nsh.postMessage(data); приложение отправляет через postMessage(data) у ref (post_message(..) в Rust). Для структурированных данных отправляйте JSON.

use nsh_core::prelude::*;

const PAGE: &str = r#"<!doctype html>
<meta name="viewport" content="width=device-width">
<button onclick="window.nsh.postMessage('hello from the page')">Post to the app</button>
<p id="got"></p>
<script>
  window.addEventListener("message", (e) => { document.getElementById("got").textContent = e.data; });
</script>"#;

fn bridge() -> impl IntoElement {
    let message = signal(String::new());
    let web = element_ref();
    view()
        .gap_3()
        .child(
            web_view_html(PAGE.to_string(), None)
                .element_ref(&web)
                .h(px(200.0))
                .on_message(move |data: &str| message.set(data.to_string())),
        )
        .child(
            text(move || format!("Post to the page · got: {}", message.get()))
                .on_press(move || web.post_message("hi from the app")),
        )
}

#Capabilities

Если приложение объявляет capabilities в nsh.json, веб-представление показывает страницы и переходит на хосты, перечисленные в webview. src на другом хосте или html в приложении без webview показывают пустое представление; переход верхнего уровня на другой хост (по ссылке, на которую нажал пользователь) отменяется на нативном уровне. В каждом случае сообщается onError с code "ERR_ACCESS_DENIED".

{
  "capabilities": {
    "webview": { "hosts": ["example.com", "*.example.com"] }
  }
}

#Особенности платформ

  • iOS загружает WebKit при первом создании веб-представления, поэтому приложению это обходится в ресурсы, только когда оно его показывает.
  • На macOS onDownload сохраняет загрузки средствами WebKit WKDownload.
  • На Android вызовы postMessage со страницы приходят в фоновом потоке и передаются приложению по порядку.
  • Чтобы скруглить углы веб-представления, задайте ему радиус скругления и overflow: "hidden" (.overflow_hidden()).