@zhaoxiangjun/base44-document 项目索引

这是给 Base44 React App 和本地 React 项目使用的文档预览组件库。
本项目只提供浏览器端文档预览组件、Hook、类型和前端工具函数，不负责 Base44 SDK、后端接口、密钥、鉴权或业务文件存储。

package: @zhaoxiangjun/base44-document
npm: https://www.npmjs.com/package/@zhaoxiangjun/base44-document
registry latest: 1.1.0
working tree package.json: 1.2.0
release status: 1.2.0 ready for user publication

1. 先看哪份文档

| 你是谁 / 你要做什么 | 应该看 | |---------------------|--------| | Base44 App 开发者 | docs/base44-usage.md | | Base44 AI Controls / AI Agent | docs/fun/ai-development-guide.md | | 想知道组件怎么 import、props 怎么传 | docs/component-api-reference.md | | 想判断应该复用哪个公共层 | docs/fun/reuse-map.md | | 本地运行和验证组件效果 | docs/local-display.md | | 维护、构建、发布 npm 包 | docs/npm-package.md | | 查看当前项目功能与本轮修改内容 | docs/project-status.md | | 查看文档预览功能方案 | docs/fun/document-preview.md | | 执行项目收尾审查 | docs/fun/final-review-checklist.md | | 查看工程修改记录 | docs/logs/ |

2. 快速安装

Base44 App 通过 npm registry 安装，不使用 git 依赖。registry 当前的 1.1.0 不包含本工作树新增的结构化文本、搜索、安全清洗和 errorMessages 能力；1.2.0 发布后使用以下配置：

{
  "dependencies": {
    "@zhaoxiangjun/base44-document": "^1.2.0"
  }
}

发布前请按 docs/local-display.md 使用本地 file: 包验证；npm 安装命令只能在用户发布 1.2.0 后使用。

入口文件引入样式：

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

组件引入：

import { DocumentViewer, DocumentPreviewDialog } from "@zhaoxiangjun/base44-document";

更完整的组件清单、props 和示例见：

docs/base44-usage.md

3. 项目边界

可以包含：
文档类型识别
Markdown / PDF / Excel / DOCX / 结构化文本 / 代码预览组件
JSON 树视图、文本搜索、行号、复制和换行控制
Markdown 目录、代码高亮和 HTML 安全清洗
文档读取 Hook
文档预览弹窗
前端展示类型定义
包内基础按钮、弹窗和状态组件

不应该包含：
Base44 SDK 调用
业务接口地址
密钥、Token、API Key
业务专属文件模型
服务端文档转换任务
@zhaoxiangjun/base44-ui 运行依赖

业务系统负责上传、鉴权、下载链接签名和接口请求，本包只接收 File、Blob 或 URL 作为预览输入。

4. 组件分组

Viewer:
  DocumentViewer / DocumentPreviewDialog

Render Parts:
  DocumentToolbar / DocumentContent / ExcelPreview
  TextPreview / JsonTreePreview / MarkdownPreview

Internal UI:
  DocumentButton / DocumentDialogFrame / DocumentDialogTitle / DocumentDialogCloseButton
  DocumentEmptyState / DocumentErrorState / DocumentLoadingState

Hook:
  useDocumentPreview

Types:
  DocumentSource / DocumentPreviewKind / DocumentLoadState
  DocumentTextLanguage / DocumentJsonValue / DocumentHeading
  DocumentViewerProps / DocumentPreviewDialogProps

Utils:
  resolveDocumentKind / getDocumentExtension / canOpenDocumentExternally
  resolveDocumentTextLanguage / isLegacyDocDocument
  createDocumentId / isSafeDocumentUrl / openDocumentExternal / downloadDocumentSource
  getDocumentIcon / formatFileSize / resolveSizeValue
  workbookToSheets / getSheetStats
  prepareTextPreview / highlightText / findTextPreviewMatches
  renderMarkdownDocument / sanitizeDocumentHtml

Constants:
  ACCEPTED_DOCUMENT_TYPES / DEFAULT_MAX_ROWS / DEFAULT_MAX_HIGHLIGHT_CHARACTERS

5. 本地开发

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

发布 npm 前必须查看：

docs/npm-package.md

本地展示和验证组件效果见：

docs/local-display.md

当前项目功能、已实现内容和本轮修改说明见：

docs/project-status.md

AI 快速开发、精确 API 和公共复用入口：

docs/fun/ai-development-guide.md
docs/component-api-reference.md
docs/fun/reuse-map.md

6. 修改记录

所有重要调整都记录在：

docs/logs/

新增组件、修改公共 API、调整发布流程或重构公共复用逻辑时，都需要新增或更新对应日志。