Sparkling
  • 中文

      • 容器

      Sparkling 内容始终运行在原生容器中 — 一个承载 Lynx 运行时的平台视图。SDK 提供两种容器模式以适配不同场景。

      两种容器模式

      全页容器嵌入式容器
      是什么独立的页面（UIViewController / Activity），自带导航栏、状态栏和生命周期管理普通视图（UIView / FrameLayout），由你放入现有原生布局中
      典型场景标准页面导航卡片、Banner、局部面板，或任何混合原生与 Lynx UI 的页面
      iOS 类名SPKViewController（通过 SPKRouter）SPKContainerView
      Android 类名SparklingActivity（通过 Sparkling.navigate()）SparklingView（通过 Sparkling.createView()）

      全页容器

      全页容器是展示 Sparkling 内容的默认方式。原生层管理导航栏、状态栏、屏幕方向和加载/错误视图 — 通过 Scheme 参数配置。

      iOS

      // 方式 A：push 到已有的导航栈
SPKRouter.open(withURL: "hybrid://lynxview_page?bundle=detail.lynx.bundle&title=Detail", context: nil)

// 方式 B：自行创建和管理 VC
let vc = SPKRouter.create(withURL: url, context: SPKContext())
navigationController.pushViewController(vc, animated: true)

      Android

      val ctx = SparklingContext().apply {
  scheme = "hybrid://lynxview_page?bundle=detail.lynx.bundle&title=Detail"
}
Sparkling.build(this, ctx).navigate()   // 启动 SparklingActivity

      通过 Scheme 配置

      全页容器通过 URL 查询参数配置。常用参数：

      参数效果
      title导航栏标题
      hide_nav_bar=1隐藏导航栏
      hide_status_bar=1隐藏状态栏
      trans_status_bar=1透明状态栏（内容延伸到状态栏下方）
      show_nav_bar_in_trans_status_bar=1透明状态栏模式下仍显示导航栏
      nav_bar_color导航栏背景色
      container_bg_color容器背景色

      完整参数列表请参阅 Scheme。

      嵌入式容器

      嵌入式容器让你将 Sparkling 内容放置在原生布局的任意位置。你控制 frame，容器在其中渲染 Lynx 内容。

      iOS — SPKContainerView

      // 1. 创建并添加到视图层级
let spkView = SPKContainerView(frame: containerView.bounds)
spkView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
containerView.addSubview(spkView)

// 2. 加载 bundle
let context = SPKContext()
spkView.load(withURL: "hybrid://lynxview?bundle=card.lynx.bundle", context)

      内容尺寸（iOS）

      默认情况下，容器保持其指定的 frame。设置 sparkContentMode 可让容器根据 Lynx 内容自动调整大小：

      模式行为
      FixedSize（默认）容器保持 frame；Lynx 内容填充其中。
      FixedWidth宽度固定；高度随内容自适应。
      FixedHeight高度固定；宽度随内容自适应。
      FitSize宽高均随内容自适应。

      加载完成后，可读取 preferredLayoutSize 获取内容的固有尺寸。

      Android — SparklingView

      // 1. 通过 Sparkling builder 创建
val ctx = SparklingContext().apply {
  scheme = "hybrid://lynxview?bundle=card.lynx.bundle"
}
val spkView = Sparkling.build(this, ctx).createView()

// 2. 添加到布局并加载
container.addView(spkView)
spkView?.loadUrl()

      生命周期

      全页容器

      生命周期自动管理。SPKViewController / SparklingActivity 会将 viewDidAppear / onResume 和 viewDidDisappear / onPause 转发给 Lynx 运行时。无需额外操作。

      嵌入式容器

      由于 SDK 无法控制你的宿主 ViewController 或 Fragment，你必须手动转发可见性事件。如果忽略这一步，Lynx 运行时将无法正确暂停定时器、动画或网络请求。

      iOS：

      override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    spkView.handleViewDidAppear()
}

override func viewDidDisappear(_ animated: Bool) {
    super.viewDidDisappear(animated)
    spkView.handleViewDidDisappear()
}

      Android：

      // Fragment.onResume 或视图变为可见时
spkView?.onShowEvent()

// Fragment.onPause 或视图变为不可见时
spkView?.onHideEvent()

// 永久销毁视图时
spkView?.release()

      生命周期回调（iOS）

      在 SPKContext 上设置 containerLifecycleDelegate 以监听加载状态。两种容器模式均适用：

      context.containerLifecycleDelegate = self

// 主要回调：
func container(_ container: SPKContainerProtocol,
               didFinishLoadWithURL url: URL?) { /* 加载成功 */ }
func container(_ container: SPKContainerProtocol,
               didLoadFailedWithURL url: URL?, error: Error?) { /* 加载失败 */ }
func containerDidFirstScreen(_ container: SPKContainerProtocol) { /* 首屏渲染 */ }

      与 Lynx 通信

      两种容器模式都支持在运行时发送事件和更新 globalProps。

      发送事件

      iOS（两种模式）：

      spkView.send(event: "refresh", params: ["key": "value"], callback: nil)

      Android（嵌入式）：

      spkView?.sendEventByJSON("refresh", JSONObject().put("key", "value"))

      更新 globalProps

      iOS（两种模式）：

      spkView.update(withGlobalProps: ["theme": "dark"])

      Android（嵌入式）：

      spkView?.updateGlobalPropsByIncrement(mapOf("theme" to "dark"))

      下一步