@zhaoxiangjun/base44-ui 项目索引

react_base44_ui 是供 Base44 React App 和本地 React 项目复用的公共 UI 组件库。

package: @zhaoxiangjun/base44-ui
registry latest: 1.6.0
working tree: 1.7.0（已确认，待发布）
target release: 1.7.0
scope: React UI components, hooks, types, frontend utilities

1. 先看哪份文档

| 目标 | 优先阅读 | | --- | --- | | AI 接手开发、快速判断怎么改 | docs/fun/ai-development-guide.md | | 查已有公共复用能力 | docs/fun/reuse-map.md | | 快速查组件、Hook、工具函数 API | docs/component-api-reference.md | | 查完整用法、行为、参数和示例 | docs/base44-usage.md | | AI 快速选型和页面模板 | docs/fun/ai-component-catalog.md | | 做项目收尾审查 | docs/fun/final-review-checklist.md | | Base44 App 使用组件 | docs/base44-usage.md | | 本地展示和验证 | docs/local-display.md | | npm 构建、打包、发布 | docs/npm-package.md | | 当前状态和维护记录 | docs/project-status.md、docs/logs/ |

2. 快速安装

{
  "dependencies": {
    "@zhaoxiangjun/base44-ui": "^1.6.0"
  }
}

registry 1.6.0 是当前可安装基线，不包含本工作树新增的表单复用 Hook 闭环和 Task 中英文默认文案。当前工作树已按维护者确认调整为待发布版本 1.7.0。

import "@zhaoxiangjun/base44-ui/styles.css";

import {
  Button,
  ConfirmDialog,
  DataTable,
  FileBrowser,
  MediaAssetCard,
  ToolPageHeader,
  ToolShell
} from "@zhaoxiangjun/base44-ui";

FontAwesome 子入口：

import {
  FontAwesomeIcon,
  ensureFontawesomeLoaded
} from "@zhaoxiangjun/base44-ui/fontawesome";

默认静态资源路径：

public/fontawesome/css/all.min.css
public/fontawesome/webfonts/*

注意：私有项目可按 FontAwesome Pro 授权策略自行托管或打包资源；但当前包是公有 npm 项目，不能随包发布 FontAwesome Pro 的 CSS、webfonts、ttf 或 woff2 文件。本包只提供 FontAwesomeIcon 和 ensureFontawesomeLoaded 包装，宿主项目自行提供 /fontawesome/css/all.min.css。

3. 项目边界

可以包含：

React UI 组件
前端展示 Hook
组件类型定义
UI 工具函数
FontAwesome / lucide-react 图标适配

不应包含：

base44.entities 调用
base44.auth 调用
base44.functions.invoke 调用
外部后端接口请求
密钥、Token、API Key
业务专属数据模型

业务请求应由使用方通过 props、callbacks、当前 App 的 src/api / src/hooks / src/lib 或 Base44 Backend Functions 接入。

4. 功能分组

Layout:
  ToolShell / ToolPageHeader / ToolButton / ToolNavItem / MobileTopBar / Surface / ScrollArea

Feedback:
  AlertDialog / ConfirmDialog / LoadingDialog / ProgressDialog / PromptDialog
  TaskStatusDialog / StatusToast / ToastProvider / useToast
  LoadingState / EmptyState / ErrorState / InlineAlert / Spinner / Skeleton / SkeletonGroup

Display:
  Avatar / AvatarGroup

File:
  FileBrowser / FilePreviewDialog / FileBreadcrumb / FileList / FileToolbar

Data / Form / Code:
  DataTable / TreeView / Field / TextField / PasswordField / Textarea
  Checkbox / RadioGroup / Switch / Select / Combobox / Autocomplete / FormSection
  DatePicker / DateRangePicker / TimePicker
  Slider / RangeSlider / Dropzone
  NumberSelectInput / NumberDropdown / CodeEditor

Navigation / Overlays:
  Tabs / Accordion / Collapsible / Stepper / Breadcrumb / Pagination
  DropdownMenu / Popover / Tooltip / Sheet / Drawer / Command Palette

Media:
  MediaAssetCard / PlaybackListItem / SlideItem / SlidesList

Task / Hooks:
  useTaskStatus / taskRunner / useControllableState / useFieldControlIds
  useKeyboardShortcut / useOutsideClick
  TASK_STATUS / TASK_PHASE / TASK_ERROR_CODE / taskText / getTaskText

Icons:
  FontAwesomeIcon / ensureFontawesomeLoaded

Primitives / Utils:
  Button / Card / Badge / Tag / Chip / Separator
  DialogFrame / DialogBody / DialogIconFrame / DialogActions
  ProgressBar / cn / format / numberOptions / fileIcons

Workspace:
  ResizablePanelGroup / ResizablePanel / ResizableHandle

5. 本地开发

npm install
npm run dev
npm run typecheck
npm run build
npm pack --dry-run

6. 修改记录

重要变更按日期记录在 docs/logs/。当前能力和维护状态见 docs/project-status.md。

AI 开发约束：

1. 先查 docs/fun/reuse-map.md，优先复用已有组件和 primitive。
2. 写代码前用 docs/component-api-reference.md 确认导出名和核心 Props，不猜测接口。
3. 不在公共 UI 包中加入业务请求、鉴权、密钥或 Base44 SDK 调用。
4. 新增用户可见文案时优先支持 locale 或由调用方传入。
5. 修改公共 API 时同步更新 src/index.ts、API 速查、完整 usage、项目状态和日志。
6. 收尾必须至少执行 npm run typecheck 和 npm run build。