@liujitcn/kratos-taro-app-core 0.0.84 → 0.0.85

package/README.md

@@ -12,6 +12,8 @@
 - 登录阶段支持 TOTP、WebAuthn 和一次性恢复码校验。
 - 公开 Base MFA 请求及通用密码弹窗、绑定面板和恢复码弹窗，供登录页与业务模块复用同一套绑定界面。
 - 接口驱动的逻辑路由、访问模式、自绘 tabBar 和稳定 `viewKey`。
+- tab 切换统一使用普通页面路由：H5 替换当前路由，微信端复用页面栈，栈满时替换栈顶，避免整栈重建。
+- runner 在编译配置中移除宿主的原生 `tabBar`，退出后恢复宿主原文件；导航按模块注册的 `viewKey` 解析物理页面，支持业务模块覆盖首页和扩展 tab。
 - 页面静态资源 export、动态资源公共路径解析，以及 H5 默认导航栏兼容框架。
 - 首页、登录、协议、WebView、启动/错误状态页面。
 - H5 与微信小程序共用的模块页面装配 runner。
@@ -28,6 +30,37 @@
 
 业务模块只能通过这些 exports 使用底座，不得相对引用 core 源码。RPC 由 `make -C frontend ts-taro-app` 生成，不能手工编辑。
 
+## 通用顶部导航
+
+所有自定义顶部导航统一使用公开组件 `KratosNavBar`，页面只提供标题和业务操作，不再定义导航高度、安全区、标题居中、按钮尺寸或微信胶囊避让。普通页与 tabBar 页的标题栏使用相同高度，按钮显隐不会改变标题位置。页面外层只维护水平与底部留白，顶部留白由组件处理；tabBar 页的导航栏还统一预留内容间距。
+
+```tsx
+import { KratosNavBar } from '@liujitcn/kratos-taro-app-core'
+
+// 普通页默认带返回，无法返回时回到首页。
+<KratosNavBar title='个人信息' />
+// tabBar 页默认不带返回，也可以不传操作按钮。
+<KratosNavBar title='首页' variant='tab' />
+<KratosNavBar
+  title='我的'
+  variant='tab'
+  action={{ icon: 'settings', label: '设置', onClick: openSettings }}
+/>
+```
+
+`back` 可显式控制返回按钮，`onBack` 可覆盖默认返回操作。`action` 包含 `label`、可选 `icon`、可选 `display` 和 `onClick`；`display` 支持 `icon`（纯图标）、`text`（纯文字）和 `both`（图标加文字），默认有图标时显示图标，否则显示文字。图标支持内置 `settings`、`read-all`、`history`，以及自定义图片地址。不传 `action` 时不渲染操作按钮。三种按钮形式共用相同高度；纯图标保持方形，文字与组合按钮按内容增宽，空间不足时省略文字。组件及 `KratosNavBarProps`、`KratosNavBarAction` 类型均从包根公开导出；业务模块应传入翻译后的标题和按钮名称。
+
+```ts
+import type { KratosNavBarAction } from '@liujitcn/kratos-taro-app-core'
+
+// 纯图标
+const iconAction: KratosNavBarAction = { icon: 'settings', label: '设置', display: 'icon', onClick: openSettings }
+// 纯文字
+const textAction: KratosNavBarAction = { label: '全部已读', display: 'text', onClick: markAllRead }
+// 图标加文字
+const combinedAction: KratosNavBarAction = { icon: 'history', label: '历史', display: 'both', onClick: openHistory }
+```
+
 ## Runner 协议
 
 模块必须同时提供运行时定义和 `./build` 导出。构建入口返回模块名称、包根目录与页面清单；runner 根据宿主的静态 `module-manifest.ts` 解析模块顺序，扫描页面并创建事务。

package/dist/runner.mjs

@@ -67,6 +67,7 @@ async function main() {
   if (options.cleanupOnly) return;
   const originalAppConfig = readFileSync(appConfigFile, "utf8");
   const manifest = JSON.parse(readFileSync(baseConfigFile, "utf8"));
+  delete manifest.tabBar;
   const modules = await loadBuildModules(hostRoot, resolve(inputDir, "module-manifest.ts"));
   const pageMap = /* @__PURE__ */ new Map();
   modules.forEach((module) => {

package/package.json

@@ -7,7 +7,7 @@
     "type": "git",
     "url": "git@github.com:liujitcn/kratos-admin.git"
   },
-  "version": "0.0.84",
+  "version": "0.0.85",
   "type": "module",
   "files": [
     "dist",

package/src/components/KratosNavBar.scss

@@ -0,0 +1,100 @@
+.kratos-nav-bar {
+  flex-shrink: 0;
+  box-sizing: border-box;
+  padding-top: calc(env(safe-area-inset-top) + 24px);
+}
+
+.kratos-nav-bar--tab {
+  margin-bottom: 16px;
+}
+
+.kratos-nav-bar__row {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  height: 76px;
+}
+
+.kratos-nav-bar__title {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  max-width: calc(100% - 190px);
+  overflow: hidden;
+  color: var(--kratos-color-text);
+  font-size: 16PX;
+  font-weight: 700;
+  line-height: 22PX;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  transform: translate(-50%, -50%);
+}
+
+.kratos-nav-bar__button {
+  display: flex;
+  flex: 0 0 76px;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  width: 76px;
+  height: 76px;
+  border: 1PX solid var(--kratos-color-border);
+  border-radius: 24px;
+  background: var(--kratos-color-surface);
+  color: var(--kratos-color-text);
+}
+
+.kratos-nav-bar__back::before {
+  width: 16px;
+  height: 16px;
+  border-left: 2PX solid var(--kratos-color-primary);
+  border-bottom: 2PX solid var(--kratos-color-primary);
+  content: '';
+  transform: rotate(45deg);
+}
+
+.kratos-nav-bar__action {
+  margin-left: auto;
+}
+
+.kratos-nav-bar__action--label {
+  flex: 0 1 auto;
+  gap: 10px;
+  min-width: 76px;
+  max-width: calc(50% - 48px);
+  width: auto;
+  padding: 0 20px;
+}
+
+.kratos-nav-bar__icon {
+  flex-shrink: 0;
+  width: 34px;
+  height: 34px;
+}
+
+.kratos-nav-bar__label {
+  min-width: 0;
+  overflow: hidden;
+  font-size: 22px;
+  line-height: 28px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.kratos-nav-bar--weapp {
+  padding-top: 44PX;
+
+  .kratos-nav-bar__row {
+    height: 88px;
+  }
+
+  /* 原生胶囊占据右侧，操作按钮与返回按钮统一放在左侧。 */
+  .kratos-nav-bar__action {
+    margin-left: 0;
+  }
+
+  .kratos-nav-bar__title {
+    max-width: calc(100% - 190px - var(--kratos-nav-bar-capsule-gap));
+  }
+}

package/src/components/KratosNavBar.tsx

@@ -0,0 +1,87 @@
+import { Image, Text, View } from '@tarojs/components'
+import Taro from '@tarojs/taro'
+import type { CSSProperties } from 'react'
+import { useI18n } from '../locales'
+import { useThemeStore } from '../stores'
+import { getMpCapsuleRightGap } from '../utils'
+import { homeTabPage } from '../utils/navigation'
+import './KratosNavBar.scss'
+
+/** KratosNavBarAction 导航栏操作按钮，统一渲染尺寸、图标与无障碍文案。 */
+export interface KratosNavBarAction {
+  /** 按钮名称，同时用作可见文字与无障碍文案。 */
+  label: string
+  /** 内置 settings、read-all、history 图标名称，或自定义图片地址。 */
+  icon?: string
+  /** 显示方式；默认有图标时显示图标，否则显示文字。 */
+  display?: 'icon' | 'text' | 'both'
+  /** 点击按钮后执行的业务操作。 */
+  onClick: () => void
+}
+
+/** KratosNavBarProps 普通页面与 tabBar 页面共用的顶部导航属性。 */
+export interface KratosNavBarProps {
+  /** 居中显示的页面标题。 */
+  title: string
+  /** 普通页面默认显示返回按钮，tabBar 页面默认隐藏返回按钮。 */
+  variant?: 'page' | 'tab'
+  /** 显式覆盖返回按钮的显隐。 */
+  back?: boolean
+  /** 可选的页面操作按钮。 */
+  action?: KratosNavBarAction
+  /** 自定义返回操作；不传时返回上一页，失败后回到首页。 */
+  onBack?: () => void
+}
+
+const iconPaths: Record<string, string> = {
+  settings:
+    '<circle cx="12" cy="12" r="3"/><path d="M19.4 15a1.6 1.6 0 0 0 .3 1.8 2 2 0 1 1-2.8 2.8 1.6 1.6 0 0 0-2.7 1.1 2 2 0 1 1-4 0 1.6 1.6 0 0 0-2.6-1.1 2 2 0 1 1-2.8-2.8A1.6 1.6 0 0 0 3 13.9a2 2 0 1 1 0-4 1.6 1.6 0 0 0 1.5-2.7 2 2 0 1 1 2.8-2.8A1.6 1.6 0 0 0 10 4.6a2 2 0 1 1 4 0 1.6 1.6 0 0 0 2.7.6 2 2 0 1 1 2.8 2.8 1.6 1.6 0 0 0-.1 2.6a2.2 2.2 0 1 1 0 4.4Z"/>',
+  'read-all': '<path d="m3 12 4 4L17 6m-5 10 9-9"/>',
+  history: '<path d="M4 6h16M4 12h16M4 18h16"/>',
+}
+
+/** KratosNavBar 统一页面标题、返回与操作按钮，并处理安全区和微信胶囊避让。 */
+export default function KratosNavBar({ title, variant = 'page', back, action, onBack }: KratosNavBarProps) {
+  const { t } = useI18n()
+  const themeStore = useThemeStore()
+  const capsuleGap = getMpCapsuleRightGap()
+  const navStyle = { '--kratos-nav-bar-capsule-gap': `${capsuleGap}px` } as CSSProperties
+  const showBack = back ?? variant === 'page'
+  const iconPath = action?.icon ? iconPaths[action.icon] : undefined
+  const color = themeStore.theme === 'light' ? '#102232' : '#e9f4f6'
+  const actionIcon = iconPath
+    ? `data:image/svg+xml;charset=utf-8,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="${color}" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round">${iconPath}</svg>`)}`
+    : action?.icon
+  const actionDisplay = action?.display ?? (actionIcon ? 'icon' : 'text')
+  const showActionIcon = !!actionIcon && actionDisplay !== 'text'
+  const showActionLabel = !actionIcon || actionDisplay !== 'icon'
+
+  /** goBack 优先执行页面返回操作，否则返回上一页并在失败时回到首页。 */
+  function goBack() {
+    if (onBack) {
+      onBack()
+      return
+    }
+    void Taro.navigateBack().catch(() => Taro.reLaunch({ url: homeTabPage }))
+  }
+
+  return (
+    <View
+      className={`kratos-nav-bar${variant === 'tab' ? ' kratos-nav-bar--tab' : ''}${process.env.TARO_ENV === 'weapp' ? ' kratos-nav-bar--weapp' : ''}`}
+      style={navStyle}
+    >
+      <View className='kratos-nav-bar__row'>
+        {showBack && (
+          <View className='kratos-nav-bar__button kratos-nav-bar__back' aria-label={t('common.action.back')} onClick={goBack} />
+        )}
+        <View className='kratos-nav-bar__title'>{title}</View>
+        {action && (
+          <View className={`kratos-nav-bar__button kratos-nav-bar__action${showActionLabel ? ' kratos-nav-bar__action--label' : ''}`} aria-label={action.label} onClick={action.onClick}>
+            {showActionIcon && <Image className='kratos-nav-bar__icon' src={actionIcon} mode='aspectFit' aria-hidden='true' />}
+            {showActionLabel && <Text className='kratos-nav-bar__label'>{action.label}</Text>}
+          </View>
+        )}
+      </View>
+    </View>
+  )
+}

package/src/index.ts

@@ -44,3 +44,6 @@ export { default as PasswordVerifyDialog } from './components/PasswordVerifyDial
 export type { PasswordVerifyDialogProps } from './components/PasswordVerifyDialog'
 export { default as KratosEmpty } from './components/KratosEmpty'
 export type { KratosEmptyProps } from './components/KratosEmpty'
+/** KratosNavBar 普通页面与 tabBar 页面共用的顶部导航栏。 */
+export { default as KratosNavBar } from './components/KratosNavBar'
+export type { KratosNavBarAction, KratosNavBarProps } from './components/KratosNavBar'

package/src/navigation.ts

@@ -197,8 +197,6 @@ const defaultMenuTitleKeys: Record<string, string> = {
 }
 
 let tabNavigationTarget: string | undefined
-const nativeTabViewKeys = ['HOME', 'PROFILE_HOME']
-const resetTabViewKeys = ['MESSAGE_INBOX']
 
 function localizedDefaultAppMenus(): AppMenu[] {
   return defaultAppMenus.map((menu) => ({
@@ -325,7 +323,7 @@ export function navigateAppView(viewKey: string, params: Record<string, string>
   navigateAppRoute(`${path}${query ? `?${query}` : ''}`)
 }
 
-/** 自绘 tab 在 H5 直接切换，微信端优先复用原生 tab 或页面栈。 */
+/** 切换自绘 tab：H5 替换路由，微信端复用页面栈，避免重建整个页面栈。 */
 function navigateTabRoute(url: string): void {
   const targetRoute = url.slice(1).split('?', 1)[0].replace(/^\/+/, '')
   const pages = getCurrentPages()
@@ -338,41 +336,17 @@ function navigateTabRoute(url: string): void {
     if (tabNavigationTarget === targetRoute) tabNavigationTarget = undefined
   }
   if (process.env.TARO_ENV === 'h5') {
-    void Taro.redirectTo({ url }).then(release, () => {
-      void Taro.reLaunch({ url }).then(release, release)
-    })
+    void Taro.redirectTo({ url }).then(release, release)
     return
   }
-  if (nativeTabViewKeys.some((viewKey) => resolveStaticView(viewKey) === targetRoute)) {
-    void Taro.switchTab({ url })
-      .then(release)
-      .catch(() => {
-        navigateTabRouteInStack(url, targetRoute, pages, currentIndex, release)
-      })
-    return
-  }
-  if (resetTabViewKeys.some((viewKey) => resolveStaticView(viewKey) === targetRoute)) {
-    void Taro.reLaunch({ url }).then(release, release)
+  const targetIndex = pages.findIndex((page) => page.route?.replace(/^\/+/, '') === targetRoute)
+  if (targetIndex >= 0 && targetIndex < currentIndex) {
+    void Taro.navigateBack({ delta: currentIndex - targetIndex }).then(release, release)
     return
   }
-  navigateTabRouteInStack(url, targetRoute, pages, currentIndex, release)
-}
-
-/** 在没有原生 tab 路由的动态菜单上复用页面栈。 */
-function navigateTabRouteInStack(
-  url: string,
-  targetRoute: string,
-  pages: ReturnType<typeof getCurrentPages>,
-  currentIndex: number,
-  release: () => void,
-): void {
-  const targetIndex = pages.findIndex((page) => page.route?.replace(/^\/+/, '') === targetRoute)
-  const navigation =
-    targetIndex >= 0 && targetIndex < currentIndex
-      ? Taro.navigateBack({ delta: currentIndex - targetIndex })
-      : Taro.navigateTo({ url })
-  void navigation.then(release).catch(() => {
-    void Taro.reLaunch({ url }).then(release, release)
+  void Taro.navigateTo({ url }).then(release, () => {
+    // 小程序页面栈满时只替换栈顶，保留其他 tab 的已加载页面。
+    void Taro.redirectTo({ url }).then(release, release)
   })
 }
 

package/src/runner.ts

@@ -69,6 +69,8 @@ async function main(): Promise<void> {
 
   const originalAppConfig = readFileSync(appConfigFile, 'utf8')
   const manifest = JSON.parse(readFileSync(baseConfigFile, 'utf8')) as AppManifest
+  // 所有宿主统一使用 KratosTabBar，原生 tab 声明会限制普通页面跳转并要求额外组件。
+  delete manifest.tabBar
   const modules = await loadBuildModules(hostRoot, resolve(inputDir, 'module-manifest.ts'))
   const pageMap = new Map<string, PageEntry>()
   modules.forEach((module) => {

package/src/styles/components.scss

@@ -105,88 +105,6 @@
   box-shadow: var(--kratos-glow);
 }
 
-/* 顶栏 */
-.k-page-nav {
-  position: relative;
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  box-sizing: border-box;
-  height: calc(88px + env(safe-area-inset-top));
-  padding-top: env(safe-area-inset-top);
-}
-.k-page-nav--weapp {
-  height: calc(88px + 44PX);
-  padding-top: 44PX;
-}
-.k-page-nav__back,
-.k-page-nav__side {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  flex: 0 0 76px;
-  width: 76px;
-  height: 76px;
-}
-.k-page-nav__back {
-  border: 1PX solid var(--kratos-color-border);
-  border-radius: 24px;
-  background: var(--kratos-color-surface);
-}
-.k-page-nav__back::before {
-  width: 16px;
-  height: 16px;
-  border-left: 2PX solid var(--kratos-color-primary);
-  border-bottom: 2PX solid var(--kratos-color-primary);
-  content: '';
-  transform: rotate(45deg);
-}
-.k-page-nav__title {
-  position: absolute;
-  left: 50%;
-  max-width: calc(100% - 190px);
-  overflow: hidden;
-  color: var(--kratos-color-text);
-  font-size: 16PX;
-  font-weight: 700;
-  text-overflow: ellipsis;
-  transform: translateX(-50%);
-  white-space: nowrap;
-}
-.k-top {
-  position: relative;
-  display: flex;
-  align-items: center;
-  /* 标题绝对居中后，流内子元素（右侧动作按钮）统一靠右排布 */
-  justify-content: flex-end;
-  gap: 16px;
-  /* weapp 原生胶囊避让：页面通过 getMpCapsuleRightGap() 写入该变量，
-     其余平台未设置时回退 0，不影响布局。 */
-  padding-right: var(--mp-capsule-gap, 0px);
-}
-/* #ifdef weapp */
-/* 双写类名提高优先级：页面级 padding 简写（如 .message-header）不得压掉导航带 */
-.k-top.k-top {
-  /* 小程序右上角是原生胶囊：操作按钮靠左，标题行与胶囊同行（同 k-page-nav--weapp 几何） */
-  justify-content: flex-start;
-  height: calc(88px + 44PX);
-  padding-top: 44PX;
-  padding-right: 0;
-}
-/* #endif */
-.k-top__title {
-  position: absolute;
-  left: 50%;
-  max-width: calc(100% - 190px);
-  overflow: hidden;
-  color: var(--kratos-color-text);
-  font-size: 16PX;
-  font-weight: 700;
-  text-overflow: ellipsis;
-  transform: translateX(-50%);
-  white-space: nowrap;
-}
-
 /* 方形图标按钮 + 角标 */
 .k-ic {
   position: relative;

package/src/views/pages/index/index.scss

@@ -9,41 +9,10 @@ page {
   background: var(--kratos-bg-gradient);
 }
 
-.home-page--weapp .home-content {
-  padding-top: 0;
-}
-
-/* 小程序端首页标题占导航带：与 k-page-nav--weapp 同几何，标题与胶囊同行 */
-.home-page--weapp .home-top {
-  box-sizing: border-box;
-  height: calc(88px + 44PX);
-  padding: 44PX 4px 0;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-}
-
-.home-page--weapp .home-top__title {
-  margin-top: 0;
-}
-
 .home-content {
   position: relative;
   z-index: 1;
-  padding: calc(env(safe-area-inset-top) + 20px) 32px 220px;
-}
-
-.home-top {
-  padding: 8px 4px 24px;
-}
-
-/* 页面大标题：与其他页面导航标题同规格，向原生导航栏看齐 */
-.home-top__title {
-  margin-top: 14px;
-  color: var(--kratos-color-text);
-  font-size: 16PX;
-  font-weight: 700;
-  text-align: center;
+  padding: 0 20px 220px;
 }
 
 .home-hero {

package/src/views/pages/index/index.tsx

@@ -5,9 +5,10 @@ import defaultLogo from '@liujitcn/kratos-taro-app-core/static/images/logo_icon.
 import { useSettingStore, useThemeStore } from '../../../stores'
 import { formatSrc } from '../../../utils'
 import './index.scss'
+import KratosNavBar from '../../../components/KratosNavBar'
 import { useI18n } from '../../../locales'
 
-/** 应用首页。 */
+/** HomePage 展示应用首页，并复用固定高度的 Tab 标题栏。 */
 export default function HomePage() {
   const { t } = useI18n()
   const themeStore = useThemeStore()
@@ -41,15 +42,13 @@ export default function HomePage() {
   ]
   return (
     <View
-      className={`home-page${process.env.TARO_ENV === 'weapp' ? ' home-page--weapp' : ''} ${
+      className={`home-page ${
         themeStore.theme === 'light' ? 'theme-light' : 'theme-dark'
       }`}
     >
       <View className='k-grid-bg' aria-hidden />
       <View className='home-content'>
-        <View className='home-top'>
-          <View className='home-top__title'>{mainTitle}</View>
-        </View>
+        <KratosNavBar title={mainTitle} variant='tab' />
 
         <View className='k-glass k-glass--lit home-hero'>
           <View className='home-hero__main'>

package/src/views/pages/login/protocal.scss

@@ -1,6 +1,6 @@
 .protocol-page {
   min-height: 100vh;
-  padding: 24px;
+  padding: 0 24px 24px;
   box-sizing: border-box;
   background: var(--kratos-bg-gradient);
 }

package/src/views/pages/login/protocal.tsx

@@ -3,7 +3,7 @@ import Taro, { useLoad } from '@tarojs/taro'
 import { useState } from 'react'
 import { useSettingStore, useThemeStore } from '../../../stores'
 import { useI18n } from '../../../locales'
-import { homeTabPage } from '../../../utils/navigation'
+import KratosNavBar from '../../../components/KratosNavBar'
 import './protocal.scss'
 
 const protocolClassMap: Record<string, string> = {
@@ -39,7 +39,7 @@ function decorateProtocolContent(html: string): string {
   )
 }
 
-/** 服务条款与隐私协议页。 */
+/** ProtocolPage 展示服务条款与隐私协议。 */
 export default function ProtocolPage() {
   const { t } = useI18n()
   const themeStore = useThemeStore()
@@ -68,18 +68,9 @@ export default function ProtocolPage() {
       })
   })
 
-  /** 返回来源页，页面栈为空时回到首页。 */
-  const onBack = () => {
-    void Taro.navigateBack({ fail: () => void Taro.reLaunch({ url: homeTabPage }) })
-  }
-
   return (
     <View className={`protocol-page ${themeStore.theme === 'light' ? 'theme-light' : 'theme-dark'}`}>
-      <View className={`k-page-nav ${process.env.TARO_ENV === 'weapp' ? 'k-page-nav--weapp' : ''}`}>
-        <View className='k-page-nav__back' aria-label={t('common.action.back')} onClick={onBack} />
-        <View className='k-page-nav__title'>{pageTitle}</View>
-        <View className='k-page-nav__side' aria-hidden />
-      </View>
+      <KratosNavBar title={pageTitle} />
       <View className='protocol-card'>
         <RichText className='protocol-content' nodes={content} />
       </View>