实例方法参考

本页按主题整理项目公开说明，供完成快速接入后查阅。代码片段中的业务回调、服务地址和存储实现需要由宿主提供。

公开方法

AI 接入见 AI接入.md。通过 getAiAdapter() 创建当前实例的 createOfficeWordAiBridge()；@ai-target 将选中内容或光标目标交给宿主，@ai-target-change 通知标记的变化。失焦不清除标记，内容区点击、关闭标记或宿主 clearAiTarget() 可清除。模型、聊天和文件存储由宿主负责。

/ai-protocol 导出 getWordAiToolSchemas() 和补丁 Schema；/docx 提供不加载 Vue 的浏览器/Node DOCX 读写入口。Skill 在组件仓库平级的 packages/skills/norio-office-word 单独交付。当前能力和边界以 Bridge 的 getCapabilities() 为准。

首版暂不将图表创建、数据／设置编辑和删除纳入正式 AI 能力，图表插入菜单保持隐藏。相关原生命令仅保留为内部实验实现，AI 不提供对应操作；已有文档中的图表源数据保留规则不变。

通过组件 ref 调用，接口类型为 OfficeWordPublicApi。下列四组共 28 个方法，包含业务方法和可选诊断方法。同步方法直接返回结果，异步方法返回 Promise。

文档与编辑：10 个方法

三个更新方法的布尔返回值表示是否实际修改了文档；无变化时可能返回 false，命令被拒绝时也可能抛出异常。

OfficeWordPageSettingsUpdate 所有字段均可选，未指定的设置保留现值：

const api = wordRef.value
if (!api) throw new Error('组件尚未就绪')

api.updatePageSettings({
  scope: 'document',
  size: 'A4',
  orientation: 'portrait',
  marginTop: 96,
  marginBottom: 96,
  marginLeft: 90,
  marginRight: 90,
})

const snapshot = await api.getDocumentAsync()
const json = JSON.stringify(snapshot)
// 将 json 保存到宿主自己的接口或存储。

文件名接入

文档只维护一个名称，存放在 OfficeWordDocument.title。顶部文件栏、文档读取结果、FILENAME 字段的名称来源及默认导出文件名均读取它；传入导出选项 fileName 只影响本次导出，不修改文档名称。菜单下载与 exportWordBlob() 的 DOCX 名称统一规范化：去掉已有的 Word 扩展名后追加一次 .docx，文件名中的 \\ / : * ? " < > | 替换为 -，连续空白合并；顶部名称仍保留用户输入。

<script setup lang="ts">
import { shallowRef } from 'vue'
import { OfficeWord, type OfficeWordPublicApi, type OfficeWordFileNameChangePayload } from '@norio-office/office-word'
// fontUrls 沿用上文四个字体文件的配置。
const wordRef = shallowRef<OfficeWordPublicApi | null>(null)
function handleFileNameChange({ fileName, previousFileName }: OfficeWordFileNameChangePayload) {
  console.log(previousFileName, fileName)
}
function rename() {
  wordRef.value?.setFileName('劳动合同')
}
</script>

<template>
  <button @click="rename">外部改名</button>
  <OfficeWord ref="wordRef" :font-urls="fontUrls" title="新建文档"
    mode="edit" :show-file-header="true" @file-name-change="handleFileNameChange" />
</template>

内部改名与 setFileName() 共用原生命令及撤销历史；只有编辑模式开放撤销／重做交互。外部改名、文档替换或隐藏文件栏会取消旧改名草稿，避免失焦后覆盖当前名称。

文件名事件在当前提交结束后的微任务通知，每次实际名称变化分别保留；回调中可再次调用 setFileName()。完整文档的 change／update:modelValue 仍遵循快照发布时机，不保证与该事件同时发出。不要用 change 手工维护另一套文件名。使用 v-model 回传组件快照（包括 JSON 克隆）不会重复触发改名。

这些规则在三种模式下一致。preview／disabled 不响应撤销、重做的编辑交互；外部 setFileName() 仍进入原生历史，返回 edit 后可撤销、重做，并正常回传名称及变更事件。通过 v-model 传入真正不同的文档（即使版本字段相同）视为文档替换；成功导入和文档替换会重置旧撤销历史，不能撤销回导入前的文件。失败或取消导入不改变当前名称。

exportWordBlob() 返回的默认名称与 Blob 内容取自同一份完成准备的导出快照；导出期间发生新的改名、导入或正文修改，不会把新名称混到旧内容上，也不会将更新后的文档误标为已保存。导出选项在调用时捕获，等待期间修改选项不会改变本次文件名。

导入：4 个方法

支持 DOCX 和 HTML 内容形式的 .doc；旧版二进制 .doc 不支持直接导入。导入名称取实际文件名（或 Blob 选项 fileName）去掉 .docx／.doc 扩展名，DOCX 与 HTML DOC 使用同一规则。成功解析后才替换当前文档。公开的 importFile()／importWordBlob() 在三种模式均可调用，仍受 importWord 授权、文件安全限制和任务取消约束；界面导入只在编辑模式开放，期间切换模式会使该界面请求失效。组件同一时间管理一个导入任务，发起新任务会请求取消前一个任务。

OfficeWordImportState 返回字段：

const api = wordRef.value
if (!api) throw new Error('组件尚未就绪')

// file 来自文件选择器，类型为 File。
const state = await api.importFile(file)
if (state.status !== 'success') {
  console.error(state.code, state.message)
}

// sourceBlob 来自下载接口或宿主存储，类型为 Blob。
await api.importWordBlob(sourceBlob, { fileName: '合同.docx' })

导出：6 个方法

导出方法会自行准备需要的文档和排版结果，无需先调用诊断方法。导出不会自动生成兼容性检查报告，也不会弹出检查确认框。公开方法返回文件内容，不会自动下载或上传；宿主负责保存、下载或上传这些结果。

OfficeWordBlobExportResult 的字段：

三个逐页图片方法共享以下可选参数：

每项返回的 page 是原文档页码，从 1 开始。有效页码超出文档范围时不会生成对应项。

const api = wordRef.value
if (!api) throw new Error('组件尚未就绪')

const result = await api.exportWordBlob({
  type: 'docx',
  fileName: '合同.docx',
})

// 上传到业务接口。
const formData = new FormData()
formData.append('file', result.blob, result.fileName)

const pdf = await api.exportPdfBlob()
const images = await api.exportPngBlobs({ pages: [1], scale: 2 })

exportDocxBlob() 的复杂对象选项按对象类型配置；没有指定时使用默认策略：

诊断：8 个方法

这些方法用于业务诊断、测试或监测。普通加载、编辑、保存和导出不要求调用。

getAuthoritativeLayoutDebugState() 的全部可选参数：

不传这些参数时只返回默认诊断信息。presentation.settled 可用于诊断画面呈现是否已经完成；不要用 ready 事件替代该状态的判断。