iOS

界面跳转

更新时间: 2026/08/13 16:01:58

Swift&Objective-C 组件在 NECoreKit 组件中提供统一路由 Router,支持参数传递和回调,实现界面的跳转和模块之间的解耦。

SwiftUI 组件通过 NEChatSwiftUIRouter 将统一路由转换为 NEChatSwiftUIRoute,由应用中的 NavigationStack 响应路由状态并展示对应页面,不需要传入 UINavigationController

如何跳转

IM UIKit 任意内置界面(如单聊界面)都可以通过路由地址跳转至其他指定界面。跳转至的指定界面,可以是其他内置界面,也可以是您的应用的新增界面。

  • Swift&Objective-C 组件调用 use 方法进行界面跳转。
  • SwiftUI 调用 enqueue 方法提交路由请求。
Swift

方法原型如下:

swift    public func use(_ url: String,
               parameters: [String: Any]? = nil,
                  closure: RouteHandleCallbackClosure? = nil)
参数 类型 说明
url String 注册界面对应的跳转地址
parameters [String: Any] 传递到下个界面的参数。parameters中的导航控制器(UINavigationController)需要用户提前创建
closure RouteHandleCallbackClosure (可选)异步回调
Objective-C

方法原型如下:

Objective-C- (void)use:(NSString *)url
 parameters:(nullable NSDictionary<NSString *, id> *)parameters
    closure:(nullable RouteHandleCallbackClosure)closure;
参数 类型 说明
url NSString * _Nonnull 注册界面对应的跳转地址由于OC无法访问swift中定义的全局变量,因此OC代码中需指定具体的路由地址
parameters NSDictionary<NSString *, id> * _Nullable 传递到下个界面的参数,parameters中的导航控制器(UINavigationController)需要用户提前创建
closure ^(id _Nullable result, RouterState state, NSString *message) (可选)异步回调
SwiftUI

方法原型如下:

swift@discardableResult
public func enqueue(url: String,
                    parameters: [String: Any]? = nil,
                    completion: ((NEChatSwiftUIRouteResult) -> Void)? = nil)
    -> NEChatSwiftUIRouteRequest
参数 类型 说明
url String 注册界面对应的跳转地址,支持的地址见下文的 SwiftUI 兼容路由地址列表
parameters [String: Any]? 传递到目标页面的参数
completion (NEChatSwiftUIRouteResult) -> Void (可选)路由处理结果回调

初始化 SwiftUI Chat 组件时,需要注册兼容路由,并在 NavigationStack 宿主中消费路由请求。以下宿主示例展示下文涉及的用户信息、单聊、群聊和群设置页面:

swiftimport NEChatUIKitSwiftUI
import NEContactUIKitSwiftUI
import NETeamUIKitSwiftUI
import SwiftUI

@MainActor
final class ChatRouteStore: ObservableObject {
    @Published var route: NEChatSwiftUIRoute?

    init() {
        let router = NEChatSwiftUIRouter()
        router.onRouteRequest = { [weak self, weak router] request in
            Task { @MainActor in
                self?.route = request.route
                router?.complete(request.id)
            }
        }
        NEChatUIKitSwiftUIClient.shared.setup(
            router: router,
            registerLegacyRoutes: true
        )
    }
}

struct RootView: View {
    @StateObject private var routeStore = ChatRouteStore()

    var body: some View {
        NavigationStack {
            ContentView()
                .navigationDestination(
                    isPresented: Binding(
                        get: { routeStore.route != nil },
                        set: { if !$0 { routeStore.route = nil } }
                    )
                ) {
                    if let route = routeStore.route {
                        destination(for: route)
                    }
                }
        }
    }

    @ViewBuilder
    private func destination(for route: NEChatSwiftUIRoute) -> some View {
        let config = ChatSwiftUIConfigCenter.shared.current()
        switch route {
        case let .p2pChat(context), let .teamChat(context):
            ChatView(
                viewModel: ChatSessionViewModel(context: context, config: config)
            )
        case let .userProfile(request):
            ContactUserInfoView(
                viewModel: ContactUserInfoViewModel(
                    accountId: request.accountId,
                    isRobot: request.isRobot
                ),
                token: .normal
            )
        case let .teamSetting(teamId, _):
            NormalTeamSettingView(teamId: teamId)
        default:
            EmptyView()
        }
    }
}

NEChatSwiftUIRouter 只负责生成和分发路由状态。应用需要在 onRouteRequest 中更新 SwiftUI 导航状态,并在处理请求后调用 complete

:::

跳转至内置界面

内置界面路由地址列表

云信 IM UIKit 提供两套风格的 UI 组件库,可任意选择一种使用。

两种风格 UI 界面的路由地址相同,但对应的 page 类型不同,请按需选择实现界面跳转。

Swift&Objective-C 组件路由地址列表

基础版 UI 界面
路由地址
UIKit 定义
Page
对应界面
跳转需传入参数
imkit://contact/selector.page ContactUserSelectRouter ContactSelectedViewController 通讯录人员选择器
imkit://contact/addFriend.page ContactAddFriendRouter FindFriendViewController 添加好友界面
imkit://contact/userInfo.page ContactUserInfoPageRouter ContactUserViewController 用户信息界面 参见跳转至用户信息界面
imkit://contact/blackList.page ContactBlackListRouter BlackListViewController 黑名单界面
imkit://contact/teamList.page ContactTeamListRouter TeamListViewController 我的群组界面
imkit://contact/verifyList.page ValidationMessageRouter ValidationMessageViewController 验证消息界面
imkit://chat/p2pChat.page PushP2pChatVCRouter P2PChatViewController 单聊界面 参见 跳转至单聊界面
imkit://chat/teamChat.page PushTeamChatVCRouter TeamChatViewController 群聊界面 参见 跳转至群聊界面
imkit://team/teamSetting.page TeamSettingViewRouter TeamSettingViewController 群设置界面 参见 跳转至群聊设置界面
imkit://search/search.page SearchContactPageRouter ConversationSearchController 好友搜索界面
imkit://mine/userInfo.page MeSettingRouter PersonInfoViewController 我的个人信息界面
imkit://conversation/conversation.page ConversationPageRouter ConversationController 会话列表页
通用版 UI 界面
路由地址
UIKit 定义
Page
对应界面
跳转需传入参数
imkit://contact/selector.page ContactUserSelectRouter FunContactSelectedViewController 通讯录人员选择器
imkit://contact/addFriend.page ContactAddFriendRouter FunFindFriendViewController 添加好友界面
imkit://contact/userInfo.page ContactUserInfoPageRouter FunContactUserViewController 用户信息界面
imkit://contact/blackList.page ContactBlackListRouter FunBlackListViewController 黑名单界面
imkit://contact/teamList.page ContactTeamListRouter FunTeamListViewController 我的群组界面
imkit://contact/verifyList.page ValidationMessageRouter FunValidationMessageViewController 验证消息界面
imkit://chat/p2pChat.page PushP2pChatVCRouter FunP2PChatViewController 单聊界面
imkit://chat/teamChat.page PushTeamChatVCRouter FunTeamChatViewController 群聊界面
imkit://team/teamSetting.page TeamSettingViewRouter FunTeamSettingViewController 群设置界面
imkit://search/search.page SearchContactPageRouter FunConversationSearchController 好友搜索界面
imkit://mine/userInfo.page MeSettingRouter FunPersonInfoViewController 我的个人信息界面
imkit://conversation/conversation.page ConversationPageRouter FunConversationController 会话列表页

SwiftUI 组件路由地址列表

调用 NEChatUIKitSwiftUIClient.shared.setup(registerLegacyRoutes: true) 后,SwiftUI Chat 组件会注册以下兼容路由。路由请求会转换为 NEChatSwiftUIRoute,应用需要在 SwiftUI 导航宿主中展示对应页面。

路由地址 SwiftUI 定义 对应路由 跳转需传入参数
imkit://chat/p2pChat.page PushP2pChatVCRouter NEChatSwiftUIRoute.p2pChat conversationId;可选 titlesessionIdsessionNameanchor
imkit://chat/teamChat.page PushTeamChatVCRouter NEChatSwiftUIRoute.teamChat conversationId;可选 titlesessionIdsessionNameanchor
imkit://chat/botSubSessionList.page PushBotSubSessionListRouter NEChatSwiftUIRoute.botSubSessionList conversationIdsessionId
imkit://chat/botSubSessionChat.page PushBotSubSessionChatRouter NEChatSwiftUIRoute.botSubSessionChat conversationIdsessionId
imkit://chat/pinMessage.page PushPinMessageVCRouter NEChatSwiftUIRoute.pinMessages conversationId
imkit://chat/searchMessage.page SearchMessageRouter NEChatSwiftUIRoute.historySearch conversationId
imkit://map/location.page NERouterUrl.LocationVCRouter NEChatSwiftUIRoute.locationDetail 可选 latlnglocationTitlesubTitle
imkit://mine/userInfo.page MeSettingRouter NEChatSwiftUIRoute.userProfile
imkit://team/teamSetting.page TeamSettingViewRouter NEChatSwiftUIRoute.teamSetting teamidteamId
imkit://contact/userInfo.page ContactUserInfoPageRouter NEChatSwiftUIRoute.userProfile uid;可选 isRobot
imkit://contact/aiRobotList.page ContactAIRobotListRouter NEChatSwiftUIRoute.aiRobot
imkit://contact/createAIRobot.page ContactCreateAIRobotRouter NEChatSwiftUIRoute.aiRobot 可选 botdefaultNameautoBindQrCode
imkit://contact/robotChatCard.page ContactRobotChatCardRouter NEChatSwiftUIRoute.aiRobot bot
imkit://contact/robotNicknameEdit.page ContactRobotNicknameEditRouter NEChatSwiftUIRoute.aiRobot 可选 currentName
imkit://contact/aiRobotDetail.page ContactAIRobotDetailRouter NEChatSwiftUIRoute.aiRobot bot
imkit://contact/aiRobotConfig.page ContactAIRobotConfigRouter NEChatSwiftUIRoute.aiRobot bot
imkit://contact/aiRobotBind.page ContactAIRobotBindRouter NEChatSwiftUIRoute.aiRobot 可选 qrCodepreviousBoundAccid

内置界面跳转示例

本文主要提供基础版 UI 界面跳转的示例(使用前需提前 注册路由),若使用通用版 UI 组件接入,切换注册路由方法即可,例如将 ChatRouter.register() 替换为 ChatRouter.registerFun();ContactRouter.register() 替换为 ContactRouter.registerFun() 等。

SwiftUI 使用前需调用 NEChatUIKitSwiftUIClient.shared.setup(registerLegacyRoutes: true),并配置上文所示的 SwiftUI 导航宿主。SwiftUI 的普通风格和娱乐风格使用相同的 NEChatSwiftUIRoute,页面风格由各组件配置决定。

跳转至用户信息界面

Swift
swiftRouter.shared.use(ContactUserInfoPageRouter, parameters: ["nav": navigationController as Any, "user" : user], closure: nil)
参数 类型 说明
ContactUserInfoPageRouter String 用户信息界面的跳转地址
nav UINavigationController 导航控制器,需用户提前创建
user NEUserWithFriend 用户信息模型
closure RouteHandleCallbackClosure (可选)异步回调
Objective-C
Objective-C[[Router shared] use:ContactUserInfoPageRouter parameters:@{@"nav": navigationController, @"user": user} closure:^(id _Nullable result, RouterState state, NSString *message) {
        // 处理回调
    }];
参数 类型 说明
nav UINavigationController 导航控制器,需用户提前创建
user NEUserWithFriend 用户信息模型
closure ^(id _Nullable result, RouterState state, NSString *message) (可选)异步回调

由于 OC 无法访问 swift 中定义的全局变量,因此 OC 代码中需指定具体的路由地址,注册界面对应的跳转地址。IM UIKit 内置的路由地址见上文的 内置界面路由地址列表

:::

SwiftUI
swiftNEChatUIKitSwiftUIClient.shared.router.enqueue(
    url: ContactUserInfoPageRouter,
    parameters: ["uid": accountId]
)
参数 类型 说明
ContactUserInfoPageRouter String 用户信息界面的路由地址
uid String 用户的 IM 账号 ID

跳转至单聊界面

Swift
swiftRouter.shared.use(
        PushP2pChatVCRouter,
        parameters: ["nav": navigationController as Any,
                     "conversationId": conversationId as Any,
                     "anchor": anchor],
        closure: nil
      )
参数 类型 说明
PushP2pChatVCRouter String 单聊界面的跳转地址
nav UINavigationController 导航控制器,需用户提前创建
conversationId String 会话 id
anchor V2NIMMessage 锚点消息
closure RouteHandleCallbackClosure (可选)异步回调
Objective-C
Objective-C[[Router shared] use:PushP2pChatVCRouter parameters:@{@"nav": navigationController, @"conversationId": conversationId, @"anchor": anchor} closure:^(id _Nullable result, RouterState state, NSString *message) {
        // 处理回调
    }];
参数 类型 说明
nav UINavigationController 导航控制器,需用户提前创建
conversationId String 会话 id
anchor V2NIMMessage 锚点消息
closure ^(id _Nullable result, RouterState state, NSString *message) (可选)异步回调
SwiftUI
swiftNEChatUIKitSwiftUIClient.shared.router.enqueue(
    url: PushP2pChatVCRouter,
    parameters: [
        "conversationId": conversationId,
        "anchor": anchor
    ]
)
参数 类型 说明
PushP2pChatVCRouter String 单聊界面的路由地址
conversationId String 会话 ID
anchor V2NIMMessage (可选)锚点消息

跳转至群聊界面

Swift
swiftRouter.shared.use(
        PushTeamChatVCRouter,
        parameters: ["nav": navigationController as Any,
                     "conversationId": conversationId as Any,
                     "anchor": anchor],
        closure: nil
      )
参数 类型 说明
PushTeamChatVCRouter String 群聊界面的跳转地址
nav UINavigationController 导航控制器,需用户提前创建
conversationId String 会话 id
anchor V2NIMMessage 锚点消息
closure RouteHandleCallbackClosure (可选)异步回调
Objective-C
Objective-C[[Router shared] use:PushTeamChatVCRouter parameters:@{@"nav": navigationController, @"conversationId": conversationId, @"anchor": anchor} closure:^(id _Nullable result, RouterState state, NSString *message) {
        // 处理回调
    }];
参数 类型 说明
nav UINavigationController 导航控制器,需用户提前创建
conversationId String 会话 id
anchor V2NIMMessage 锚点消息
closure ^(id _Nullable result, RouterState state, NSString *message) (可选)异步回调

由于 OC 无法访问 swift 中定义的全局变量,因此 OC 代码中需指定具体的路由地址,注册界面对应的跳转地址。IM UIKit 内置的路由地址见上文的 内置界面路由地址列表

:::

SwiftUI
swiftNEChatUIKitSwiftUIClient.shared.router.enqueue(
    url: PushTeamChatVCRouter,
    parameters: [
        "conversationId": conversationId,
        "anchor": anchor
    ]
)
参数 类型 说明
PushTeamChatVCRouter String 群聊界面的路由地址
conversationId String 会话 ID
anchor V2NIMMessage (可选)锚点消息

跳转至群聊设置界面

Swift
swiftRouter.shared.use(TeamSettingViewRouter, parameters: ["nav": navigationController as Any, "teamid": viewmodel.sessionId], closure: nil)
参数 类型 说明
TeamSettingViewRouter String 群聊设置页的跳转地址
nav UINavigationController 导航控制器,需用户提前创建
teamid String 群组的 ID
closure RouteHandleCallbackClosure (可选)异步回调
Objective-C
Objective-C[[Router shared] use:TeamSettingViewRouter parameters:@{@"nav": navigationController, @"teamid": viewmodel.sessionId} closure:^(id _Nullable result, RouterState state, NSString *message) {
        // 处理回调
    }];
参数 类型 说明
nav UINavigationController 导航控制器,需用户提前创建
teamid NSString 群组的 ID
closure ^(id _Nullable result, RouterState state, NSString *message) (可选)异步回调

由于 OC 无法访问 swift 中定义的全局变量,因此 OC 代码中需指定具体的路由地址,注册界面对应的跳转地址。IM UIKit 内置的路由地址见上文的 内置界面路由地址列表

:::

SwiftUI
swiftNEChatUIKitSwiftUIClient.shared.router.enqueue(
    url: TeamSettingViewRouter,
    parameters: ["teamid": teamId]
)
参数 类型 说明
TeamSettingViewRouter String 群聊设置页的路由地址
teamid String 群组 ID

跳转至新增界面

IM UIKit 提供的路由能力,支持根据业务需求新增界面并实现从 IM UIKit 的内置界面跳转至新增界面。

  1. 在通过路由实现跳转前,需调用 register 方法注册新增界面的路由地址。

    方法原型如下:

    Swift
    swiftpublic func register(_ url: String, closure: @escaping RouteAsyncHandle)
    
    参数 类型 说明
    url String 注册界面对应的跳转地址
    closure ([String: Any]) -> Void 传递参数
    Objective-C
    Objective-C- (void)register:(NSString * _Nonnull)url closure:(void (^ _Nonnull)(NSDictionary<NSString *, id> * _Nonnull))closure;
    
    参数 类型 说明
    url NSString 注册界面对应的跳转地址
    closure void (^ _Nonnull)(NSDictionary<NSString *, id> * _Nonnull) 传递参数
    SwiftUI
    swift@MainActor
    final class CustomRouteStore: ObservableObject {
        @Published var message: String?
    
        init() {
            Router.shared.register("app://custom/page") { [weak self] parameters in
                Task { @MainActor in
                    self?.message = parameters["message"] as? String
                }
            }
        }
    }
    
    参数 类型 说明
    url String 新增界面对应的路由地址
    parameters [String: Any] 传递到新增界面的参数

    路由注册机制采用覆盖模式,即相同的 url,后注册的会覆盖之前注册的。

  2. 界面跳转展示。

    • Swift&Objective-C 组件调用 use 方法进行界面跳转,具体参数说明参见上文的 如何跳转
    • SwiftUI 同样调用 Router.shared.use("app://custom/page", parameters: ["message": "Hello"]) 触发已注册的闭包,再由 CustomRouteStore 驱动 NavigationStack 展示新增界面。
此文档是否对你有帮助?
有帮助
去反馈
  • 如何跳转
  • 跳转至内置界面
  • 内置界面路由地址列表
  • Swift&Objective-C 组件路由地址列表
  • 基础版 UI 界面
  • 通用版 UI 界面
  • SwiftUI 组件路由地址列表
  • 内置界面跳转示例
  • 跳转至用户信息界面
  • 跳转至单聊界面
  • 跳转至群聊界面
  • 跳转至群聊设置界面
  • 跳转至新增界面