jvs-docx-ui 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,97 @@
-# Temporary Holding Version
+# jvs-docx-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+基于 **Vue 3 + TypeScript + Vite + docxjs (`docx-preview`)** 构建的 Word (`.docx`) 文档预览组件库，同时支持 **独立站点部署** 与 **Vue 3 插件 NPM 发布**。
+
+## 1. 开发与构建指令
+
+```bash
+# 安装依赖
+pnpm install
+
+# 启动本地开发调试 (支持 0.0.0.0 局域网访问)
+pnpm dev
+
+# 构建可独立部署的 Web 应用（产物位于 dist/app）
+pnpm build
+
+# 构建可发布的 Vue 3 插件库（产物位于 dist/lib，包含 ES/UMD 与 .d.ts 类型声明）
+pnpm build:lib
+```
+
+## 2. 支持的文档加载方式
+
+### 方式一：作为 Vue 3 插件通过 Props 直接传入文件链接或文件流
+
+`<JvsDocx />` 同时支持 `fileUrl`、`url`、`src`、`fileContent`、`v-model` 绑定远程/本地链接、`File`、`Blob`、`ArrayBuffer`、`Uint8Array` 或 Base64 字符串：
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { JvsDocx } from 'jvs-docx-ui'
+import 'jvs-docx-ui/style.css'
+
+const docUrl = ref('https://example.com/files/contract.docx')
+const headers = { Authorization: 'Bearer xxx' }
+</script>
+
+<template>
+  <div style="height: 100vh">
+    <JvsDocx :file-url="docUrl" :request-headers="headers" />
+  </div>
+</template>
+```
+
+### 方式二：通过组件 Ref 实例方法主动加载（链接或本地文件）
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { JvsDocx, type JvsDocxExpose } from 'jvs-docx-ui'
+import 'jvs-docx-ui/style.css'
+
+const docxRef = ref<JvsDocxExpose | null>(null)
+
+// 1. 通过文件 URL 链接加载（支持自定义请求头）
+async function loadByUrl(url: string) {
+  await docxRef.value?.loadFromUrl(url, {
+    fileName: '技术协议.docx',
+    headers: { Authorization: 'Bearer xxx' }
+  })
+}
+
+// 2. 通过本地 File / Blob / ArrayBuffer / Base64 加载
+async function onFileChange(e: Event) {
+  const file = (e.target as HTMLInputElement).files?.[0]
+  if (file) {
+    await docxRef.value?.importDocxFile(file, file.name)
+  }
+}
+
+// 3. 导出当前预览的 .docx 文件
+async function onExport() {
+  await docxRef.value?.exportDocxFile('导出文档.docx', true)
+}
+</script>
+
+<template>
+  <div style="height: 600px">
+    <JvsDocx ref="docxRef" />
+  </div>
+</template>
+```
+
+### 方式三：独立站点部署模式下的外部传参加载
+
+1. **URL 查询参数自动加载**：
+   直接访问 `http://your-host/?fileUrl=https://example.com/demo.docx&fileName=示例文档.docx`（或 `?url=...`），页面挂载后会自动拉取链接并渲染预览。
+2. **顶部工具栏链接输入**：
+   在顶部工具栏输入框中粘贴 `.docx` 链接并点击「加载链接」或按回车即可预览。
+3. **iframe `postMessage` 通信加载**：
+   ```js
+   iframeWindow.postMessage({
+     type: 'jvs-docx:load',
+     fileUrl: 'https://example.com/demo.docx',
+     fileName: '示例文档.docx',
+     headers: { Authorization: 'Bearer xxx' }
+   }, '*')
+   ```

package/dist/lib/index.d.ts

@@ -0,0 +1,171 @@
+import { ComponentOptionsMixin } from 'vue';
+import { ComponentProvideOptions } from 'vue';
+import { defaultOptions } from 'docx-preview';
+import { DefineComponent } from 'vue';
+import { Options as DocxPreviewOptions } from 'docx-preview';
+import { parseAsync } from 'docx-preview';
+import { Plugin as Plugin_2 } from 'vue';
+import { PublicProps } from 'vue';
+import { renderAsync } from 'docx-preview';
+import { renderDocument } from 'docx-preview';
+import { WordDocument } from 'docx-preview';
+
+export { defaultOptions }
+
+export declare const DOCX_MIME_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+
+export declare type DocxInputSource = File | Blob | ArrayBuffer | Uint8Array | string | {
+    url?: string;
+    fileUrl?: string;
+    content?: File | Blob | ArrayBuffer | Uint8Array | string;
+    fileName?: string;
+    headers?: Record<string, string>;
+    requestInit?: RequestInit;
+};
+
+export declare interface DocxLoadOptions {
+    /** 指定文件名（不传则自动从 File.name / Content-Disposition / URL 路径推断） */
+    fileName?: string;
+    /** 请求远程文件链接时的自定义请求头（例如 Authorization Token） */
+    headers?: Record<string, string>;
+    /** 请求远程文件链接时的透传 fetch RequestInit 配置 */
+    requestInit?: RequestInit;
+    /** 自定义文件拉取函数 */
+    customFetch?: (url: string, init?: RequestInit) => Promise<Blob | ArrayBuffer | Uint8Array | Response>;
+}
+
+export { DocxPreviewOptions }
+
+/**
+ * 触发浏览器下载 .docx Blob
+ */
+export declare function downloadDocxBlob(blob: Blob, fileName?: string): void;
+
+/**
+ * 从 URL 或 Content-Disposition 响应头中提取文件名
+ */
+export declare function extractFileNameFromUrl(url: string, contentDisposition?: string | null): string;
+
+/**
+ * 通过 URL 拉取远程或本地 .docx 文件并转为 Blob
+ */
+export declare function fetchDocxFromUrl(url: string, options?: DocxLoadOptions): Promise<NormalizedDocxResult>;
+
+/**
+ * 判断字符串是否为 URL 或文件路径（而非纯 Base64 字符串）
+ */
+export declare function isLikelyUrlString(str: string): boolean;
+
+export declare const JvsDocx: DefineComponent<JvsDocxProps, {
+importDocxFile: (source: DocxInputSource, optionsOrFileName?: string | DocxLoadOptions) => Promise<WordDocument>;
+loadFromUrl: (url: string, optionsOrFileName?: string | DocxLoadOptions) => Promise<WordDocument>;
+renderDocx: (source: DocxInputSource, optionsOrFileName?: string | DocxLoadOptions) => Promise<WordDocument>;
+exportDocxFile: (fileName?: string, download?: boolean) => Promise<Blob>;
+clear: () => void;
+getWordDocument: () => WordDocument | null;
+getBlob: () => Blob | null;
+getFileName: () => string;
+getContainer: () => HTMLElement | null;
+}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
+error: (error: Error) => any;
+rendered: (document: any) => any;
+loaded: (payload: JvsDocxLoadedPayload) => any;
+change: (blob: Blob | null) => any;
+}, string, PublicProps, Readonly<JvsDocxProps> & Readonly<{
+onError?: ((error: Error) => any) | undefined;
+onRendered?: ((document: any) => any) | undefined;
+onLoaded?: ((payload: JvsDocxLoadedPayload) => any) | undefined;
+onChange?: ((blob: Blob | null) => any) | undefined;
+}>, {
+fileName: string;
+requestInit: RequestInit;
+customFetch: (url: string, init?: RequestInit) => Promise<Blob | ArrayBuffer | Uint8Array | Response>;
+fileUrl: string;
+fileContent: DocxInputSource;
+url: string;
+src: DocxInputSource;
+modelValue: DocxInputSource;
+requestHeaders: Record<string, string>;
+options: Partial<DocxPreviewOptions>;
+}, {}, {}, {}, string, ComponentProvideOptions, false, {
+previewContainerRef: HTMLDivElement;
+}, HTMLDivElement>;
+
+export declare interface JvsDocxExpose {
+    /** 导入并渲染 .docx 文档（支持 File / Blob / ArrayBuffer / Uint8Array / URL 链接 / Base64 / 配置对象） */
+    importDocxFile: (source: DocxInputSource, optionsOrFileName?: string | DocxLoadOptions) => Promise<WordDocument>;
+    /** 通过远程或本地文件链接地址加载并渲染 .docx 文档 */
+    loadFromUrl: (url: string, optionsOrFileName?: string | DocxLoadOptions) => Promise<WordDocument>;
+    /** 使用 docxjs 渲染加载 .docx 文档（importDocxFile 的别名） */
+    renderDocx: (source: DocxInputSource, optionsOrFileName?: string | DocxLoadOptions) => Promise<WordDocument>;
+    /** 导出当前预览的 .docx 文件 */
+    exportDocxFile: (fileName?: string, download?: boolean) => Promise<Blob>;
+    /** 清空当前文档预览内容 */
+    clear: () => void;
+    /** 获取当前 docxjs 解析后的 WordDocument AST 对象 */
+    getWordDocument: () => WordDocument | null;
+    /** 获取当前文档的原始 Blob 数据 */
+    getBlob: () => Blob | null;
+    /** 获取当前加载的文档文件名 */
+    getFileName: () => string;
+    /** 获取预览容器 DOM 节点 */
+    getContainer: () => HTMLElement | null;
+}
+
+export declare interface JvsDocxLoadedPayload {
+    fileName: string;
+    blob: Blob;
+    document: WordDocument;
+}
+
+export declare interface JvsDocxProps {
+    /** Word (.docx) 文件内容或链接（支持 File / Blob / ArrayBuffer / Uint8Array / URL / Base64 / 配置对象） */
+    fileContent?: DocxInputSource;
+    /** 远程或本地 .docx 文件链接地址 */
+    fileUrl?: string;
+    /** 远程或本地 .docx 文件链接地址（fileUrl 的简写别名） */
+    url?: string;
+    /** 通用文档数据源或链接地址（支持 URL / File / Blob / ArrayBuffer / Base64） */
+    src?: DocxInputSource;
+    /** 支持 v-model 绑定文档数据源或文件链接 */
+    modelValue?: DocxInputSource;
+    /** 默认文档名称（用于导出时默认文件名） */
+    fileName?: string;
+    /** 请求远程文件链接时的自定义请求头（例如 Authorization Token） */
+    requestHeaders?: Record<string, string>;
+    /** 请求远程文件链接时的 fetch RequestInit 配置（如 credentials: 'include'） */
+    requestInit?: RequestInit;
+    /** 自定义远程文件拉取函数 */
+    customFetch?: DocxLoadOptions['customFetch'];
+    /** docxjs (docx-preview) 渲染配置项 */
+    options?: Partial<DocxPreviewOptions>;
+}
+
+declare const JvsDocxUiPlugin: Plugin_2;
+export { JvsDocxUiPlugin }
+export default JvsDocxUiPlugin;
+
+export declare interface NormalizedDocxResult {
+    blob: Blob;
+    fileName: string;
+}
+
+/**
+ * 将各种输入源（File / Blob / ArrayBuffer / Uint8Array / URL 链接 / Base64 / 配置对象）统一解析为 Blob 与文件名
+ */
+export declare function normalizeDocxSource(source: DocxInputSource, options?: DocxLoadOptions): Promise<NormalizedDocxResult>;
+
+/**
+ * 兼容旧版 API：将各种输入源统一转换为 Blob
+ */
+export declare function normalizeDocxSourceToBlob(source: DocxInputSource, options?: DocxLoadOptions): Promise<Blob>;
+
+export { parseAsync }
+
+export { renderAsync }
+
+export { renderDocument }
+
+export { WordDocument }
+
+export { }

package/dist/lib/jvs-docx-ui.css

@@ -0,0 +1 @@
+.jvs-docx-viewer[data-v-34e07d63]{position:relative;width:100%;height:100%;min-height:360px;background-color:#f1f5f9;overflow:hidden;display:flex;flex-direction:column}.jvs-docx-viewer__container[data-v-34e07d63]{flex:1;width:100%;height:100%;overflow:auto}.jvs-docx-viewer__overlay[data-v-34e07d63]{position:absolute;top:0;right:0;bottom:0;left:0;z-index:5;background-color:#f1f5f9;display:flex;flex-direction:column;align-items:center;justify-content:center;padding:32px;color:#64748b;text-align:center;-webkit-user-select:none;user-select:none}.jvs-docx-viewer__overlay--error[data-v-34e07d63]{color:#ef4444}.jvs-docx-viewer__empty-icon[data-v-34e07d63]{display:flex;align-items:center;justify-content:center;width:76px;height:76px;border-radius:16px;background-color:#e2e8f0;color:#64748b;margin-bottom:16px}.jvs-docx-viewer__state-title[data-v-34e07d63]{margin:0 0 6px;font-size:15px;font-weight:600;color:#334155}.jvs-docx-viewer__overlay--error .jvs-docx-viewer__state-title[data-v-34e07d63]{margin-top:12px;color:#dc2626}.jvs-docx-viewer__state-desc[data-v-34e07d63]{margin:0;font-size:13px;color:#94a3b8;max-width:440px;line-height:1.6}.jvs-docx-viewer__state-text[data-v-34e07d63]{margin:14px 0 0;font-size:13px;color:#64748b}.jvs-docx-viewer__spinner[data-v-34e07d63]{width:32px;height:32px;border:3px solid #cbd5e1;border-top-color:#2563eb;border-radius:50%;animation:jvs-docx-spin-34e07d63 .75s linear infinite}@keyframes jvs-docx-spin-34e07d63{to{transform:rotate(360deg)}}.jvs-docx-viewer__container[data-v-34e07d63] .docx-wrapper{background-color:#f1f5f9;padding:24px 16px 40px;display:flex;flex-direction:column;align-items:center;min-height:100%}.jvs-docx-viewer__container[data-v-34e07d63] .docx-wrapper>section.docx{background-color:#fff;box-shadow:0 4px 16px #0f172a14,0 1px 3px #0f172a0a;border-radius:2px;margin-bottom:20px;padding:72pt 90pt}.jvs-docx-viewer__container[data-v-34e07d63] section.docx p[class*=docx-num-]:before{white-space:pre;margin-right:4pt}.jvs-docx-viewer__container[data-v-34e07d63] section.docx table{max-width:100%}.jvs-docx-viewer__container[data-v-34e07d63] section.docx img{max-width:100%}