HSMS 共享用户界面
一个用于HSMS应用程序的可再用React + MUI组件库,包括可配置的布局,主题工具,以及UI原始.
安装
- 时间 :
pnpm add @crystaltech/hsms-shared-ui - 线条 :
yarn add @crystaltech/hsms-shared-ui - 无 :
npm i @crystaltech/hsms-shared-ui
端口道具( 匹配您的应用程序) : @mui/material, (中文(简体) ), @mui/icons-material, (中文(简体) ), @mui/x-date-pickers, (中文(简体) ), @emotion/*, (中文(简体) ), react, (中文(简体) ), react-dom, (中文(简体) ), dayjs, (中文(简体) ), react-perfect-scrollbar, (中文(简体) ), simplebar-react。 。 。 .
用于其他模块
- 安装打字( TypeScript 项目):
pnpm add -D typescript @types/react @types/react-dom
- 配置类型脚本 :
tsconfig.json数字 :compilerOptions.jsx: "react-jsx"compilerOptions.moduleResolution: "bundler"(或"node"(中文(简体) )compilerOptions.skipLibCheck: true(可选)
- 导入组件 :
import { MainLayout, ThemeSetting, CustomButton } from '@crystaltech/hsms-shared-ui';
- 导入类型( 可选) :
import type { ITheme } from '@crystaltech/hsms-shared-ui/dist/theme/defaultTheme';import type { ILayoutConfig } from '@crystaltech/hsms-shared-ui/dist/components/layout/MainLayout';
- JavaScript 项目 :
- 启用类型建议: 添加
// @ts-check用于文件或使用 JSDoc 类型防御. - 在VS代码中确保:
javascript.suggest.autoImports财务报告和审定财务报表typescript.suggest.autoImports已启用.
- 启用类型建议: 添加
- Monorepo 链接 :
- 使用工作空间链接或
pnpm link如果自动导入建议不显示, 则重新启动 TS 服务器 .
- 使用工作空间链接或
快速启动( 主题)
包装您的应用程序 ThemeCustomization 和使用情况 ThemeSetting 以编辑并坚持主题.
import { ThemeCustomization, ThemeSetting } from "@crystaltech/hsms-shared-ui";
import { defaultTheme, ITheme } from "@crystaltech/hsms-shared-ui/dist/theme/defaultTheme";
export default function App() {
const [theme, setTheme] = useState<ITheme>(defaultTheme);
const handleSave = async (next: ITheme) => { setTheme(next); return next; };
return (
<ThemeCustomization defaultTheme={theme}>
<ThemeSetting theme={theme} onSave={handleSave} />
</ThemeCustomization>
);
}
主题模型
ITheme住在这里src/theme/defaultTheme.ts包含palette(导航、侧边、初级/中级、背景、文字、中立)和typography。 。 。 .- 使用
defaultTheme作为起点; 通过一个新的对象来重取主题.
版式
主拉尤特语Name
- 道具 :
title: string, (中文(简体) ),layoutConfig: ILayoutConfig, (中文(简体) ),logoutHandler?: () => Promise<void> ILayoutConfig数字 :userManage?: { user: UserInfo; redirectUrl: string }navbar: { showHamburgerInMobile: boolean; themeToggler: boolean }sideDrawer: { menuConfig: IMenuConfig[]; settingsConfig: ISettingsConfig; isMinimized: boolean; drawerWidth: number }footerText: string
示例
import { MainLayout } from "@crystaltech/hsms-shared-ui";
import { menuConfig, settingsConfig } from "@crystaltech/hsms-shared-ui/dist/components/layout/layoutConfig";
const layoutConfig = {
navbar: { showHamburgerInMobile: true, themeToggler: false },
sideDrawer: { menuConfig, settingsConfig, isMinimized: false, drawerWidth: 260 },
userManage: { user, redirectUrl: "/login" },
footerText: "© 2025 All rights reserved",
};
<MainLayout title="HSMS" layoutConfig={layoutConfig}>
{/* children */}
</MainLayout>
与 Wrapper 连接
- 环绕
MainLayout带有BrowserRouter。当您还没有程序根的路由器时使用.
路线
- 道具 :
pageTitle, (中文(简体) ),user, (中文(简体) ),authenticated, (中文(简体) ),userRoles?, (中文(简体) ),clients?, (中文(简体) ),loginMethod, (中文(简体) ),logoutHandler, (中文(简体) ),redirectPath?, (中文(简体) ),pages, (中文(简体) ),publicRoutes?, (中文(简体) ),Layout?, (中文(简体) ),mainLayoutConfig, (中文(简体) ),NotFoundPage?。 。 。 . - 构建从
pages并通过ProtectedRoute。 。 。 .
示例(静态页图) :
import { RoutesConfigLayout } from "@crystaltech/hsms-shared-ui";
import Home from "./pages/index";
import TablePage from "./pages/table";
const pages = {
"/src/pages/index.tsx": { default: Home },
"/src/pages/table/index.tsx": { default: TablePage, roles: ["admin"] },
} satisfies import("@crystaltech/hsms-shared-ui/dist/routes/RoutesConfigLayout").IPages;
<RoutesConfigLayout
pageTitle="HSMS"
user={user}
authenticated={isAuthenticated}
loginMethod={login}
logoutHandler={logout}
redirectPath="/login"
pages={pages}
publicRoutes={[{ path: "/about", element: <About /> }]}
mainLayoutConfig={layoutConfig}
/>
UserInfo 支持 realm_access.roles 和每个客户的作用resource_access[client].roles) (中文(简体) ). 路线级别 roles 如果提供的话, 将覆盖全球作用 .
数据表
多动态表
- 道具 :
tableData: DataStructure, (中文(简体) ),rowsPerPage: number, (中文(简体) ),page: number, (中文(简体) ),handleChangePage, (中文(简体) ),handleChangeRowsPerPage。 。 。 . - 特征:粘贴头、列能见度移动、关键词过滤器(
CustomInput(原始内容存档于2018-09-26). pagination.
类型( 强制) :
export type FieldContentActionsProps = {
label: string;
icon?: React.ReactNode;
onClick: (item: FieldItem) => void;
variant?: "outlined" | "filled";
};
export type DatePickerProps = { date: string; onChange?: (item: FieldItem, date: Date) => void };
export type FieldItem = {
id: number; // same across rows for a column
fieldName: string;
isVisible: boolean;
fieldType: "text" | "date" | "link" | "label" | "actions" | "date-picker";
fieldContent: string | DatePickerProps | FieldContentActionsProps[];
to?: string; // for link
};
export type FieldItemArray = FieldItem[];
export type DataStructure = FieldItem[][]; // rows => columns
示例数据:
import { MultiDynamicTable } from "@crystaltech/hsms-shared-ui";
import Visibility from "@mui/icons-material/Visibility";
const dynamicTableData: DataStructure = [
[
{ id: 1, fieldName: "Name", isVisible: true, fieldType: "link", fieldContent: "Alice", to: "/users/1" },
{ id: 2, fieldName: "Status", isVisible: true, fieldType: "label", fieldContent: "Active" },
{ id: 3, fieldName: "Joined", isVisible: true, fieldType: "date", fieldContent: "2025-01-01" },
{ id: 4, fieldName: "Actions", isVisible: true, fieldType: "actions", fieldContent: [
{ label: "View", icon: <Visibility />, variant: "outlined", onClick: (item) => console.log(item) },
] },
{ id: 5, fieldName: "Reminder", isVisible: true, fieldType: "date-picker", fieldContent: {
date: "2025-01-05", onChange: (item, date) => console.log(item, date)
} },
],
[
{ id: 1, fieldName: "Name", isVisible: true, fieldType: "link", fieldContent: "Bob", to: "/users/2" },
{ id: 2, fieldName: "Status", isVisible: true, fieldType: "label", fieldContent: "Inactive" },
{ id: 3, fieldName: "Joined", isVisible: true, fieldType: "date", fieldContent: "2024-12-01" },
{ id: 4, fieldName: "Actions", isVisible: true, fieldType: "actions", fieldContent: [] },
{ id: 5, fieldName: "Reminder", isVisible: true, fieldType: "date-picker", fieldContent: { date: "2025-02-01" } },
],
];
<MultiDynamicTable
tableData={dynamicTableData}
page={0}
rowsPerPage={10}
handleChangePage={(_, p) => setPage(p)}
handleChangeRowsPerPage={(e) => setRowsPerPage(parseInt(e.target.value, 10))}
/>
UI 组件
所有部件均从 src/index.ts。 。 。 .
-
自定义按钮
- 扩展 MUI
ButtonProps; 添加startIcon, (中文(简体) ),endIcon, (中文(简体) ),loading。 。 。 . loading禁用按钮并显示旋转器.
- 扩展 MUI
-
自定义Icon按钮
- MUI 上的薄膜包
IconButton总是让children图标.
- MUI 上的薄膜包
-
自定义输入
- 道具 :
startIcon?, (中文(简体) ),placeholder?, (中文(简体) ),onChange?(value), (中文(简体) ),count?, (中文(简体) ),onClear?。 。 。 . - 显示计数徽章并清空按钮.
- 道具 :
-
自定义检查框
- 道具 :
checked?, (中文(简体) ),onChange?(checked), (中文(简体) ),label?管理内部状态.
- 道具 :
-
自定义无线电组
- 道具 :
label, (中文(简体) ),options: {label,value}[], (中文(简体) ),value, (中文(简体) ),onChange(value)。 。 。 .
- 道具 :
-
自定义选择
- 道具 :
label, (中文(简体) ),value, (中文(简体) ),options: { value: string|number; label: string }[], (中文(简体) ),onChange(SelectChangeEvent)。 。 。 .
- 道具 :
-
自定义开关
- 道具 :
checked, (中文(简体) ),onChange(checked)。 。 。 .
- 道具 :
-
自定义标签
- 道具 :
tabs: {label,value}[], (中文(简体) ),value, (中文(简体) ),onChange(event,value)附加时TabsProps。 。 。 .
- 道具 :
-
自定义约会选择器
- 道具 :
label, (中文(简体) ),value: Dayjs|null, (中文(简体) ),onChange(Dayjs|null|undefined); 可清除.
- 道具 :
-
控制日期选择器
- 道具 :
label?, (中文(简体) ),initialValue?: string, (中文(简体) ),onChange?(Dayjs|null)管理自己的国家.
- 道具 :
-
自定义颜色选择器
- 道具 :
initialColor?, (中文(简体) ),onChange(color); 使用react-colorSketchPicker。 。 。 .
- 道具 :
-
自定义滚动栏
- 道具 :
children, (中文(简体) ),maxWidth?, (中文(简体) ),maxHeight?; 包装simplebar-react。 。 。 .
- 道具 :
-
自动完成
- 道具 :
label, (中文(简体) ),multiple?, (中文(简体) ),fetchOptions(), (中文(简体) ),getOptionLabel, (中文(简体) ),isOptionEqualToValue, (中文(简体) ),onChange?。 。 。 . - 获取打开时的选项; 显示加载指标 .
- 示例
<AsyncAutocomplete label="Users" fetchOptions={async () => [{ id:1, name:"Alice" }]} getOptionLabel={(o) => o.name} isOptionEqualToValue={(o,v) => o.id === v.id} onChange={(sel) => console.log(sel)} />
- 道具 :
-
复选框ListWithAvatar
- 道具 :
items: { id:number; label:string; avatarSrc? }[], (中文(简体) ),checkedItems?, (中文(简体) ),onChange(checkedIds)。 。 。 .
- 道具 :
-
自定义可选列表
- 道具 :
items: { label:string; icon? }[], (中文(简体) ),onSelect?(index);支持选择和第二个项目后的分隔符.
- 道具 :
-
装入器
- 道具 :
size?, (中文(简体) ),text?, (中文(简体) ),fullScreen?。 。 。 . - 显示带有模块标志的动画自旋器;可选的全屏覆盖.
- 道具 :
出口
import {
ThemeSetting,
ThemeCustomization,
MainLayout,
MainlayoutWithWrapper,
RoutesConfigLayout,
MultiDynamicTable,
ProfilePages,
// UI primitives
AsyncAutocomplete,
CheckboxListWithAvatar,
ControlledDatePicker,
CustomButton,
CustomCheckbox,
CustomColorPicker,
CustomDatePicker,
CustomIconButton,
CustomInput,
CustomRadioGroup,
CustomScrollbar,
CustomSelect,
CustomSelectableList,
CustomSwitch,
CustomTabs,
CustomTextField,
Loader,
} from "@crystaltech/hsms-shared-ui";
页:1
RoutesConfigLayout用途ProtectedRoute执行roles财务报告和审定财务报表clients; 路由级别roles覆盖全局.- 列能见度正在插入
MultiDynamicTable依赖共享id某一列的跨行值. - 确保对等版本的 MUI 和 React 匹配您的应用程序 .
- 参见
src/theme/defaultTheme.ts全体会议ITheme形状.
月亮喷出喷出器
防止初始白屏,并在应用初始化时显示全屏加载器.
- EME (Vite apps): 在条目文件的顶端添加
import '@crystaltech/hsms-shared-ui/preMountSplash';- 有事件或呼叫的信号生命周期
markAppReady()等准备好了.
- IIFE( 微前端主机或遗留 HTML): 在您的应用程序捆绑前包含 CDN 脚本
<script src="https://unpkg.com/@crystaltech/hsms-shared-ui/dist/preMountSplash.iife.js" crossorigin="anonymous"></script>
- 带有自定义根的可选手动输入
import { initPreMountSplash } from '@crystaltech/hsms-shared-ui/preMountSplash';initPreMountSplash({ rootId: 'portal-root' });- 在IIFE主机中,信号准备:
<script> // later in bootstrap window.HSMSPreMountSplash?.markAppReady(); // or: window.dispatchEvent(new Event('app-ready')) </script>
使用的本地密钥
- 主题:
theme.mode, (中文(简体) ),theme.themeColor - 标记 :
organization_name
PWA和CSP
- Vite PWA:无害环境管理的进口预留;CDN IIFE是外部的并首先获得网络.
- CSP: 注射器插入一个小
<style>; 允许内置样式或相应配置策略.
标准生命周期
- 添加数
app-loading类改为html在其中,将它取出并设定app-ready藏起来. - 设定
window.__APP_READY__ = true发送全局app-ready隐藏时的事件. - 隐藏应用程序的信号准备状态
hsms-app-mounted或者说app-ready。 。 。 . - 你可以按程序打电话
markAppReady()或发送日期new Event('app-ready')。 。 。 .
示例主机页面:见 examples/host.html。 。 。 .
快速启动( Splash)
- 选择集成 :
- Vite 应用程序: 添加
import '@crystaltech/hsms-shared-ui/preMountSplash'在您条目文件的顶端. - 微前端/后端:将 CDN IIFE 脚本包含在您的主机 HTML 中.
- Vite 应用程序: 添加
- 确保早日提供品牌/主题关键:
localStorage.organization_name, (中文(简体) ),localStorage.theme。 。 。 .
- 可选的手工输入和自定义根 :
initPreMountSplash({ rootId: 'portal-root' })。 。 。 .
- 应用程序挂载后的信号准备 :
- 无害环境管理:发送
hsms-app-mounted和/或电话markAppReady()。 。 。 . - 爱丽丝:
window.HSMSPreMountSplash?.markAppReady()或者说window.dispatchEvent(new Event('app-ready'))。 。 。 .
- 无害环境管理:发送
- 校验行为 :
- 第一幅画:
<html>已经app-loading而喷出物是可见的. - 准备完毕后:喷出物逐渐消失
<html>开关到app-ready。 。 。 .
- 第一幅画:
无害环境管理实例:
import '@crystaltech/hsms-shared-ui/preMountSplash';
// ... your app bootstrap (fetch config, auth, etc.)
window.dispatchEvent(new Event('hsms-app-mounted'));
window.dispatchEvent(new Event('app-ready'));
IIFE 主机示例 :
<script src="https://unpkg.com/@crystaltech/hsms-shared-ui/dist/preMountSplash.iife.js" crossorigin="anonymous"></script>
<script>
window.HSMSPreMountSplash?.initPreMountSplash({ rootId: 'portal-root' });
// after app is mounted
window.HSMSPreMountSplash?.markAppReady();
// or: window.dispatchEvent(new Event('app-ready'));
// optional: set branding early so it shows on splash
localStorage.setItem('organization_name', 'HSMS');
localStorage.setItem('theme', JSON.stringify({ mode: 'light', themeColor: '#2c5282' }));
</script>
收养清单(缩略语)
- 每个应用程序选择一个集成:无害环境管理导入(Vite)或IIFE CDN(Host HTML)——避免双入.
- 将挂载根 ID 标准化(例如,
portal-root)并通过{ rootId }始终如一. - 种子品牌/主题在登录/博客早期:
organization_name, (中文(简体) ),theme。 。 。 . - 挂载时信号准备:呼叫
markAppReady()或发送日期new Event('app-ready')。 。 。 . - CSP: 允许注入
<style>在政策. - 性能:在重捆前包括IIFE脚本;在溅出前避免屏蔽内线脚本.
- PWA:确保无害环境管理的进口预留;如果使用CDN IIFE,则验证网络倒置策略.
- QA: 验证第一次喷出、淡出和
<html>切换app-loading→app-ready。 。 。 .
最小步骤( 其他模块)
- Vite apps (ESM) (英语:
- 安装 :
pnpm add @crystaltech/hsms-shared-ui - 顶上
src/main.tsx(或src/index.ts:import '@crystaltech/hsms-shared-ui/preMountSplash' - 应用程序挂载后: 发送
hsms-app-mounted和/或电话markAppReady()。 。 。 . - 可选:设置早期品牌/主题密钥:
localStorage.setItem('organization_name', 'HSMS');
- 安装 :
反应(Vite)实例——推荐接线
// src/main.tsx
import '@crystaltech/hsms-shared-ui/preMountSplash';
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
ReactDOM.createRoot(document.getElementById('root')!).render(
<React.StrictMode>
<App />
</React.StrictMode>
);
// src/App.tsx
import { useEffect } from 'react';
import { markAppReady } from '@crystaltech/hsms-shared-ui/preMountSplash';
export default function App() {
useEffect(() => { markAppReady(); }, []);
return (
<div>Your UI</div>
);
}
- 微前端/后端主机( IIFE) :
- 在捆绑前添加脚本 :
<script src="https://unpkg.com/@crystaltech/hsms-shared-ui/dist/preMountSplash.iife.js" crossorigin="anonymous"></script> - 带有 root id 的可选输入 :
<script>window.HSMSPreMountSplash?.initPreMountSplash({ rootId: 'portal-root' });</script> - 挂载后, 信号准备 :
<script>window.HSMSPreMountSplash?.markAppReady();</script> - 可选:通过
localStorage。 。 。 .
- 在捆绑前添加脚本 :