@crystaltech/hsms-shared-ui

中文文档
0.8.2发布于 2026/11/14TypeScriptESM + CJS近 30 天下载 1959

一个用于HSMS应用程序的可再用React + MUI组件库,包括可配置的布局,主题工具,以及UI原始.

中文使用文档
文档目录17 节
  1. 安装
  2. 用于其他模块
  3. 快速启动( 主题)
  4. 主题模型
  5. 版式
  6. 主拉尤特语Name
  7. 与 Wrapper 连接
  8. 路线
  9. 数据表
  10. 多动态表
  11. UI 组件
  12. 出口
  13. 页:1
  14. 月亮喷出喷出器
  15. 快速启动( Splash)
  16. 收养清单(缩略语)
  17. 最小步骤( 其他模块)

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 禁用按钮并显示旋转器.
  • 自定义Icon按钮

    • MUI 上的薄膜包 IconButton 总是让 children 图标.
  • 自定义输入

    • 道具 : 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-color SketchPicker。 。 。 .
  • 自定义滚动栏

    • 道具 : 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 中.
  • 确保早日提供品牌/主题关键:
    • 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) (英语:
    1. 安装 : pnpm add @crystaltech/hsms-shared-ui
    2. 顶上 src/main.tsx (或 src/index.ts: import '@crystaltech/hsms-shared-ui/preMountSplash'
    3. 应用程序挂载后: 发送 hsms-app-mounted 和/或电话 markAppReady()。 。 。 .
    4. 可选:设置早期品牌/主题密钥: 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) :
    1. 在捆绑前添加脚本 : <script src="https://unpkg.com/@crystaltech/hsms-shared-ui/dist/preMountSplash.iife.js" crossorigin="anonymous"></script>
    2. 带有 root id 的可选输入 : <script>window.HSMSPreMountSplash?.initPreMountSplash({ rootId: 'portal-root' });</script>
    3. 挂载后, 信号准备 : <script>window.HSMSPreMountSplash?.markAppReady();</script>
    4. 可选:通过 localStorage。 。 。 .

版本与发布记录

@crystaltech/hsms-shared-ui 共发布 246 个版本,首次发布于 2025/02/24;过去 12 个月发布了 130 个版本。

版本发布日期距今
0.8.2latest2026/11/141 天前
0.8.12026/11/133 天前
0.8.02026/11/133 天前
0.7.292026/11/0114 天前
0.7.282026/10/2818 天前
0.7.272026/10/121 个月前

其他发布通道:alpha → 0.7.18-alpha.1。

关于 @crystaltech/hsms-shared-ui 的常见问题

@crystaltech/hsms-shared-ui 是什么?

一个用于HSMS应用程序的可再用React + MUI组件库,包括可配置的布局,主题工具,以及UI原始.

如何安装 @crystaltech/hsms-shared-ui?

在项目目录运行 npm install @crystaltech/hsms-shared-ui,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:dayjs(^1.11.0)、react(>=19 <20)、react-dom(>=19 <20)、@mui/system(^6.0.0)、@mui/material(^6.0.0)、@emotion/react(^11.0.0)、@emotion/styled(^11.0.0)、react-router-dom(>=6 <8)、@mui/icons-material(^6.0.0)、@mui/x-date-pickers(^7.25.0)、react-perfect-scrollbar(^1.5.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@crystaltech/hsms-shared-ui 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@crystaltech/hsms-shared-ui 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@crystaltech/hsms-shared-ui 可以商用吗?

@crystaltech/hsms-shared-ui 使用 未声明 许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利,商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括,不构成法律意见,请以许可原文为准。

@crystaltech/hsms-shared-ui 的下载量有多少?

根据 npm 官方下载统计,@crystaltech/hsms-shared-ui 在 2026/10/11 – 2026/11/09 这 30 天内被下载 1,959 次,日均约 65 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@crystaltech/hsms-shared-ui 还在维护吗?

最新版本 0.8.2 发布于 2026/11/14(1 天前);至今共发布 246 个版本,其中过去 12 个月发布了 130 个;首次发布于 2025/02/24。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。