界面跳转
更新时间: 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 public func use(_ url: String,
parameters: [String: Any]? = nil,
closure: RouteHandleCallbackClosure? = nil)
| 参数 | 类型 | 说明 |
|---|---|---|
url |
String | 注册界面对应的跳转地址
|
parameters |
[String: Any] | 传递到下个界面的参数。parameters中的导航控制器(UINavigationController)需要用户提前创建 |
closure |
RouteHandleCallbackClosure | (可选)异步回调 |
方法原型如下:
Objective-C- (void)use:(NSString *)url
parameters:(nullable NSDictionary<NSString *, id> *)parameters
closure:(nullable RouteHandleCallbackClosure)closure;
| 参数 | 类型 | 说明 |
|---|---|---|
url |
NSString * _Nonnull | 注册界面对应的跳转地址
|
parameters |
NSDictionary<NSString *, id> * _Nullable | 传递到下个界面的参数,parameters中的导航控制器(UINavigationController)需要用户提前创建 |
closure |
^(id _Nullable result, RouterState state, NSString *message) | (可选)异步回调 |
方法原型如下:
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;可选 title、sessionId、sessionName、anchor |
| imkit://chat/teamChat.page | PushTeamChatVCRouter |
NEChatSwiftUIRoute.teamChat |
conversationId;可选 title、sessionId、sessionName、anchor |
| imkit://chat/botSubSessionList.page | PushBotSubSessionListRouter |
NEChatSwiftUIRoute.botSubSessionList |
conversationId、sessionId |
| imkit://chat/botSubSessionChat.page | PushBotSubSessionChatRouter |
NEChatSwiftUIRoute.botSubSessionChat |
conversationId、sessionId |
| imkit://chat/pinMessage.page | PushPinMessageVCRouter |
NEChatSwiftUIRoute.pinMessages |
conversationId |
| imkit://chat/searchMessage.page | SearchMessageRouter |
NEChatSwiftUIRoute.historySearch |
conversationId |
| imkit://map/location.page | NERouterUrl.LocationVCRouter |
NEChatSwiftUIRoute.locationDetail |
可选 lat、lng、locationTitle、subTitle |
| imkit://mine/userInfo.page | MeSettingRouter |
NEChatSwiftUIRoute.userProfile |
无 |
| imkit://team/teamSetting.page | TeamSettingViewRouter |
NEChatSwiftUIRoute.teamSetting |
teamid 或 teamId |
| imkit://contact/userInfo.page | ContactUserInfoPageRouter |
NEChatSwiftUIRoute.userProfile |
uid;可选 isRobot |
| imkit://contact/aiRobotList.page | ContactAIRobotListRouter |
NEChatSwiftUIRoute.aiRobot |
无 |
| imkit://contact/createAIRobot.page | ContactCreateAIRobotRouter |
NEChatSwiftUIRoute.aiRobot |
可选 bot、defaultName、autoBindQrCode |
| 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 |
可选 qrCode、previousBoundAccid |
内置界面跳转示例
本文主要提供基础版 UI 界面跳转的示例(使用前需提前 注册路由),若使用通用版 UI 组件接入,切换注册路由方法即可,例如将 ChatRouter.register() 替换为 ChatRouter.registerFun();ContactRouter.register() 替换为 ContactRouter.registerFun() 等。
SwiftUI 使用前需调用 NEChatUIKitSwiftUIClient.shared.setup(registerLegacyRoutes: true),并配置上文所示的 SwiftUI 导航宿主。SwiftUI 的普通风格和娱乐风格使用相同的 NEChatSwiftUIRoute,页面风格由各组件配置决定。
跳转至用户信息界面
swiftRouter.shared.use(ContactUserInfoPageRouter, parameters: ["nav": navigationController as Any, "user" : user], closure: nil)
| 参数 | 类型 | 说明 |
|---|---|---|
ContactUserInfoPageRouter |
String | 用户信息界面的跳转地址 |
nav |
UINavigationController | 导航控制器,需用户提前创建 |
user |
NEUserWithFriend | 用户信息模型 |
closure |
RouteHandleCallbackClosure | (可选)异步回调 |
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 内置的路由地址见上文的 内置界面路由地址列表。
:::
swiftNEChatUIKitSwiftUIClient.shared.router.enqueue(
url: ContactUserInfoPageRouter,
parameters: ["uid": accountId]
)
| 参数 | 类型 | 说明 |
|---|---|---|
ContactUserInfoPageRouter |
String | 用户信息界面的路由地址 |
uid |
String | 用户的 IM 账号 ID |
跳转至单聊界面
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[[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) | (可选)异步回调 |
swiftNEChatUIKitSwiftUIClient.shared.router.enqueue(
url: PushP2pChatVCRouter,
parameters: [
"conversationId": conversationId,
"anchor": anchor
]
)
| 参数 | 类型 | 说明 |
|---|---|---|
PushP2pChatVCRouter |
String | 单聊界面的路由地址 |
conversationId |
String | 会话 ID |
anchor |
V2NIMMessage | (可选)锚点消息 |
跳转至群聊界面
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[[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 内置的路由地址见上文的 内置界面路由地址列表。
:::
swiftNEChatUIKitSwiftUIClient.shared.router.enqueue(
url: PushTeamChatVCRouter,
parameters: [
"conversationId": conversationId,
"anchor": anchor
]
)
| 参数 | 类型 | 说明 |
|---|---|---|
PushTeamChatVCRouter |
String | 群聊界面的路由地址 |
conversationId |
String | 会话 ID |
anchor |
V2NIMMessage | (可选)锚点消息 |
跳转至群聊设置界面
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[[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 内置的路由地址见上文的 内置界面路由地址列表。
:::
swiftNEChatUIKitSwiftUIClient.shared.router.enqueue(
url: TeamSettingViewRouter,
parameters: ["teamid": teamId]
)
| 参数 | 类型 | 说明 |
|---|---|---|
TeamSettingViewRouter |
String | 群聊设置页的路由地址 |
teamid |
String | 群组 ID |
跳转至新增界面
IM UIKit 提供的路由能力,支持根据业务需求新增界面并实现从 IM UIKit 的内置界面跳转至新增界面。
-
在通过路由实现跳转前,需调用
register方法注册新增界面的路由地址。方法原型如下:
Swiftswiftpublic func register(_ url: String, closure: @escaping RouteAsyncHandle)参数 类型 说明 urlString 注册界面对应的跳转地址 closure([String: Any]) -> Void 传递参数 Objective-CObjective-C- (void)register:(NSString * _Nonnull)url closure:(void (^ _Nonnull)(NSDictionary<NSString *, id> * _Nonnull))closure;参数 类型 说明 urlNSString 注册界面对应的跳转地址 closurevoid (^ _Nonnull)(NSDictionary<NSString *, id> * _Nonnull) 传递参数 SwiftUIswift@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 } } } }参数 类型 说明 urlString 新增界面对应的路由地址 parameters[String: Any] 传递到新增界面的参数 路由注册机制采用覆盖模式,即相同的 url,后注册的会覆盖之前注册的。
-
界面跳转展示。
- Swift&Objective-C 组件调用
use方法进行界面跳转,具体参数说明参见上文的 如何跳转。 - SwiftUI 同样调用
Router.shared.use("app://custom/page", parameters: ["message": "Hello"])触发已注册的闭包,再由CustomRouteStore驱动NavigationStack展示新增界面。
- Swift&Objective-C 组件调用




