@4399ywkf/editor 0.4.3 → 0.5.0

package/README.md

@@ -36,11 +36,95 @@ Univer sheets 核心 gzip 后 871KB；无条件打进主包会直接毁掉阅读
 ```ts
 import { NotionEditor, ArticleViewer } from "@4399ywkf/editor/doc"
 import { ImportDocx, ExportDocx } from "@4399ywkf/editor/docx"
+import { downloadXlsx } from "@4399ywkf/editor/xlsx"
 import { SheetView } from "@4399ywkf/editor/sheet"
 import { PdfView } from "@4399ywkf/editor/pdf"
 import "@4399ywkf/editor/styles"
 ```
 
+## 表格通道配置
+
+Univer 的 UI 是 `univer-` 前缀的原子类，没有稳定选择器 —— **别用 CSS 硬藏工具栏**。
+开关走 `sheet` 这个 prop，直接透传到 Univer preset：
+
+```tsx
+<DocumentView
+  format="sheet"
+  content={snapshot}
+  readOnly
+  sheet={{
+    findReplace: true,                       // Ctrl+F 查找替换
+    ui: { footer: true, formulaBar: false }, // 底栏保留（多表切换靠它），公式栏收掉
+  }}
+/>
+```
+
+`ui` 可用：`header` / `toolbar` / `ribbonType` / `footer` / `formulaBar` / `contextMenu` /
+`statusBarStatistic` / `menu`。
+
+- **`readOnly` 时 `toolbar` 默认为 `false`** —— 整条 ribbon 在只读预览里全是死按钮，
+  窄面板里还挤。要它回来就显式传 `ui: { toolbar: true }`。
+- `footer` 别随手关：多工作表时它是唯一的切表入口，关掉用户就只看得见第一张表。
+- `findReplace` 不需要额外装包：`preset-sheets-find-replace` 是 `@univerjs/presets`
+  自己的 dependency，走子路径动态 import，没开就完全不下载。
+
+其它能力（筛选、排序、条件格式、图片……）自己 import preset 传进来。
+`createUniver` **不会**自动收集 preset 自带的 locales，得配套传 `locales`，
+否则菜单会显示成原始 i18n key：
+
+```tsx
+import { UniverSheetsFilterPreset } from "@univerjs/presets/preset-sheets-filter"
+import zhCN from "@univerjs/presets/preset-sheets-filter/locales/zh-CN"
+
+<DocumentView format="sheet" content={snapshot}
+  sheet={{ presets: [UniverSheetsFilterPreset()], locales: [zhCN] }} />
+```
+
+`sheet` 里的配置**只在引擎创建时读一次**，挂载后改不生效也不会重建
+（重建 = 重下引擎 + 丢掉选区和滚动位置，而宿主几乎总是传内联字面量）。要换配置请换 `key`。
+
+## xlsx 导出
+
+和 docx 一样**在本地生成，文档不出内网**；不引 SheetJS，只多用已有的 fflate。
+
+```tsx
+import { downloadXlsx, exportXlsx } from "@4399ywkf/editor/xlsx"
+
+const api = useRef<unknown>(null)
+<DocumentView format="sheet" content={snapshot} onReady={(a) => (api.current = a)} />
+
+// univerAPI 或快照都收
+const { warnings } = downloadXlsx(api.current, "年度报表.xlsx")
+if (warnings.length) toast(warnings.join("\n"))   // ← 别吞，见下
+```
+
+服务端 / 定时任务只有 JSON 也能导 —— 整条链路不碰 DOM，不用起 Univer：
+
+```ts
+import { xlsxFromSnapshot } from "@4399ywkf/editor/xlsx"
+const { bytes, warnings, stats } = xlsxFromSnapshot(snapshot)
+```
+
+保真范围：
+
+| | 状态 |
+|---|---|
+| 值与类型、共享字符串、强制文本（`quotePrefix`） | ✅ |
+| 公式 + 缓存值，填充公式还原成 xlsx 的共享公式 | ✅ |
+| 数字格式、字体、颜色、填充、边框、对齐、换行、旋转 | ✅ |
+| 合并单元格、行高列宽、隐藏行列、冻结窗格 | ✅ |
+| 多工作表、工作表隐藏、标签颜色、网格线开关 | ✅ |
+| 富文本单元格 | ~ 压平成纯文本 |
+| 图片、图表、透视表、条件格式、数据校验、筛选、批注、超链接 | ✕ |
+
+最后一行是 Univer 社区版的结构性限制：这些数据不在 `cellData` 里，而是各插件自己
+序列化进 `resources` 的私有结构。**所以 `warnings` 必须展示给用户** —— 导出时它会
+逐条点名丢了什么（「条件格式未随 xlsx 导出」），打开文件才发现要糟得多。
+
+`cachedFormulaValues`（默认 true）决定公式格写不写 Univer 算好的值。关掉则只留公式、
+由 Excel 打开时重算 —— 这时会自动加上 `fullCalcOnLoad`，否则不重算的消费方
+（网页预览、pandas）会看到一片空白。
+
 ## docx 导入导出
 
 API 形态对齐 `@tiptap-pro/extension-import-docx` / `-export-docx`，但**在本地解析**，

package/dist/{DocView-IZ4JBSIA.js → DocView-XQMJUUVK.js}

@@ -1,4 +1,4 @@
-import { EditorConfigProvider, NotionEditor } from './chunk-FQCG2HNJ.js';
+import { EditorConfigProvider, NotionEditor } from './chunk-IUDLMN53.js';
 import './chunk-QMYT5WXO.js';
 import { jsx } from 'react/jsx-runtime';
 
@@ -15,5 +15,5 @@ function DocView({ content, readOnly, room, className, onReady }) {
 }
 
 export { DocView as default };
-//# sourceMappingURL=DocView-IZ4JBSIA.js.map
-//# sourceMappingURL=DocView-IZ4JBSIA.js.map
+//# sourceMappingURL=DocView-XQMJUUVK.js.map
+//# sourceMappingURL=DocView-XQMJUUVK.js.map

package/dist/{DocView-IZ4JBSIA.js.map → DocView-XQMJUUVK.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/views/DocView.tsx"],"names":[],"mappings":";;;;AAMe,SAAR,QAAyB,EAAE,OAAA,EAAS,UAAU,IAAA,EAAM,SAAA,EAAW,SAAQ,EAAsB;AAClG,EAAA,2BACG,KAAA,EAAA,EAAI,SAAA,EACH,8BAAC,oBAAA,EAAA,EAAqB,MAAA,EAAQ,EAAC,EAC7B,QAAA,kBAAA,GAAA;AAAA,IAAC,YAAA;AAAA,IAAA;AAAA,MACC,MAAM,IAAA,IAAQ,SAAA;AAAA,MACd,OAAA;AAAA,MACA,QAAA;AAAA,MACA,aAAA,EAAe,CAAC,MAAA,KAAmB,OAAA,GAAU,MAAM;AAAA;AAAA,KAEvD,CAAA,EACF,CAAA;AAEJ","file":"DocView-IZ4JBSIA.js","sourcesContent":["import type { Editor } from \"@tiptap/react\"\nimport { EditorConfigProvider } from \"../contexts/editor-config-context\"\nimport { NotionEditor } from \"../components/tiptap-templates/notion-like/notion-like-editor\"\nimport type { DocumentViewProps } from \"../registry\"\n\n/** doc 通道：云文档与本地 doc 是同一套 tiptap，不做区分 */\nexport default function DocView({ content, readOnly, room, className, onReady }: DocumentViewProps) {\n  return (\n    <div className={className}>\n      <EditorConfigProvider config={{}}>\n        <NotionEditor\n          room={room ?? \"default\"}\n          content={content as string}\n          readOnly={readOnly}\n          onEditorReady={(editor: Editor) => onReady?.(editor)}\n        />\n      </EditorConfigProvider>\n    </div>\n  )\n}\n"]}
+{"version":3,"sources":["../src/views/DocView.tsx"],"names":[],"mappings":";;;;AAMe,SAAR,QAAyB,EAAE,OAAA,EAAS,UAAU,IAAA,EAAM,SAAA,EAAW,SAAQ,EAAsB;AAClG,EAAA,2BACG,KAAA,EAAA,EAAI,SAAA,EACH,8BAAC,oBAAA,EAAA,EAAqB,MAAA,EAAQ,EAAC,EAC7B,QAAA,kBAAA,GAAA;AAAA,IAAC,YAAA;AAAA,IAAA;AAAA,MACC,MAAM,IAAA,IAAQ,SAAA;AAAA,MACd,OAAA;AAAA,MACA,QAAA;AAAA,MACA,aAAA,EAAe,CAAC,MAAA,KAAmB,OAAA,GAAU,MAAM;AAAA;AAAA,KAEvD,CAAA,EACF,CAAA;AAEJ","file":"DocView-XQMJUUVK.js","sourcesContent":["import type { Editor } from \"@tiptap/react\"\nimport { EditorConfigProvider } from \"../contexts/editor-config-context\"\nimport { NotionEditor } from \"../components/tiptap-templates/notion-like/notion-like-editor\"\nimport type { DocumentViewProps } from \"../registry\"\n\n/** doc 通道：云文档与本地 doc 是同一套 tiptap，不做区分 */\nexport default function DocView({ content, readOnly, room, className, onReady }: DocumentViewProps) {\n  return (\n    <div className={className}>\n      <EditorConfigProvider config={{}}>\n        <NotionEditor\n          room={room ?? \"default\"}\n          content={content as string}\n          readOnly={readOnly}\n          onEditorReady={(editor: Editor) => onReady?.(editor)}\n        />\n      </EditorConfigProvider>\n    </div>\n  )\n}\n"]}

package/dist/SheetView-DSADIZNS.js

@@ -0,0 +1,3 @@
+export { SheetView as default } from './chunk-L6ZR5HHW.js';
+//# sourceMappingURL=SheetView-DSADIZNS.js.map
+//# sourceMappingURL=SheetView-DSADIZNS.js.map

package/dist/{SheetView-2EID6B2I.js.map → SheetView-DSADIZNS.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"SheetView-2EID6B2I.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"SheetView-DSADIZNS.js"}

package/dist/{chunk-FQCG2HNJ.js → chunk-IUDLMN53.js}

@@ -20944,6 +20944,16 @@ function EditorProvider(props) {
   } = props;
   const { user } = useUser();
   const { setTocContent } = useToc();
+  const scrollParentRef = useRef(null);
+  const editorRef = useRef(null);
+  const resolveScrollParent = useCallback(() => {
+    if (scrollParentRef.current) return scrollParentRef.current;
+    const dom = editorRef.current?.view?.dom;
+    if (!dom?.isConnected) return window;
+    const found = getScrollableAncestor(dom);
+    scrollParentRef.current = found;
+    return found;
+  }, []);
   const editorConfig = useEditorConfig();
   const onUpload = editorConfig?.upload?.onUpload ?? handleImageUpload;
   const onUploadError = editorConfig?.upload?.onError ?? ((error) => console.error("Upload failed:", error));
@@ -21040,6 +21050,8 @@ function EditorProvider(props) {
       Image,
       TableOfContents.configure({
         getIndex: getHierarchicalIndexes,
+        // 见 resolveScrollParent 的说明：默认的 window 在「内层 div 滚动」的宿主里收不到事件
+        scrollParent: resolveScrollParent,
         onUpdate(content2) {
           setTocContent(content2);
         }
@@ -21123,6 +21135,24 @@ function EditorProvider(props) {
       ...extraExtensions ?? []
     ]
   });
+  useEffect(() => {
+    if (!editor) return;
+    editorRef.current = editor;
+    const dom = editor.view?.dom;
+    if (!dom?.isConnected) return;
+    const target = getScrollableAncestor(dom);
+    if (target instanceof Window) return;
+    scrollParentRef.current = target;
+    const handler = () => {
+      const storage = editor.storage?.tableOfContents;
+      storage?.scrollHandler?.();
+    };
+    target.addEventListener("scroll", handler, { passive: true });
+    handler();
+    return () => {
+      target.removeEventListener("scroll", handler);
+    };
+  }, [editor]);
   useEffect(() => {
     if (provider) return;
     if (!editor) return;
@@ -21243,5 +21273,5 @@ function ArticleViewer({ content, placeholder = "" }) {
 }
 
 export { ArticleViewer, Audio, CollabContext, CollabProvider, Column, Columns, DEFAULT_MAX_FILE_SIZES, DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EditorConfigProvider, EditorContentArea, EditorProvider, FileAttachment, FloatingElement, HIDE_FLOATING_META, LoadingSpinner, MediaUploadButton, MediaUploadPlaceholder, NotionEditor, NotionEditorContent, PasteDropMedia, Separator, Spacer, Toolbar, ToolbarGroup, ToolbarSeparator, UiState, UserContext, UserProvider, Video, defaultUiState, detectMediaKind, findSelectionPosition, hasContentAbove, markHideFloatingOnNext, pickFile, resolveMaxSize, runMediaUpload, selectNodeAndHideFloating, useCollab, useCollaboration, useComposedRef, useCursorVisibility, useEditorConfig, useElementRect, useFloatingElement, useFloatingToolbarVisibility, useIsBreakpoint, useIsomorphicLayoutEffect, useMenuNavigation, useOnClickOutside, useThrottledCallback, useUiEditorState, useUnmount, useUser, useWindowSize, use_ui_editor_state_default };
-//# sourceMappingURL=chunk-FQCG2HNJ.js.map
-//# sourceMappingURL=chunk-FQCG2HNJ.js.map
+//# sourceMappingURL=chunk-IUDLMN53.js.map
+//# sourceMappingURL=chunk-IUDLMN53.js.map