@robsun/keystone-web-core

Keystone 平台前端核心包，提供平台级路由、页面与基础能力（登录、组织与权限、审批、任务中心、通知、设置、帮助中心）。

安装

pnpm add @robsun/keystone-web-core

依赖要求

该包使用以下 peerDependencies：

• react ^19.2.0
• react-dom ^19.2.0
• react-router-dom ^7.10.1
• antd ^6.0.1
• @ant-design/icons ^6.1.0

核心依赖（已内置）：

• i18next ^24.2.3 - 国际化框架
• react-i18next ^15.5.1 - React 国际化绑定
• i18next-browser-languagedetector ^8.0.4 - 浏览器语言检测

最小接入

1. vite.config.ts

import { createKeystoneViteConfig } from '@robsun/keystone-web-core/vite'

export default createKeystoneViteConfig({
  server: {
    port: 3000,
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
      },
    },
  },
})

2. src/app.config.ts

import type { KeystoneWebConfig } from '@robsun/keystone-web-core'

export const appConfig: Partial<KeystoneWebConfig> = {
  brand: {
    name: 'Keystone',
    shortName: 'KS',
    appName: 'Keystone',
    platformName: 'Keystone 平台',
  },
  approval: {
    businessTypes: [{ value: 'general', label: '通用流程' }],
  },
}

3. src/main.tsx

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import dayjs from 'dayjs'
import 'dayjs/locale/zh-cn'
import { KeystoneApp, getKeystoneConfig, setKeystoneConfig } from '@robsun/keystone-web-core'
import { appConfig } from './app.config'
import '@robsun/keystone-web-core/styles/keystone.css'

setKeystoneConfig(appConfig)
dayjs.locale(getKeystoneConfig().ui?.locale?.dayjs ?? 'zh-cn')

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <KeystoneApp />
  </StrictMode>
)

配置项说明（KeystoneWebConfig）

• brand：品牌名、Logo、平台名等
• auth：登录/恢复密码页文案
• dashboard：仪表盘标题与指标
• approval：审批业务类型映射（value/label）
• modules：模块开关（默认启用 keystone）
• help：帮助中心开关
• ui：Ant Design 主题与本地化
  • theme：Ant Design 主题配置
  • locale：dayjs 本地化配置
  • i18n：多语言配置
    • defaultLocale：默认语言（默认 'zh-CN'）
    • supportedLocales：支持的语言列表（默认 ['zh-CN', 'en-US']）
    • fallbackLocale：回退语言（默认 'zh-CN'）
    • persistKey：本地存储键名（默认 'ks-language'）
    • detection：是否自动检测浏览器语言（默认 true）

多语言支持

Keystone 内置中英文双语支持，默认语言为中文。所有 UI 文案、表单验证消息、系统提示均支持国际化。

支持的语言

• zh-CN - 简体中文（默认）
• en-US - 英语

语言配置

在 app.config.ts 中配置语言选项：

export const appConfig: Partial<KeystoneWebConfig> = {
  brand: {
    name: 'Keystone',
    // ...
  },
  ui: {
    i18n: {
      defaultLocale: 'zh-CN',                    // 默认语言
      supportedLocales: ['zh-CN', 'en-US'],      // 支持的语言
      fallbackLocale: 'zh-CN',                   // 回退语言（翻译缺失时使用）
      persistKey: 'ks-language',                 // localStorage 存储键名
      detection: true,                           // 自动检测浏览器语言
    },
  },
}

语言切换

用户可通过界面右上角的语言切换器选择语言，选择会自动保存到浏览器本地存储（localStorage）。下次访问时会自动应用上次选择的语言。

翻译覆盖范围

• 认证模块：登录、密码恢复
• 系统管理：用户、角色、部门、权限管理
• 审批中心：流程配置、工作台、记录查询
• 通知中心：通知列表、详情
• 帮助中心：搜索、导航
• 通用组件：表单验证、数据导入导出、确认对话框
• 错误消息：所有系统错误提示

帮助中心文档

默认读取包内 src/modules/keystone/help 的 Markdown。若要覆盖：

createKeystoneViteConfig({
  helpDir: './src/help',
})

样式

必须引入预构建样式：

import '@robsun/keystone-web-core/styles/keystone.css'

若需重新构建样式（仅维护者使用）：

pnpm -C packages/keystone-web-core styles:build

发布（维护者）

发布到 npmjs.org（预发布会自动生成 dist）：

npm login
pnpm -C packages/keystone-web-core publish --no-git-checks