@onekeyfe/react-native-native-list 3.0.116 → 3.0.118

package/android/src/main/java/com/onekey/nativelist/NativeListRowView.kt

@@ -506,6 +506,7 @@ internal class NativeListRowView(
   private var checkboxUsesSelectorStyle = false
   private var iconSubduedColor = Color.rgb(141, 141, 141)
   private var visualBackdropColor = Color.WHITE
+  private var imagePlaceholderColor = "#0000000F"
   private val circleOutlineProvider = object : ViewOutlineProvider() {
     override fun getOutline(view: View, outline: Outline) {
       outline.setOval(0, 0, view.width, view.height)
@@ -914,6 +915,8 @@ internal class NativeListRowView(
     }
     iconSubduedColor = color(theme, "iconSubdued", "#00000072")
     visualBackdropColor = color(theme, "rowBackground", "#FFFFFF")
+    imagePlaceholderColor = theme?.optString("strongBackground", "#0000000F")
+      ?.takeIf(String::isNotEmpty) ?: "#0000000F"
     unreadDot.background = roundedFill(
       parseNativeListColor("#E5484D"),
       4f,
@@ -1367,6 +1370,8 @@ internal class NativeListRowView(
     leadingActionIcon.iconName = ""
     leadingActionIcon.glyphSizeDp = 24
     leadingActionIcon.setOnClickListener(null)
+    leadingActionIcon.setTag(com.facebook.react.R.id.react_test_id, null)
+    leadingActionIcon.contentDescription = null
     mainColumn.visibility = VISIBLE
     dataContainer.visibility = GONE
     dataColumns.forEach { it.visibility = GONE }
@@ -2106,6 +2111,33 @@ internal class NativeListRowView(
       ?: if (variant == "perp") 8 else 14
     setPadding(dp(horizontalPadding), dp(verticalPadding), dp(horizontalPadding), dp(verticalPadding))
 
+    item.json.optJSONObject("leadingAction")?.let { action ->
+      leadingActionIcon.visibility = VISIBLE
+      leadingActionIcon.iconName = action.optString("name")
+      leadingActionIcon.glyphSizeDp = 24
+      leadingActionIcon.tintColor = safeColor(
+        action.optString("tintColor"),
+        color(theme, "icon", "#0000009B"),
+      )
+      leadingActionIcon.isEnabled = !action.optBoolean("disabled", false)
+      leadingActionIcon.alpha = if (leadingActionIcon.isEnabled) 1f else 0.4f
+      leadingActionIcon.setTag(
+        com.facebook.react.R.id.react_test_id,
+        action.optString("testID").takeIf(String::isNotEmpty),
+      )
+      leadingActionIcon.contentDescription = action.optString("accessibilityLabel")
+      leadingActionIcon.setOnClickListener {
+        emitAction(
+          item,
+          action.optString("actionKey"),
+          null,
+          leadingActionIcon,
+          "leadingAction",
+        )
+      }
+      addView(leadingActionIcon, LayoutParams(dp(36), dp(36)).apply { marginEnd = dp(5) })
+    }
+
     val leading = JSONObject(item.json.getJSONObject("leading").toString())
     imageStyle?.optString("shape")?.takeIf(String::isNotEmpty)?.let { leading.put("shape", it) }
     imageStyle?.optString("contentFit")?.takeIf(String::isNotEmpty)?.let { contentFit ->
@@ -2463,11 +2495,12 @@ internal class NativeListRowView(
     mediaMetadataRow.gravity = Gravity.CENTER_VERTICAL
     mediaMetadataRow.addView(subtitle, weighted().apply { marginEnd = dp(8) })
     item.json.optJSONObject("networkImage")?.let { networkImage ->
-      mediaNetworkImage.visibility = VISIBLE
+      // OneKey patch: Preserve badge layout without exposing a loading/error tile.
+      // mediaNetworkImage.visibility = VISIBLE
       mediaNetworkImage.outlineProvider = circleOutlineProvider
       mediaNetworkImage.clipToOutline = true
       mediaMetadataRow.addView(mediaNetworkImage, LayoutParams(dp(14), dp(14)))
-      bindImage(networkImage, mediaNetworkImage, item.key, 2, "network")
+      bindImage(networkImage, mediaNetworkImage, item.key, 2, "network", hideUntilLoaded = true)
     }
     mainColumn.addView(mediaMetadataRow, 0)
     mainColumn.addView(titleLine, 1)
@@ -3155,11 +3188,17 @@ internal class NativeListRowView(
     val isIcon = kind == "icon"
     val cornerIconData = visual.optJSONObject("cornerIcon")
     val fallback = visual.optString("fallbackText").take(2)
-    leadingFallback.text = fallback
+    val fallbackIconData = visual.optJSONObject("fallbackIcon")
+    val handlesSourceFallback =
+      !isIcon && sources.isNotEmpty() &&
+        (visual.has("fallbackText") || fallbackIconData != null)
+    leadingFallback.text = if (handlesSourceFallback) "" else fallback
     leadingFallback.setTextColor(parseNativeListColor("#00000072"))
     val visualBackground = safeColor(
       visual.optString("backgroundColor"),
-      parseNativeListColor(if (isIcon) "#0000000F" else "#E0E0E0"),
+      // OneKey patch: Visual loading and fallback use the active list theme.
+      // parseNativeListColor(if (isIcon) "#0000000F" else "#E0E0E0"),
+      parseNativeListColor(imagePlaceholderColor),
     )
     if (!isIcon && visual.optString("backgroundColor").isNotEmpty()) {
       leadingFrame.background = roundedFill(
@@ -3168,10 +3207,11 @@ internal class NativeListRowView(
       )
     }
     leadingFallback.background = roundedFill(
-      visualBackground,
+      if (handlesSourceFallback) parseNativeListColor(imagePlaceholderColor) else visualBackground,
       cornerRadiusDp ?: leadingCornerRadius(shape, minOf(sizeDp, heightDp)),
     )
-    leadingFallback.visibility = if (!isIcon && sources.isEmpty()) VISIBLE else GONE
+    leadingFallback.visibility =
+      if (!isIcon && (sources.isEmpty() || handlesSourceFallback)) VISIBLE else GONE
     if (isIcon) {
       leadingFrame.background = GradientDrawable().apply {
         setColor(visualBackground)
@@ -3184,6 +3224,14 @@ internal class NativeListRowView(
         parseNativeListColor("#0000009B"),
       )
       leadingIcon.visibility = VISIBLE
+    } else if (sources.isEmpty() && fallbackIconData != null) {
+      leadingFallback.visibility = GONE
+      leadingIcon.iconName = fallbackIconData.optString("name")
+      leadingIcon.tintColor = safeColor(
+        fallbackIconData.optString("tintColor"),
+        parseNativeListColor("#0000009B"),
+      )
+      leadingIcon.visibility = VISIBLE
     }
     val visibleSources = sources.take(leadingImages.size)
     val tokenPair = kind == "token" && visibleSources.size > 1
@@ -3236,7 +3284,10 @@ internal class NativeListRowView(
     }
     visibleSources.forEachIndexed { index, (source, variant) ->
       val image = leadingImages[index]
-      image.visibility = VISIBLE
+      // OneKey patch: Decorative badges and source-owned fallbacks stay hidden until loaded.
+      // image.visibility = VISIBLE
+      val ownsSourceFallback = index == 0 && handlesSourceFallback
+      image.visibility = if (index > 0 || ownsSourceFallback) INVISIBLE else VISIBLE
       image.layoutParams = leadingImageLayout(
         index = index,
         count = visibleSources.size,
@@ -3273,21 +3324,32 @@ internal class NativeListRowView(
         marketLeadingUsesSourceClip = true
         image.clipToOutline = false
       }
-      val fallbackIcon = if (index == 0) visual.optJSONObject("fallbackIcon") else null
+      val fallbackIcon = if (index == 0) fallbackIconData else null
       val expectedEpoch = bindingEpoch
       bindImage(source, image, boundKey ?: "", index, variant,
-        onLoad = if (fallbackIcon == null) null else ({
-          if (bindingEpoch == expectedEpoch) { image.visibility = VISIBLE; leadingIcon.visibility = GONE }
+        onLoad = if (!ownsSourceFallback) null else ({
+          if (bindingEpoch == expectedEpoch) {
+            image.visibility = VISIBLE
+            leadingFallback.visibility = GONE
+            leadingIcon.visibility = GONE
+          }
         }),
-        onError = if (fallbackIcon == null) null else ({
+        onError = if (!ownsSourceFallback) null else ({
           if (bindingEpoch == expectedEpoch) {
             image.visibility = GONE
-            leadingFallback.visibility = GONE
-            leadingIcon.iconName = fallbackIcon.optString("name")
-            leadingIcon.tintColor = safeColor(fallbackIcon.optString("tintColor"), parseNativeListColor("#0000009B"))
-            leadingIcon.visibility = VISIBLE
+            if (fallbackIcon != null) {
+              leadingFallback.visibility = GONE
+              leadingIcon.iconName = fallbackIcon.optString("name")
+              leadingIcon.tintColor = safeColor(fallbackIcon.optString("tintColor"), parseNativeListColor("#0000009B"))
+              leadingIcon.visibility = VISIBLE
+            } else {
+              leadingIcon.visibility = GONE
+              leadingFallback.text = fallback
+              leadingFallback.visibility = VISIBLE
+            }
           }
         }),
+        hideUntilLoaded = index > 0 || ownsSourceFallback,
       )
     }
     // OneKey patch: wallet overlays retain source images, provider colors and QR text.
@@ -3310,7 +3372,7 @@ internal class NativeListRowView(
         val image = overlay.optJSONObject("image")
         val view = when {
           image != null -> OneKeyImageReusableView(reactContext).also {
-            bindImage(image, it, boundKey ?: "", 10 + index, "generic")
+            bindImage(image, it, boundKey ?: "", 10 + index, "generic", hideUntilLoaded = true)
             selectorImages.add(it)
           }
           overlay.optString("text").isNotEmpty() -> TextView(context).apply {
@@ -4057,12 +4119,26 @@ internal class NativeListRowView(
     variant: String,
     onLoad: (() -> Unit)? = null,
     onError: (() -> Unit)? = null,
+    hideUntilLoaded: Boolean = false,
     retryAttempt: Int = 0,
   ) {
     selectorImageRetries.remove(imageView)?.let(imageView::removeCallbacks)
     val expectedEpoch = bindingEpoch
     val retryLimit = source.optInt("retryTimes", 0).coerceAtLeast(0)
     val uri = source.optString("uri").trim().takeIf(String::isNotEmpty)
+    if (hideUntilLoaded) imageView.visibility = INVISIBLE
+    val handleLoad: (() -> Unit)? = if (hideUntilLoaded) ({
+      if (bindingEpoch == expectedEpoch) {
+        imageView.visibility = VISIBLE
+        onLoad?.invoke()
+      }
+    }) else onLoad
+    val handleError: (() -> Unit)? = if (hideUntilLoaded) ({
+      if (bindingEpoch == expectedEpoch) {
+        imageView.visibility = INVISIBLE
+        onError?.invoke()
+      }
+    }) else onError
     imageView.configure(
       sourceUri = uri,
       sourceHeadersJson = source.optJSONObject("headers")?.toString(),
@@ -4074,20 +4150,21 @@ internal class NativeListRowView(
       optimizeTos = retryAttempt == 0 && source.optBoolean("optimizeTos", true),
       overscan = source.optDouble("overscan", 1.1),
       loadingStrategy = source.optString("loadingStrategy", "static"),
-      onLoad = if (retryLimit == 0) onLoad else ({
+      placeholderColor = imagePlaceholderColor,
+      onLoad = if (retryLimit == 0) handleLoad else ({
         if (bindingEpoch == expectedEpoch) {
           selectorImageRetries.remove(imageView)?.let(imageView::removeCallbacks)
-          onLoad?.invoke()
+          handleLoad?.invoke()
         }
       }),
-      onError = if (retryLimit == 0) onError else ({
+      onError = if (retryLimit == 0) handleError else ({
         if (bindingEpoch == expectedEpoch) {
-          if (retryAttempt >= retryLimit) onError?.invoke()
+          if (retryAttempt >= retryLimit) handleError?.invoke()
           else if (!selectorImageRetries.containsKey(imageView)) {
             val retry = Runnable {
               if (bindingEpoch == expectedEpoch) {
                 selectorImageRetries.remove(imageView)
-                bindImage(source, imageView, token, slot, variant, onLoad, onError, retryAttempt + 1)
+                bindImage(source, imageView, token, slot, variant, onLoad, onError, hideUntilLoaded, retryAttempt + 1)
               }
             }
             selectorImageRetries[imageView] = retry

package/ios/NativeListCell.swift

@@ -1276,6 +1276,8 @@ final class NativeListCell: UICollectionViewCell {
     leadingActionButton.isHidden = true
     leadingActionButton.setImage(nil, for: .normal)
     leadingActionButton.setImage(nil, for: .disabled)
+    leadingActionButton.accessibilityIdentifier = nil
+    leadingActionButton.accessibilityLabel = nil
     unreadDot.isHidden = true
     mediaBadgeLabel.isHidden = true
     mediaBadgeLabel.text = nil
@@ -1833,7 +1835,13 @@ final class NativeListCell: UICollectionViewCell {
         let label = UILabel()
         label.font = nativeListFont(ofSize: 14)
         label.lineBreakMode = .byTruncatingTail
-        label.setContentCompressionResistancePriority(.defaultLow, for: .horizontal)
+        // Match V1: the balance may shrink, but keep the shortened address intact.
+        label.setContentCompressionResistancePriority(
+          item.data.string("presentation") == "accountSelector" && segment.bool("separatorBefore")
+            ? .defaultHigh
+            : .defaultLow,
+          for: .horizontal
+        )
         label.textColor = dataTextColor(segment.string("tone", default: "secondary"), theme: theme)
         setLineHeight(label, text: segment.string("text"), lineHeight: 20)
         let runs = segment.dictionaries("textSegments")
@@ -2312,6 +2320,28 @@ final class NativeListCell: UICollectionViewCell {
     rootTopConstraint.constant = verticalPadding
     rootBottomConstraint.constant = -verticalPadding
     rootStack.spacing = CGFloat(style?.double("leadingGap", default: variant == "perp" ? 8 : 14) ?? (variant == "perp" ? 8 : 14))
+    if let leadingAction = item.data.dictionary("leadingAction") {
+      leadingActionButton.isHidden = false
+      let tintColor = UIColor(
+        nativeListHex: leadingAction.string("tintColor", default: "#646464"),
+        fallback: .darkGray
+      )
+      leadingActionButton.tintColor = tintColor
+      if let image = nativeListIcon(named: leadingAction.string("name")) {
+        leadingActionButton.setImage(image, for: .normal)
+        leadingActionButton.setImage(
+          image.withTintColor(tintColor, renderingMode: .alwaysOriginal),
+          for: .disabled
+        )
+      }
+      leadingActionButton.isEnabled = !leadingAction.bool("disabled")
+      leadingActionButton.alpha = leadingActionButton.isEnabled ? 1 : 0.4
+      leadingActionButton.accessibilityIdentifier = leadingAction["testID"] as? String
+      leadingActionButton.accessibilityLabel = leadingAction["accessibilityLabel"] as? String
+      leadingActionKey = leadingAction.string("actionKey")
+      rootStack.addArrangedSubview(leadingActionButton)
+      rootStack.setCustomSpacing(5, after: leadingActionButton)
+    }
     leadingWidth.constant = imageWidth
     leadingHeight.constant = imageHeight
     if let visual = marketLeading(item, style: style) {
@@ -2567,13 +2597,15 @@ final class NativeListCell: UICollectionViewCell {
     subtitleLabel.setContentCompressionResistancePriority(.defaultLow, for: .horizontal)
     if let networkImage = item.data.dictionary("networkImage") {
       mediaMetadataStack.addArrangedSubview(mediaNetworkImage)
-      mediaNetworkImage.isHidden = false
+      // OneKey patch: Preserve badge layout without exposing a loading/error tile.
+      // mediaNetworkImage.isHidden = false
       bindImage(
         networkImage,
         into: mediaNetworkImage,
         token: item.key,
         slot: 2,
-        variant: "network"
+        variant: "network",
+        hideUntilLoaded: true
       )
     }
     mainStack.insertArrangedSubview(mediaMetadataStack, at: 0)
@@ -3343,14 +3375,23 @@ final class NativeListCell: UICollectionViewCell {
       default: kind == "image" || mediaHeight.isActive ? "rounded" : "circle"
     )
     let cornerIcon = visual.dictionary("cornerIcon")
-    fallbackLabel.text = String(visual.string("fallbackText").prefix(2))
+    let fallbackText = String(visual.string("fallbackText").prefix(2))
+    let fallbackIconData = visual.dictionary("fallbackIcon")
+    let handlesSourceFallback = !isIcon && !sources.isEmpty &&
+      (visual["fallbackText"] != nil || fallbackIconData != nil)
+    fallbackLabel.text = handlesSourceFallback ? nil : fallbackText
+    let sourceFallbackBackground = currentTheme?["strongBackground"] as? String ?? "#0000000F"
     leadingContainer.backgroundColor = UIColor(
-      nativeListHex: visual.string("backgroundColor", default: isIcon ? "#F0F0F0" : "#E0E0E0"),
+      // OneKey patch: Visual loading and fallback use the active list theme.
+      // nativeListHex: visual.string("backgroundColor", default: isIcon ? "#F0F0F0" : "#E0E0E0"),
+      nativeListHex: handlesSourceFallback
+        ? sourceFallbackBackground
+        : visual.string("backgroundColor", default: sourceFallbackBackground),
       fallback: .gray
     )
     leadingContainer.layer.cornerRadius = leadingCornerRadius(shape: shape)
     leadingContainer.clipsToBounds = true
-    fallbackLabel.isHidden = isIcon || !sources.isEmpty
+    fallbackLabel.isHidden = isIcon || (!sources.isEmpty && !handlesSourceFallback)
     if isIcon {
       leadingContainer.layer.borderWidth = 1 / UIScreen.main.scale
       leadingContainer.layer.borderColor = UIColor(
@@ -3364,6 +3405,15 @@ final class NativeListCell: UICollectionViewCell {
       )
       leadingIconImageView.image = nativeListIcon(named: visual.string("name"))
       leadingIconImageView.contentMode = .scaleAspectFit
+    } else if sources.isEmpty, let fallbackIconData {
+      fallbackLabel.isHidden = true
+      leadingIconImageView.isHidden = false
+      leadingIconImageView.tintColor = UIColor(
+        nativeListHex: fallbackIconData.string("tintColor", default: "#646464"),
+        fallback: .darkGray
+      )
+      leadingIconImageView.image = nativeListIcon(named: fallbackIconData.string("name"))
+      leadingIconImageView.contentMode = .scaleAspectFit
     }
     let visibleSources = Array(sources.prefix(leadingImages.count))
     let tokenPair = kind == "token" && visibleSources.count > 1
@@ -3398,7 +3448,10 @@ final class NativeListCell: UICollectionViewCell {
     }
     for (index, source) in visibleSources.enumerated() {
       let imageView = leadingImages[index]
-      imageView.isHidden = false
+      // OneKey patch: Decorative badges and source-owned fallbacks stay hidden until loaded.
+      // imageView.isHidden = false
+      let ownsSourceFallback = index == 0 && handlesSourceFallback
+      imageView.isHidden = index > 0 || ownsSourceFallback
       imageView.clipsToBounds = true
       leadingSlotConstraints.append(contentsOf: leadingConstraints(
         imageView,
@@ -3412,22 +3465,30 @@ final class NativeListCell: UICollectionViewCell {
         imageView.layer.cornerRadius = 0
         imageView.clipsToBounds = false
       }
-      let fallbackIcon = index == 0 ? visual.dictionary("fallbackIcon") : nil
+      let fallbackIcon = index == 0 ? fallbackIconData : nil
       let expectedEpoch = bindingEpoch
       bindImage(source.data, into: imageView, token: key, slot: index, variant: source.variant,
-        onLoad: fallbackIcon == nil ? nil : { [weak self, weak imageView] in
+        onLoad: !ownsSourceFallback ? nil : { [weak self, weak imageView] in
           guard let self, self.bindingEpoch == expectedEpoch else { return }
           imageView?.isHidden = false
+          self.fallbackLabel.isHidden = true
           self.leadingIconImageView.isHidden = true
         },
-        onError: fallbackIcon == nil ? nil : { [weak self, weak imageView] in
-          guard let self, self.bindingEpoch == expectedEpoch, let fallbackIcon else { return }
+        onError: !ownsSourceFallback ? nil : { [weak self, weak imageView] in
+          guard let self, self.bindingEpoch == expectedEpoch else { return }
           imageView?.isHidden = true
-          self.fallbackLabel.isHidden = true
-          self.leadingIconImageView.image = nativeListIcon(named: fallbackIcon.string("name"))
-          self.leadingIconImageView.tintColor = UIColor(nativeListHex: fallbackIcon.string("tintColor", default: "#646464"), fallback: .darkGray)
-          self.leadingIconImageView.isHidden = false
-        })
+          if let fallbackIcon {
+            self.fallbackLabel.isHidden = true
+            self.leadingIconImageView.image = nativeListIcon(named: fallbackIcon.string("name"))
+            self.leadingIconImageView.tintColor = UIColor(nativeListHex: fallbackIcon.string("tintColor", default: "#646464"), fallback: .darkGray)
+            self.leadingIconImageView.isHidden = false
+          } else {
+            self.leadingIconImageView.isHidden = true
+            self.fallbackLabel.text = fallbackText
+            self.fallbackLabel.isHidden = false
+          }
+        },
+        hideUntilLoaded: index > 0 || ownsSourceFallback)
     }
     // OneKey patch: source-derived wallet decorations may occupy both corners.
     let overlays = visual.dictionaries("overlays")
@@ -3444,7 +3505,15 @@ final class NativeListCell: UICollectionViewCell {
       let width = CGFloat(overlay.double("width", default: isWalletText ? Double(naturalTextWidth) : Double(size)))
       let frame = UIView()
       frame.translatesAutoresizingMaskIntoConstraints = false
-      frame.backgroundColor = UIColor(nativeListHex: overlay.string("backgroundColor", default: "#FFFFFF"), fallback: .clear)
+      // OneKey patch: The row theme, not a light-only white, owns badge backing.
+      // frame.backgroundColor = UIColor(nativeListHex: overlay.string("backgroundColor", default: "#FFFFFF"), fallback: .clear)
+      frame.backgroundColor = UIColor(
+        nativeListHex: overlay.string(
+          "backgroundColor",
+          default: currentTheme?["rowBackground"] as? String ?? "#00000000"
+        ),
+        fallback: .clear
+      )
       frame.layer.cornerRadius = min(width, height) / 2
       frame.clipsToBounds = true
       leadingContainer.addSubview(frame)
@@ -3459,7 +3528,14 @@ final class NativeListCell: UICollectionViewCell {
       let content: UIView
       if let image = overlay.dictionary("image") {
         let imageView = OneKeyImageReusableView(frame: .zero)
-        bindImage(image, into: imageView, token: key, slot: 10 + index, variant: "generic")
+        bindImage(
+          image,
+          into: imageView,
+          token: key,
+          slot: 10 + index,
+          variant: "generic",
+          hideUntilLoaded: true
+        )
         selectorImages.append(imageView)
         content = imageView
       } else if !overlay.string("text").isEmpty {
@@ -3919,6 +3995,7 @@ final class NativeListCell: UICollectionViewCell {
     variant: String,
     onLoad: (() -> Void)? = nil,
     onError: (() -> Void)? = nil,
+    hideUntilLoaded: Bool = false,
     retryAttempt: Int = 0
   ) {
     let imageID = ObjectIdentifier(imageView)
@@ -3933,6 +4010,17 @@ final class NativeListCell: UICollectionViewCell {
     } else {
       headersJson = nil
     }
+    if hideUntilLoaded { imageView.isHidden = true }
+    let handleLoad: (() -> Void)? = hideUntilLoaded ? { [weak self, weak imageView] in
+      guard let self, self.bindingEpoch == expectedEpoch else { return }
+      imageView?.isHidden = false
+      onLoad?()
+    } : onLoad
+    let handleError: (() -> Void)? = hideUntilLoaded ? { [weak self, weak imageView] in
+      guard let self, self.bindingEpoch == expectedEpoch else { return }
+      imageView?.isHidden = true
+      onError?()
+    } : onError
     imageView.configure(
       sourceUri: source.string("uri").trimmingCharacters(in: .whitespacesAndNewlines),
       sourceHeadersJson: headersJson,
@@ -3944,19 +4032,20 @@ final class NativeListCell: UICollectionViewCell {
       optimizeTos: retryAttempt == 0 && (source["optimizeTos"] == nil || source.bool("optimizeTos")),
       overscan: source["overscan"] == nil ? 1.1 : source.double("overscan"),
       loadingStrategy: source.string("loadingStrategy", default: "static"),
-      onLoad: retryLimit == 0 ? onLoad : { [weak self] in
+      placeholderColor: currentTheme?["strongBackground"] as? String ?? "#0000000F",
+      onLoad: retryLimit == 0 ? handleLoad : { [weak self] in
         guard let self, self.bindingEpoch == expectedEpoch else { return }
         self.selectorImageRetries.removeValue(forKey: imageID)?.cancel()
-        onLoad?()
+        handleLoad?()
       },
-      onError: retryLimit == 0 ? onError : { [weak self, weak imageView] in
+      onError: retryLimit == 0 ? handleError : { [weak self, weak imageView] in
         guard let self, self.bindingEpoch == expectedEpoch, let imageView else { return }
-        guard retryAttempt < retryLimit else { onError?(); return }
+        guard retryAttempt < retryLimit else { handleError?(); return }
         guard self.selectorImageRetries[imageID] == nil else { return }
         let retry = DispatchWorkItem { [weak self, weak imageView] in
           guard let self, self.bindingEpoch == expectedEpoch, let imageView else { return }
           self.selectorImageRetries.removeValue(forKey: imageID)
-          self.bindImage(source, into: imageView, token: token, slot: slot, variant: variant, onLoad: onLoad, onError: onError, retryAttempt: retryAttempt + 1)
+          self.bindImage(source, into: imageView, token: token, slot: slot, variant: variant, onLoad: onLoad, onError: onError, hideUntilLoaded: hideUntilLoaded, retryAttempt: retryAttempt + 1)
         }
         self.selectorImageRetries[imageID] = retry
         DispatchQueue.main.asyncAfter(deadline: .now() + Double(Int.random(in: 0...2)), execute: retry)

package/ios/RNCNativeListView.swift

@@ -248,12 +248,11 @@ final class NativeListView: UIView {
     guard let next = try? NativeListConfig.parse(json: json) else { return }
     invalidateActionAnchor(reason: "snapshot")
     if let current = config, isControlledSelectionSnapshotUpdate(from: current, to: next) {
-      let changedSummaryKeys = Set(zip(current.items, next.items).compactMap { old, new in
-        old.content != new.content ? new.key : nil
-      })
       config = next
       itemsByKey = Dictionary(uniqueKeysWithValues: next.items.map { ($0.key, $0) })
-      refreshVisibleSelection(changedSummaryKeys: changedSummaryKeys)
+      // OneKey patch: A controlled selection echo is fully handled by the
+      // lightweight updater. Rebinding unchanged visuals clears cached images.
+      refreshVisibleSelection()
       return
     }
     let oldItems = itemsByKey

package/lib/module/NativeList.js

@@ -10,6 +10,17 @@ import { applyRowPatches, serializePatches, serializeSnapshot } from "./validati
 import { jsx as _jsx } from "react/jsx-runtime";
 const NativeListConfig = require('../nitrogen/generated/shared/json/NativeListConfig.json');
 const NativeListHost = getHostComponent('NativeList', () => NativeListConfig);
+export function preloadNativeListAvatarImages(sources) {
+  return OneKeyImageCache.preload(sources.map(source => ({
+    uri: source.uri,
+    headers: source.headers,
+    resizeWidth: source.width,
+    resizeHeight: source.height,
+    optimizeTos: source.optimizeTos !== false,
+    overscan: source.overscan,
+    cachePolicy: source.cachePolicy === 'memory' ? OneKeyImageCachePolicy.MEMORY : source.cachePolicy === 'disk' ? OneKeyImageCachePolicy.DISK : OneKeyImageCachePolicy.MEMORY_DISK
+  })));
+}
 function parsePayload(payloadJson) {
   return JSON.parse(payloadJson);
 }
@@ -78,14 +89,7 @@ export const NativeList = /*#__PURE__*/forwardRef(function NativeList({
   updateAvatarPrefetchRef.current = updateAvatarPrefetch;
   useEffect(() => {
     avatarLifecycle.current = 'mounted';
-    const queue = new NativeAvatarPrefetchQueue(source => OneKeyImageCache.preload([{
-      uri: source.uri,
-      headers: source.headers,
-      resizeWidth: source.width,
-      resizeHeight: source.height,
-      optimizeTos: false,
-      cachePolicy: source.cachePolicy === 'memory' ? OneKeyImageCachePolicy.MEMORY : source.cachePolicy === 'disk' ? OneKeyImageCachePolicy.DISK : OneKeyImageCachePolicy.MEMORY_DISK
-    }]));
+    const queue = new NativeAvatarPrefetchQueue(source => preloadNativeListAvatarImages([source]));
     avatarQueueRef.current = queue;
     updateAvatarPrefetchRef.current();
     return () => {

package/lib/module/NativeList.web.js

@@ -5,7 +5,21 @@ import { View } from 'react-native';
 import { normalizeIndexScroll, normalizeKeyScroll, normalizePositionScroll, resolveLocationIndex, scrollFailure, validateOffset } from "./scrolling.js";
 import { serializePatches, validateSnapshot } from "./validation.js";
 import { NativeListWebEngine } from "./web/NativeListWebEngine.js";
+import { acquireNativeListAvatar, canonicalNativeListAvatarUri } from "./web/NativeListWebAvatarCache.js";
 import { jsx as _jsx } from "react/jsx-runtime";
+export function preloadNativeListAvatarImages(sources) {
+  if (typeof document === 'undefined') return Promise.resolve(false);
+  const uris = [...new Set(sources.map(source => canonicalNativeListAvatarUri(source.uri)).filter(uri => uri !== undefined))];
+  if (!uris.length) return Promise.resolve(false);
+  return Promise.all(uris.map(uri => new Promise(resolve => {
+    let release;
+    const settle = success => {
+      resolve(success);
+      queueMicrotask(() => release?.());
+    };
+    release = acquireNativeListAvatar(document, uri, () => settle(true), () => settle(false), 0);
+  }))).then(results => results.every(Boolean));
+}
 export const NativeList = /*#__PURE__*/forwardRef(function NativeList({
   snapshot,
   webVirtualizationEnabled = true,

package/lib/module/index.js

@@ -1,6 +1,6 @@
 "use strict";
 
-export { NativeList } from './NativeList';
+export { NativeList, preloadNativeListAvatarImages } from './NativeList';
 export { applyRowPatches, serializePatches, serializeSnapshot, validatePatches, validateSnapshot } from "./validation.js";
 export { checkboxStateForKeys, checkboxStateForSection, isSelectableRow, reduceSelection, selectionStateFromSnapshot } from "./selection.js";
 //# sourceMappingURL=index.js.map

package/lib/module/validation.js

@@ -124,6 +124,13 @@ function assertMarketRow(row, path) {
   }
   assertText(row.price, `${path}.price`);
   assertText(row.change.text, `${path}.change.text`);
+  assertTrailingAccessories(row.leadingAction ? [row.leadingAction] : undefined, `${path}.leadingAction`);
+  if (row.leadingAction) {
+    assertText(row.leadingAction.name, `${path}.leadingAction.name`);
+    if (row.leadingAction.actionKey !== undefined) {
+      assertKey(row.leadingAction.actionKey, `${path}.leadingAction.actionKey`);
+    }
+  }
   assertLeadingVisual(row.leading, `${path}.leading`);
   const assertSegments = (segments, segmentPath) => {
     segments?.forEach((segment, index) => {

package/lib/module/web/NativeListWebEngine.js

@@ -628,11 +628,32 @@ function configureWebAvatar(image, source, uri) {
   });
   webAvatarCleanup.set(image, dispose);
 }
+const WEB_IMAGE_FADE_DELAY_MS = 100;
+const WEB_IMAGE_FADE_DURATION_MS = 140;
+function webImageNow(image) {
+  return image.ownerDocument.defaultView?.performance.now() ?? Date.now();
+}
+function revealWebImage(element, startedAt) {
+  element.getAnimations?.().forEach(animation => animation.cancel());
+  element.style.opacity = '1';
+  const view = element.ownerDocument.defaultView;
+  if (webImageNow(element) - startedAt < WEB_IMAGE_FADE_DELAY_MS || view?.matchMedia?.('(prefers-reduced-motion: reduce)').matches || typeof element.animate !== 'function') return;
+  element.animate([{
+    opacity: 0
+  }, {
+    opacity: 1
+  }], {
+    duration: WEB_IMAGE_FADE_DURATION_MS,
+    easing: 'ease-out'
+  });
+}
 function createImage(context, source, className) {
   const avatarUri = canonicalNativeListAvatarUri(source.uri);
   const uri = avatarUri ?? safeImageUri(source.uri);
   if (!uri) return undefined;
   const image = context.document.createElement('img');
+  const startedAt = webImageNow(image);
+  image.style.opacity = '0';
   if (className) image.className = className;
   // OneKey patch: consume recoverable errors before the visual's final fallback listener.
   if (avatarUri) {
@@ -646,6 +667,13 @@ function createImage(context, source, className) {
   image.loading = 'lazy';
   image.decoding = 'async';
   image.style.objectFit = source.contentFit === 'fill' ? 'fill' : source.contentFit ?? 'cover';
+  image.addEventListener('load', () => {
+    if (image.dataset.nativeListSelectorPaint !== 'true') revealWebImage(image, startedAt);
+  });
+  image.addEventListener('error', () => {
+    image.style.opacity = '0';
+  });
+  image.dataset.nativeListImageStartedAt = String(startedAt);
   return image;
 }
 
@@ -655,14 +683,18 @@ function paintSelectorImageBackground(image, frame, inset = 0) {
   const paint = createElement(image.ownerDocument, 'span', 'ok-native-list-selector-image-background');
   paint.style.cssText = 'position:absolute;pointer-events:none;border-radius:inherit;background-position:center;background-repeat:no-repeat';
   paint.style.inset = String(inset) + 'px';
+  paint.style.opacity = '0';
   paint.style.backgroundSize = image.style.objectFit === 'fill' ? '100% 100%' : image.style.objectFit === 'center' ? 'auto' : image.style.objectFit;
+  image.dataset.nativeListSelectorPaint = 'true';
   image.style.opacity = '0';
   const update = () => {
     paint.style.backgroundImage = 'url(' + JSON.stringify(image.currentSrc || image.src) + ')';
+    revealWebImage(paint, Number(image.dataset.nativeListImageStartedAt) || webImageNow(image));
   };
   image.addEventListener('load', update);
   image.addEventListener('error', () => {
     paint.style.backgroundImage = 'none';
+    paint.style.opacity = '0';
   });
   frame.insertBefore(paint, image);
   if (image.complete && image.naturalWidth > 0) update();
@@ -949,8 +981,15 @@ function createVisual(context, visual, selectorPresentation) {
     frame.appendChild(fallback);
     return frame;
   }
-  if ('backgroundColor' in visual && visual.backgroundColor) frame.style.background = visual.backgroundColor;
+
+  // OneKey patch: Every image visual starts from the current theme backing.
+  // if ('backgroundColor' in visual && visual.backgroundColor)
+  //   frame.style.background = visual.backgroundColor;
+  frame.style.background = 'backgroundColor' in visual && visual.backgroundColor ? visual.backgroundColor : 'var(--nl-strong)';
   const source = visual.kind === 'image' ? visual.image : visual.image;
+  const fallbackIcon = 'fallbackIcon' in visual ? visual.fallbackIcon : undefined;
+  const handlesSourceFallback = !!source && (fallbackIcon !== undefined || 'fallbackText' in visual);
+  if (handlesSourceFallback) frame.style.background = 'var(--nl-strong)';
   const image = source ? createImage(context, source) : undefined;
   if (image) {
     image.className = 'ok-native-list-visual-main';
@@ -970,17 +1009,19 @@ function createVisual(context, visual, selectorPresentation) {
     frame.appendChild(corner);
   }
   // OneKey patch: image failure uses the same source-derived fallback as v1.
-  if ('fallbackIcon' in visual && visual.fallbackIcon) {
-    const icon = visual.fallbackIcon;
+  const hasFallbackText = 'fallbackText' in visual;
+  if (fallbackIcon || hasFallbackText) {
     const showFallback = () => {
       if (image) {
         disposeWebImageRetries(image);
         image.remove();
       }
       frame.querySelector('.ok-native-list-visual-fallback:not(.ok-native-list-visual-corner)')?.remove();
-      const fallback = createElement(context.document, 'span', 'ok-native-list-visual-fallback');
-      applySelectorIcon(fallback, icon.name);
-      if (icon.tintColor) fallback.style.color = icon.tintColor;
+      const fallback = createElement(context.document, 'span', 'ok-native-list-visual-fallback', fallbackIcon ? undefined : 'fallbackText' in visual ? visual.fallbackText ?? '' : '');
+      if (fallbackIcon) {
+        applySelectorIcon(fallback, fallbackIcon.name);
+        if (fallbackIcon.tintColor) fallback.style.color = fallbackIcon.tintColor;
+      }
       frame.prepend(fallback);
     };
     if (image) image.addEventListener('error', showFallback, {
@@ -1747,6 +1788,17 @@ function createMarketRow(context, row) {
   const layoutStyle = resolveWebMarketLayoutStyle(row);
   body.style.padding = String(layoutStyle.verticalPadding) + 'px ' + String(layoutStyle.horizontalPadding) + 'px';
   body.style.gap = '0px';
+  if (row.leadingAction) {
+    const action = createIconAction(context, row.leadingAction.name, row.leadingAction.actionKey, row.leadingAction.disabled, row.leadingAction.tintColor);
+    action.style.flex = '0 0 36px';
+    action.style.width = '36px';
+    action.style.height = '36px';
+    action.style.marginRight = '5px';
+    setData(action, 'testid', row.leadingAction.testID);
+    if (row.leadingAction.accessibilityLabel) action.setAttribute('aria-label', row.leadingAction.accessibilityLabel);
+    markActionAnchorSource(action, 'leadingAction');
+    body.appendChild(action);
+  }
   const visual = createVisual(context, row.leading);
   if (visual) {
     const width = layoutStyle.imageWidth;
@@ -1822,16 +1874,45 @@ function createMarketRow(context, row) {
     titleLine.appendChild(element);
   });
   main.appendChild(titleLine);
-  if (row.subtitle || row.subtitleSegments?.length) {
-    const subtitle = createElement(context.document, 'span', 'ok-native-list-market-subtitle', row.subtitle);
-    applyMarketTextStyle(subtitle, style?.subtitle, {
-      fontSize: 14,
-      lineHeight: 20,
-      weight: 400,
-      alignment: 'start'
-    });
-    applyValueSegments(subtitle, row.subtitleSegments, style?.subtitle?.fontSize ?? 14, style?.subtitle?.lineHeight ?? 20, marketFontWeight(style?.subtitle?.fontWeight, 400));
-    main.appendChild(subtitle);
+  if (row.subtitlePrefix || row.subtitle || row.subtitleSegments?.length) {
+    const subtitleLine = createElement(context.document, 'span', 'ok-native-list-market-subtitle-line');
+    subtitleLine.style.display = 'flex';
+    subtitleLine.style.alignItems = 'center';
+    subtitleLine.style.minWidth = '0';
+    subtitleLine.style.overflow = 'hidden';
+    subtitleLine.style.gap = String(row.subtitlePrefix ? row.subtitlePrefix.gap ?? 4 : 0) + 'px';
+    if (row.subtitlePrefix) {
+      const prefix = createElement(context.document, 'span', 'ok-native-list-market-subtitle-prefix', row.subtitlePrefix.text);
+      applyMarketTextStyle(prefix, row.subtitlePrefix.style, {
+        fontSize: 12,
+        lineHeight: 16,
+        weight: 400,
+        alignment: 'start'
+      });
+      prefix.style.display = 'block';
+      prefix.style.flex = '1 1 auto';
+      prefix.style.minWidth = '0';
+      prefix.style.overflow = 'hidden';
+      prefix.style.textOverflow = 'ellipsis';
+      prefix.style.color = row.subtitlePrefix.style?.color ?? 'var(--nl-secondary)';
+      if (row.subtitlePrefix.maxWidth !== undefined) {
+        prefix.style.maxWidth = String(row.subtitlePrefix.maxWidth) + 'px';
+      }
+      subtitleLine.appendChild(prefix);
+    }
+    if (row.subtitle || row.subtitleSegments?.length) {
+      const subtitle = createElement(context.document, 'span', 'ok-native-list-market-subtitle', row.subtitle);
+      applyMarketTextStyle(subtitle, style?.subtitle, {
+        fontSize: 14,
+        lineHeight: 20,
+        weight: 400,
+        alignment: 'start'
+      });
+      applyValueSegments(subtitle, row.subtitleSegments, style?.subtitle?.fontSize ?? 14, style?.subtitle?.lineHeight ?? 20, marketFontWeight(style?.subtitle?.fontWeight, 400));
+      subtitle.style.flex = row.subtitlePrefix ? '0 0 auto' : '1 1 auto';
+      subtitleLine.appendChild(subtitle);
+    }
+    main.appendChild(subtitleLine);
   }
   body.appendChild(main);
   const trailing = createElement(context.document, 'span', 'ok-native-list-market-trailing');

package/lib/typescript/src/NativeList.d.ts

@@ -1,7 +1,9 @@
 import React from 'react';
+import type { ImageSource } from './models';
 import type { NativeListProps } from './NativeList.types';
 export type { NativeListProps, NativeListRef } from './NativeList.types';
 export type { ActionAnchorState, ScrollAlignment, ScrollPositionOptions, ScrollToEndParams, ScrollToIndexFailedInfo, ScrollToIndexParams, ScrollToItemParams, ScrollToKeyParams, ScrollToLocationParams, ScrollToOffsetParams, } from './NativeList.types';
+export declare function preloadNativeListAvatarImages(sources: readonly ImageSource[]): Promise<boolean>;
 export declare const NativeList: React.ForwardRefExoticComponent<NativeListProps & React.RefAttributes<Readonly<{
     applySnapshot(snapshot: import("./models").NativeListSnapshot): void;
     applyPatches(patches: readonly import("./models").RowPatch[]): void;

package/lib/typescript/src/NativeList.web.d.ts

@@ -1,8 +1,9 @@
 import React from 'react';
 import type { NativeListProps } from './NativeList.types';
-import type { NativeListSnapshot, RowPatch } from './models';
+import type { ImageSource, NativeListSnapshot, RowPatch } from './models';
 export type { NativeListProps, NativeListRef } from './NativeList.types';
 export type { ActionAnchorState, ScrollAlignment, ScrollPositionOptions, ScrollToEndParams, ScrollToIndexFailedInfo, ScrollToIndexParams, ScrollToItemParams, ScrollToKeyParams, ScrollToLocationParams, ScrollToOffsetParams, } from './NativeList.types';
+export declare function preloadNativeListAvatarImages(sources: readonly ImageSource[]): Promise<boolean>;
 export declare const NativeList: React.ForwardRefExoticComponent<NativeListProps & React.RefAttributes<Readonly<{
     applySnapshot(snapshot: NativeListSnapshot): void;
     applyPatches(patches: readonly RowPatch[]): void;

package/lib/typescript/src/index.d.ts

@@ -1,4 +1,4 @@
-export { NativeList } from './NativeList';
+export { NativeList, preloadNativeListAvatarImages } from './NativeList';
 export type { ActionAnchorState, NativeListProps, NativeListRef, ScrollAlignment, ScrollPositionOptions, ScrollToEndParams, ScrollToIndexFailedInfo, ScrollToIndexParams, ScrollToItemParams, ScrollToKeyParams, ScrollToLocationParams, ScrollToOffsetParams, } from './NativeList';
 export type * from './models';
 export { applyRowPatches, serializePatches, serializeSnapshot, validatePatches, validateSnapshot, } from './validation';

package/lib/typescript/src/models.d.ts

@@ -329,6 +329,9 @@ export type DataRow = RowBase & Readonly<{
 export type MarketRow = RowBase & Readonly<{
     type: 'market';
     variant: 'token' | 'stock' | 'perp';
+    leadingAction?: Extract<TrailingAccessory, {
+        kind: 'icon';
+    }>;
     leading: LeadingVisual;
     title: string;
     subtitle?: string;
@@ -545,7 +548,7 @@ export type RowPatch = Readonly<{
 }> | Readonly<{
     type: 'market';
     key: string;
-    changes: Partial<Pick<MarketRow, CommonPatchFields | 'leading' | 'title' | 'subtitle' | 'subtitleSegments' | 'price' | 'priceSegments' | 'change' | 'badges' | 'pressActionKey' | 'pressInActionKey' | 'longPressActionKey' | 'diagnostics' | 'style'>>;
+    changes: Partial<Pick<MarketRow, CommonPatchFields | 'leadingAction' | 'leading' | 'title' | 'subtitle' | 'subtitleSegments' | 'price' | 'priceSegments' | 'change' | 'badges' | 'pressActionKey' | 'pressInActionKey' | 'longPressActionKey' | 'diagnostics' | 'style'>>;
 }> | Readonly<{
     type: 'mediaTile';
     key: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/react-native-native-list",
-  "version": "3.0.116",
+  "version": "3.0.118",
   "description": "Template-driven native RecyclerView and UICollectionView for React Native",
   "source": "./src/index.ts",
   "main": "./lib/module/index.js",
@@ -83,8 +83,8 @@
     "typescript": "^5.9.2"
   },
   "peerDependencies": {
-    "@onekeyfe/react-native-image": "3.0.116",
-    "@onekeyfe/react-native-native-logger": "3.0.116",
+    "@onekeyfe/react-native-image": "3.0.118",
+    "@onekeyfe/react-native-native-logger": "3.0.118",
     "react": "*",
     "react-native": "*",
     "react-native-nitro-modules": "0.37.0"

package/src/NativeList.tsx

@@ -20,6 +20,7 @@ import type {
 } from './NativeList.nitro';
 import type {
   ActionAnchorInvalidatedEvent,
+  ImageSource,
   RowActionEvent,
   SelectionDeltaEvent,
   ReorderEvent,
@@ -64,6 +65,27 @@ const NativeListHost = getHostComponent<
   NativeListMethods
 >('NativeList', () => NativeListConfig);
 
+export function preloadNativeListAvatarImages(
+  sources: readonly ImageSource[]
+): Promise<boolean> {
+  return OneKeyImageCache.preload(
+    sources.map((source) => ({
+      uri: source.uri,
+      headers: source.headers,
+      resizeWidth: source.width,
+      resizeHeight: source.height,
+      optimizeTos: source.optimizeTos !== false,
+      overscan: source.overscan,
+      cachePolicy:
+        source.cachePolicy === 'memory'
+          ? OneKeyImageCachePolicy.MEMORY
+          : source.cachePolicy === 'disk'
+          ? OneKeyImageCachePolicy.DISK
+          : OneKeyImageCachePolicy.MEMORY_DISK,
+    }))
+  );
+}
+
 function parsePayload<T>(payloadJson: string): T {
   return JSON.parse(payloadJson) as T;
 }
@@ -151,21 +173,7 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
     useEffect(() => {
       avatarLifecycle.current = 'mounted';
       const queue = new NativeAvatarPrefetchQueue((source) =>
-        OneKeyImageCache.preload([
-          {
-            uri: source.uri,
-            headers: source.headers,
-            resizeWidth: source.width,
-            resizeHeight: source.height,
-            optimizeTos: false,
-            cachePolicy:
-              source.cachePolicy === 'memory'
-                ? OneKeyImageCachePolicy.MEMORY
-                : source.cachePolicy === 'disk'
-                ? OneKeyImageCachePolicy.DISK
-                : OneKeyImageCachePolicy.MEMORY_DISK,
-          },
-        ])
+        preloadNativeListAvatarImages([source])
       );
       avatarQueueRef.current = queue;
       updateAvatarPrefetchRef.current();

package/src/NativeList.web.tsx

@@ -9,7 +9,7 @@ import React, {
 } from 'react';
 import { View } from 'react-native';
 import type { NativeListProps, NativeListRef } from './NativeList.types';
-import type { NativeListSnapshot, RowPatch } from './models';
+import type { ImageSource, NativeListSnapshot, RowPatch } from './models';
 import {
   normalizeIndexScroll,
   normalizeKeyScroll,
@@ -24,6 +24,10 @@ import {
   NativeListWebEngine,
   type NativeListWebCallbacks,
 } from './web/NativeListWebEngine';
+import {
+  acquireNativeListAvatar,
+  canonicalNativeListAvatarUri,
+} from './web/NativeListWebAvatarCache';
 
 export type { NativeListProps, NativeListRef } from './NativeList.types';
 export type {
@@ -39,6 +43,39 @@ export type {
   ScrollToOffsetParams,
 } from './NativeList.types';
 
+export function preloadNativeListAvatarImages(
+  sources: readonly ImageSource[]
+): Promise<boolean> {
+  if (typeof document === 'undefined') return Promise.resolve(false);
+  const uris = [
+    ...new Set(
+      sources
+        .map((source) => canonicalNativeListAvatarUri(source.uri))
+        .filter((uri): uri is string => uri !== undefined)
+    ),
+  ];
+  if (!uris.length) return Promise.resolve(false);
+  return Promise.all(
+    uris.map(
+      (uri) =>
+        new Promise<boolean>((resolve) => {
+          let release: (() => void) | undefined;
+          const settle = (success: boolean) => {
+            resolve(success);
+            queueMicrotask(() => release?.());
+          };
+          release = acquireNativeListAvatar(
+            document,
+            uri,
+            () => settle(true),
+            () => settle(false),
+            0
+          );
+        })
+    )
+  ).then((results) => results.every(Boolean));
+}
+
 export const NativeList = forwardRef<NativeListRef, NativeListProps>(
   function NativeList(
     {

package/src/index.ts

@@ -1,4 +1,4 @@
-export { NativeList } from './NativeList';
+export { NativeList, preloadNativeListAvatarImages } from './NativeList';
 export type {
   ActionAnchorState,
   NativeListProps,

package/src/models.ts

@@ -346,6 +346,7 @@ export type MarketRow = RowBase &
   Readonly<{
     type: 'market';
     variant: 'token' | 'stock' | 'perp';
+    leadingAction?: Extract<TrailingAccessory, { kind: 'icon' }>;
     leading: LeadingVisual;
     title: string;
     subtitle?: string;
@@ -667,6 +668,7 @@ export type RowPatch =
         Pick<
           MarketRow,
           | CommonPatchFields
+          | 'leadingAction'
           | 'leading'
           | 'title'
           | 'subtitle'

package/src/validation.ts

@@ -242,6 +242,16 @@ function assertMarketRow(row: MarketRow, path: string): void {
   }
   assertText(row.price, `${path}.price`);
   assertText(row.change.text, `${path}.change.text`);
+  assertTrailingAccessories(
+    row.leadingAction ? [row.leadingAction] : undefined,
+    `${path}.leadingAction`
+  );
+  if (row.leadingAction) {
+    assertText(row.leadingAction.name, `${path}.leadingAction.name`);
+    if (row.leadingAction.actionKey !== undefined) {
+      assertKey(row.leadingAction.actionKey, `${path}.leadingAction.actionKey`);
+    }
+  }
   assertLeadingVisual(row.leading, `${path}.leading`);
   const assertSegments = (
     segments: MarketRow['priceSegments'],

package/src/web/NativeListWebEngine.ts

@@ -1087,6 +1087,30 @@ function configureWebAvatar(
   webAvatarCleanup.set(image, dispose);
 }
 
+const WEB_IMAGE_FADE_DELAY_MS = 100;
+const WEB_IMAGE_FADE_DURATION_MS = 140;
+
+function webImageNow(image: HTMLImageElement): number {
+  return image.ownerDocument.defaultView?.performance.now() ?? Date.now();
+}
+
+function revealWebImage(element: HTMLElement, startedAt: number) {
+  element.getAnimations?.().forEach((animation) => animation.cancel());
+  element.style.opacity = '1';
+  const view = element.ownerDocument.defaultView;
+  if (
+    webImageNow(element as HTMLImageElement) - startedAt <
+      WEB_IMAGE_FADE_DELAY_MS ||
+    view?.matchMedia?.('(prefers-reduced-motion: reduce)').matches ||
+    typeof element.animate !== 'function'
+  )
+    return;
+  element.animate([{ opacity: 0 }, { opacity: 1 }], {
+    duration: WEB_IMAGE_FADE_DURATION_MS,
+    easing: 'ease-out',
+  });
+}
+
 function createImage(
   context: RenderContext,
   source: ImageSource,
@@ -1096,6 +1120,8 @@ function createImage(
   const uri = avatarUri ?? safeImageUri(source.uri);
   if (!uri) return undefined;
   const image = context.document.createElement('img');
+  const startedAt = webImageNow(image);
+  image.style.opacity = '0';
   if (className) image.className = className;
   // OneKey patch: consume recoverable errors before the visual's final fallback listener.
   if (avatarUri) {
@@ -1110,6 +1136,14 @@ function createImage(
   image.decoding = 'async';
   image.style.objectFit =
     source.contentFit === 'fill' ? 'fill' : source.contentFit ?? 'cover';
+  image.addEventListener('load', () => {
+    if (image.dataset.nativeListSelectorPaint !== 'true')
+      revealWebImage(image, startedAt);
+  });
+  image.addEventListener('error', () => {
+    image.style.opacity = '0';
+  });
+  image.dataset.nativeListImageStartedAt = String(startedAt);
   return image;
 }
 
@@ -1128,20 +1162,27 @@ function paintSelectorImageBackground(
   paint.style.cssText =
     'position:absolute;pointer-events:none;border-radius:inherit;background-position:center;background-repeat:no-repeat';
   paint.style.inset = String(inset) + 'px';
+  paint.style.opacity = '0';
   paint.style.backgroundSize =
     image.style.objectFit === 'fill'
       ? '100% 100%'
       : image.style.objectFit === 'center'
       ? 'auto'
       : image.style.objectFit;
+  image.dataset.nativeListSelectorPaint = 'true';
   image.style.opacity = '0';
   const update = () => {
     paint.style.backgroundImage =
       'url(' + JSON.stringify(image.currentSrc || image.src) + ')';
+    revealWebImage(
+      paint,
+      Number(image.dataset.nativeListImageStartedAt) || webImageNow(image)
+    );
   };
   image.addEventListener('load', update);
   image.addEventListener('error', () => {
     paint.style.backgroundImage = 'none';
+    paint.style.opacity = '0';
   });
   frame.insertBefore(paint, image);
   if (image.complete && image.naturalWidth > 0) update();
@@ -1516,9 +1557,19 @@ function createVisual(
     return frame;
   }
 
-  if ('backgroundColor' in visual && visual.backgroundColor)
-    frame.style.background = visual.backgroundColor;
+  // OneKey patch: Every image visual starts from the current theme backing.
+  // if ('backgroundColor' in visual && visual.backgroundColor)
+  //   frame.style.background = visual.backgroundColor;
+  frame.style.background =
+    'backgroundColor' in visual && visual.backgroundColor
+      ? visual.backgroundColor
+      : 'var(--nl-strong)';
   const source = visual.kind === 'image' ? visual.image : visual.image;
+  const fallbackIcon =
+    'fallbackIcon' in visual ? visual.fallbackIcon : undefined;
+  const handlesSourceFallback =
+    !!source && (fallbackIcon !== undefined || 'fallbackText' in visual);
+  if (handlesSourceFallback) frame.style.background = 'var(--nl-strong)';
   const image = source ? createImage(context, source) : undefined;
   if (image) {
     image.className = 'ok-native-list-visual-main';
@@ -1556,8 +1607,8 @@ function createVisual(
     frame.appendChild(corner);
   }
   // OneKey patch: image failure uses the same source-derived fallback as v1.
-  if ('fallbackIcon' in visual && visual.fallbackIcon) {
-    const icon = visual.fallbackIcon;
+  const hasFallbackText = 'fallbackText' in visual;
+  if (fallbackIcon || hasFallbackText) {
     const showFallback = () => {
       if (image) {
         disposeWebImageRetries(image);
@@ -1571,10 +1622,18 @@ function createVisual(
       const fallback = createElement(
         context.document,
         'span',
-        'ok-native-list-visual-fallback'
+        'ok-native-list-visual-fallback',
+        fallbackIcon
+          ? undefined
+          : 'fallbackText' in visual
+          ? visual.fallbackText ?? ''
+          : ''
       );
-      applySelectorIcon(fallback, icon.name);
-      if (icon.tintColor) fallback.style.color = icon.tintColor;
+      if (fallbackIcon) {
+        applySelectorIcon(fallback, fallbackIcon.name);
+        if (fallbackIcon.tintColor)
+          fallback.style.color = fallbackIcon.tintColor;
+      }
       frame.prepend(fallback);
     };
     if (image) image.addEventListener('error', showFallback, { once: true });
@@ -3123,6 +3182,24 @@ function createMarketRow(context: RenderContext, row: MarketRow): HTMLElement {
     String(layoutStyle.horizontalPadding) +
     'px';
   body.style.gap = '0px';
+  if (row.leadingAction) {
+    const action = createIconAction(
+      context,
+      row.leadingAction.name,
+      row.leadingAction.actionKey,
+      row.leadingAction.disabled,
+      row.leadingAction.tintColor
+    );
+    action.style.flex = '0 0 36px';
+    action.style.width = '36px';
+    action.style.height = '36px';
+    action.style.marginRight = '5px';
+    setData(action, 'testid', row.leadingAction.testID);
+    if (row.leadingAction.accessibilityLabel)
+      action.setAttribute('aria-label', row.leadingAction.accessibilityLabel);
+    markActionAnchorSource(action, 'leadingAction');
+    body.appendChild(action);
+  }
   const visual = createVisual(context, row.leading);
   if (visual) {
     const width = layoutStyle.imageWidth;
@@ -3236,27 +3313,67 @@ function createMarketRow(context: RenderContext, row: MarketRow): HTMLElement {
     titleLine.appendChild(element);
   });
   main.appendChild(titleLine);
-  if (row.subtitle || row.subtitleSegments?.length) {
-    const subtitle = createElement(
+  if (row.subtitlePrefix || row.subtitle || row.subtitleSegments?.length) {
+    const subtitleLine = createElement(
       context.document,
       'span',
-      'ok-native-list-market-subtitle',
-      row.subtitle
-    );
-    applyMarketTextStyle(subtitle, style?.subtitle, {
-      fontSize: 14,
-      lineHeight: 20,
-      weight: 400,
-      alignment: 'start',
-    });
-    applyValueSegments(
-      subtitle,
-      row.subtitleSegments,
-      style?.subtitle?.fontSize ?? 14,
-      style?.subtitle?.lineHeight ?? 20,
-      marketFontWeight(style?.subtitle?.fontWeight, 400)
-    );
-    main.appendChild(subtitle);
+      'ok-native-list-market-subtitle-line'
+    );
+    subtitleLine.style.display = 'flex';
+    subtitleLine.style.alignItems = 'center';
+    subtitleLine.style.minWidth = '0';
+    subtitleLine.style.overflow = 'hidden';
+    subtitleLine.style.gap =
+      String(row.subtitlePrefix ? row.subtitlePrefix.gap ?? 4 : 0) + 'px';
+    if (row.subtitlePrefix) {
+      const prefix = createElement(
+        context.document,
+        'span',
+        'ok-native-list-market-subtitle-prefix',
+        row.subtitlePrefix.text
+      );
+      applyMarketTextStyle(prefix, row.subtitlePrefix.style, {
+        fontSize: 12,
+        lineHeight: 16,
+        weight: 400,
+        alignment: 'start',
+      });
+      prefix.style.display = 'block';
+      prefix.style.flex = '1 1 auto';
+      prefix.style.minWidth = '0';
+      prefix.style.overflow = 'hidden';
+      prefix.style.textOverflow = 'ellipsis';
+      prefix.style.color =
+        row.subtitlePrefix.style?.color ?? 'var(--nl-secondary)';
+      if (row.subtitlePrefix.maxWidth !== undefined) {
+        prefix.style.maxWidth = String(row.subtitlePrefix.maxWidth) + 'px';
+      }
+      subtitleLine.appendChild(prefix);
+    }
+    if (row.subtitle || row.subtitleSegments?.length) {
+      const subtitle = createElement(
+        context.document,
+        'span',
+        'ok-native-list-market-subtitle',
+        row.subtitle
+      );
+      applyMarketTextStyle(subtitle, style?.subtitle, {
+        fontSize: 14,
+        lineHeight: 20,
+        weight: 400,
+        alignment: 'start',
+      });
+      applyValueSegments(
+        subtitle,
+        row.subtitleSegments,
+        style?.subtitle?.fontSize ?? 14,
+        style?.subtitle?.lineHeight ?? 20,
+        marketFontWeight(style?.subtitle?.fontWeight, 400)
+      );
+      subtitle.style.flex = row.subtitlePrefix ? '0 0 auto' : '1 1 auto';
+      subtitleLine.appendChild(subtitle);
+    }
+    main.appendChild(subtitleLine);
   }
   body.appendChild(main);
   const trailing = createElement(