简介NTKO Office文档控件跨浏览器新版本插件集成入门教程由重庆软航科技有限公司官方编写面向需要为OA系统添加浏览器内在线编辑Word、Excel等Office文档功能的开发者与系统集成人员。教程针对高版本64位谷歌、火狐及Chromium内核双核浏览器不再支持NPAPI、PPAPI插件的问题详细讲解了从产品组成、支持环境到集成实现的全过程。内容覆盖跨浏览器插件exe、firefox的xpi、chrome的crx安装方式以及ntko-background-min.js引用、ntkoBrowser.openWindow调用和ntkooffice.js配置等关键步骤并附带痕迹保留、模板套红、打印控制等常用功能说明。资源为单个doc文档容量约1.08MB全文13页章节结构清晰可按步骤对照操作。已有3896人浏览学习对于需要在现代浏览器环境中快速集成Office在线编辑能力的开发团队具有直接参考价值。1. 浏览器换代把 Office 在线编辑变成黑匣子NTKO 跨浏览器新版本是来填坑的做过 OA 系统的人应该都撞过这堵墙业务还在用 Word 模板套红、痕迹保留浏览器却从 IE 一路升级到 64 位 Chrome 和 Firefox老 ActiveX 控件一夜间全部失效。原因大家都知道高版本谷歌、火狐先后抛弃 NPAPI 插件机制而文档控件这类依赖本地 Office 的组件恰恰就建在 NPAPI 上。NTKO OFFICE 文档控件跨浏览器新版本就是为了解决这个断档而设计的它不再硬塞插件进浏览器而是用一个独立的应用程序窗口承载控件浏览器页面只负责调度从而让 32 位、64 位谷歌、火狐以及 360 这类双核浏览器里能继续在线阅读、编辑 Word/Excel/PowerPoint 并保存回服务器。这篇教程适合两类人一是老系统等着升级控件续命的维护者二是新项目要在 Chrome 内核浏览器里做在线编辑选型的开发。2. 新版产品组成拆解xpi、crx、exe 与两个 JS 文件的分工逻辑2.1 为什么老方案会在高版本浏览器里失灵先说原理不然你连装哪个文件都不知道。传统 NTKO 文档控件是 ActiveX 控件IE 里通过 object 标签直接实例化浏览器内核与 COM 组件之间是原生通道所以好用。Chrome 和 Firefox 早期还保留了一部分 NPAPI 接口给这类插件后来谷歌从 Chrome 45 开始逐步禁用 NPAPI火狐也在 Firefox 52 之后默认关闭只留 PPAPI 给音视频插件用。PPAPI 比 NPAPI 更封闭本地 ActiveX 控件根本进不了这个沙箱于是“在浏览器里直接编辑 Office 文档”这条路被彻底堵死。新版 NTKO 的产品思路是绕过浏览器控件限制把控件从网页里拿出来放到一个独立的应用程序窗口里运行。浏览器页面通过 JavaScript 与这个外部程序通信外部程序再调用本机 Office 完成编辑、保存。这样浏览器是什么内核、什么位数都不再影响控件的存在真正做到了“控件在浏览器外体验在浏览器内”。这也是为什么新版产品文件里多了 exe、xpi、crx 这类浏览器扩展文件它们本质上是搭桥用的。2.2 五个核心文件各自负责什么新版文档控件的产品包和旧版差异很大旧版一个 cab 包打天下新版被拆成了浏览器扩展程序、后台通信脚本和控件生成脚本三部分。我按实际项目里会碰到的东西逐个说明。文件用途安装方式NTKO-WEBEXT 跨浏览器插件-1.5.7.exe浏览器与本地控件通信的桥梁谷歌火狐共用双击安装必须装ntko_office-firefox-1.5.8.xpi火狐浏览器扩展负责把页面请求转发给本地程序拖入浏览器或代码自动安装ntko-office-chrome-1.5.8.crx谷歌系浏览器扩展功能同 xpi开发者模式拖入ntko-background-min.js页面端后台调度脚本提供 ntkoBrowser 全局对象页面 script 标签引用ntkooffice.js生成文档控件 object 标签及控件参数拷贝到项目目录后按需修改这里有个容易混淆的点exe 和 xpi/crx 不是二选一而是叠加关系。exe 是必须装的常驻程序xpi 和 crx 是浏览器侧的转发器缺了 exe浏览器扩展拿到请求也没地方送。产品文档里特别标注了这一点装插件时不要偷懒只拖 crx。另外xpi 和 crx 虽然文件名里带了版本号 1.5.8exe 是 1.5.7这不代表冲突只是三个模块各自的版本节奏不同使用环境里三个都要装齐全。2.3 独立应用程序窗口的工作方式与 Session 保持新方案的核心机制是 ntkoBrowser.openWindow(url)页面调用它后会唤起外部程序窗口这个窗口再加载 openWindow 指定的页面。注意这个窗口虽然是应用窗口但它内部仍然渲染了传进来的 url 页面用户的编辑操作都发生在这个页面里。由于窗口的上下文独立于浏览器标签页浏览器升级也好、标签页崩溃也好都影响不到已经打开的控件窗口。Session 保持是另一个关键优化点。老方案在浏览器标签页内嵌控件时控件发出的 HTTP 请求和页面同属一个 Session没太大问题新方案因为编辑窗口独立如果直接发请求服务端会认为是个新会话于是出现“编辑完保存直接跳回登录页”的经典翻车现场。新版产品通过扩展程序和后台脚本把原页面的 Cookie、会话标识透传给独立窗口保证后续上传、保存请求仍然走原会话。这也是为什么集成时要求把 ntko-background-min.js 放在原页面而不是放在 openWindow 指向的新页面里。3. 环境搭建先装对三件套exe、火狐 xpi、谷歌 crx 的安装顺序与验证3.1 先装 exeNTKO-WEBEXT 跨浏览器插件安装细节环境搭建的第一步只有一个动作安装 NTKO-WEBEXT 跨浏览器插件-1.5.7.exe。这个程序是浏览器和本地文档控件之间的转发服务它不区分浏览器类型谷歌、火狐、360 都走它。安装过程就是标准的 Windows 向导选择安装路径后一路下一步就行。装完建议手动重启一次浏览器否则扩展程序找不到刚注册的本地服务表现为插件装上了但调用 openWindow 毫无反应。这里有个细节值得注意安装 exe 时如果系统同时开着 Chrome 和 Firefox最好都关掉再装。Windows 下插件服务注册时会刷新浏览器侧的扩展列表浏览器开着容易导致扩展未正确绑定。我习惯装完后先不打开任何业务页面直接打开一个空白标签页验证扩展状态Chrome 在地址栏输入 chrome://extensions 看 crx 是否启用Firefox 则看附加组件管理器里 xpi 的状态。3.2 火狐 xpi 的手动安装与版本判断火狐的 xpi 安装有两种方式。手动方式是把 ntko_office-firefox-1.5.8.xpi 文件直接拖进火狐窗口浏览器会弹出“安装附加组件”的确认提示点击安装后等待片刻看到“扩展已安装”的通知即成功。这种方式适合内网部署、代码里不方便做自动安装引导的场景。另一种方式是代码引导安装教程里特别说明了判断逻辑火狐版本在 50 及以上的用 window.location.href 指向 xpi 文件路径浏览器会拦截并弹窗询问是否允许安装附加组件。注意这个判断很关键旧版火狐使用 installTrigger 方式新版火狐把 installTrigger 移除了如果代码不做版本判断老接口在 50 以上版本里会直接报错。产品包里给的示例是专门针对高版本的我建议在代码里保留版本分支低版本走传统安装高版本走 href 跳转。3.3 谷歌系浏览器 crx 安装开发者模式必须开谷歌浏览器的 crx 安装和火狐逻辑不同。进入“更多工具—扩展程序”页面后第一步必须是打开右上角的“开发者模式”开关否则拖入 crx 文件时浏览器只会下载它不会进入安装流程。打开开发者模式后把 ntko-office-chrome-1.5.8.crx 拖入扩展程序页面Chrome 会弹出一个“添加扩展程序”的确认框点击确认后扩展出现在列表中即完成。360 安全浏览器以及猎豹、QQ 浏览器这类双核产品因为内核是 Chromium绝大多数情况可以直接复用 crx 安装流程。但注意一点部分双核浏览器的扩展商店对非官方渠道的 crx 有限制安装入口可能在“高级设置”或“扩展中心”里路径名字和 Chrome 不完全一样。如果拖入没反应就去找该浏览器自己的扩展管理页开启开发者模式后再拖成功率会高很多。3.4 安装完成的验证方法三个插件都装完后先别急着写业务代码做一个快速自检。在浏览器里按 F12 打开控制台输入 window.ntkoBrowser如果返回的是对象而不是 undefined说明后台脚本和扩展程序通信正常。再输入 typeof ntkoBrowser.openWindow确认是 function 类型。这一步能过滤掉八成环境问题后面页面集成报错时排查范围可以瞬间缩小到代码层。另一个验证点是 exe 是否在运行。打开 Windows 任务管理器查看进程列表里有没有 NTKO 相关的进程名通常带 WebExt 字样。如果扩展确认启用、ntkoBrowser 对象存在但 openWindow 无法唤起窗口多半是 exe 服务没起来卸载重装一次 exe 基本能解决。4. 页面集成四步走从 ntko-background-min.js 到 ntkooffice.js 的改动点4.1 第一步引用 ntko-background-min.js 并调用 openWindow页面集成的起点是后台脚本。把 ntko-background-min.js 放到项目目录后在业务页面的 body 标签里用 script 引入然后就可以调用 ntkoBrowser.openWindow(url)。这里要特别强调参数含义openWindow 的 url 参数指向的是“即将打开文档的页面”也就是承载编辑界面的那个页面通常是含有 office 控件的编辑页。这个页面和当前页面是两个不同的页面。!-- 原业务列表页 body 末尾 -- script src/ntko/ntko-background-min.js/script script // 用户点击“编辑文档”按钮时触发 function editDoc(docId) { var editUrl /oa/ntko_edit.jsp?docId docId; ntkoBrowser.openWindow(editUrl); } /scriptopenWindow 是外部程序窗口的入口它不是普通页面跳转而是唤起独立应用程序窗口加载 editUrl。所以 editUrl 所在的页面必须能被当前用户访问并且这个页面里会继续引入 ntkooffice.js 来真正生成控件。如果 openWindow 没有响应先检查 ntko-background-min.js 路径是否正确再检查扩展是否启用这两类问题占了我实际排查的七成。4.2 第二步火狐 xpi 的代码引导安装火狐的 xpi 除了手动拖拽官方教程推荐在代码里做引导这一步必须在调用 openWindow 之前完成。判断逻辑我直接给可用的写法// 检测当前浏览器是否为 Firefox var isFirefox navigator.userAgent.indexOf(Firefox) -1; if (isFirefox) { // 提取版本号转为整数用于判断 var ver parseInt(navigator.userAgent.split(Firefox/)[1], 10); if (ver 50) { // 高版本 Firefox 通过 location.href 引导安装 xpi window.location.href /ntko/ntko_office-firefox-1.5.8.xpi; } } // 版本判断完成后再打开文档编辑窗口 ntkoBrowser.openWindow(/oa/ntko_edit.jsp?docId123);这里有两处坑。第一window.location.href 指向 xpi 后浏览器会拦截并询问用户是否允许安装用户必须手动确认代码无法绕过这是 Mozilla 的政策限制。第二location.href 跳转 xpi 后原页面还在但用户体验上会有一次明显的弹窗确认这是正常的不要以为是安装失败。如果火狐版本低于 50教程里提示需要走老式 installTrigger 接口那个接口在高版本里已经被移除了。4.3 第三步修改 ntkooffice.js 中的 classid、codebase 与授权信息ntkooffice.js 是产品包提供的控件生成脚本它会在 openWindow 指定的编辑页面里动态生成 object 标签。默认情况下这个文件里的 classid、codebase 是某个固定配置部署到自己项目时必须改成你自己的。先看典型的 ntkooffice.js 关键片段// ntkooffice.js 中生成控件的核心参数 var ocxInfo { classid: CLSID:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, codebase: /ntko/OfficeControl.cab#version5,0,3,1, width: 100%, height: 600, // 正式版授权信息测试版可留空 MakerCaprtion: , MakerKey: , Production: , ProductKey: };classid 从哪来如果拿到的是 OfficeControl.cab解开包后会有一个 OfficeControl.inf 文件里面记录了 OfficeControl.ocx 的 clsid 和文件版本号classid 必须完全照抄一个字符都不能差。codebase 由两部分拼接第一部分是 cab 文件在服务器上相对于当前网页的 URL 路径建议写相对路径第二部分是控件版本号用 # 号连接。教程里给了一个示例版本 5.0.3.1实际以你 cab 包里 inf 文件标注的 fileversion 为准。授权信息是正式版才有的测试版不用填。正式版的四个字段MakerCaprtion、MakerKey、Production、ProductKey在随产品附带的《秘钥及使用说明.txt》里文件名可能因商务流程有差异但内容就是那组密钥。注意区分MakerCaprtion 和 MakerKey 是制作人的标识Production 和 ProductKey 是产品授权码四者缺一不可漏填一个会导致控件在正式环境下拒绝加载。4.4 第四步属性、方法、事件三种接口的调用控件加载完成后通过 document.getElementById(TANGER_OCX) 就能拿到控件对象。id 默认是 TANGER_OCX在 ntkooffice.js 里可以改但改了之后所有调用点都要同步改。接口分三类写法上有明显差异。属性赋值用“对象.属性名 值”的格式比如禁用控件文件菜单里的“打开”项var ntkoobj document.getElementById(TANGER_OCX); ntkoobj.fileopen false; // false 禁用“打开”菜单项方法调用用“对象.方法名(参数)”的格式比如打开服务器上的文档var ntkoobj document.getElementById(TANGER_OCX); ntkoobj.BeginOpenFromUrl(/oa/files/contract.docx); // 参数是文档的服务器路径事件绑定比较特殊它是通过 script 标签声明式的写法并且事件名和参数是约定死的script languageJscript forTANGER_OCX eventOnDocumentOpened(url,doc) // 文档打开完成后触发url 是文档地址doc 是文档对象 ntkoobj.SetReadOnly(true, password); /script这个写法里for 属性必须等于 object 标签的 idevent 属性是事件名url 和 doc 是事件携带的参数名不能自己改名。建议把这三种调用方式写到同一个 js 文件里统一管理方便后续维护。方法的具体参数列表建议找到对应版本的开发接口文档再查教程里给的 BeginOpenFromUrl 只是示例实际项目里更常用的是带完整参数的 OpenDocument 系列方法。5. 集成避坑classid、codebase、Session 与插件加载的五个典型问题5.1 控件加载失败页面提示 TANGER_OCX 未定义现象是页面能打开但 console 报错 TANGER_OCX is null后面的所有方法调用都失效。原因排查下来大多是 classid 不匹配也就是 ntkooffice.js 里的 CLSID 和当前使用的 cab 包里的不一致。还有一个容易被忽略的场景同一台服务器上存在多个版本的 OfficeControl.cab浏览器缓存了旧的 cab 包即使 classid 改对了下载的仍是旧控件。解决方法是先打开 cab 包里的 OfficeControl.inf把 clsid 原样复制到 ntkooffice.js。如果确认 classid 无误就让客户端强制刷新一次CtrlF5必要时清理浏览器缓存重新加载。注意classid 必须和 cab 包完全一致不是只要格式对就行任何一个字符不同ActiveX 都会判定为不同的控件。5.2 codebase 路径写绝对地址导致部署环境不一致现象是开发环境控件加载正常一旦发布到测试服或正式服控件就加载不出来。原因基本是 codebase 里写了开发机的绝对路径类似 file:///D:/OfficeControl.cab。产品文档里明确要求 codebase 写相对路径是相对于当前网页的 URL而不是服务器根路径。比如当前编辑页在 /oa/edit.jsp控件放在 /oa/controls/ 下codebase 应该写成 controls/OfficeControl.cab#version5,0,3,1。解决方法是统一约定控件 cab 的存放位置并让所有页面通过统一的前缀拼接 codebase。版本号也别漏cab 更新后如果版本号没变客户端会用缓存里的旧文件这个坑最隐蔽。每次升级 cab 时把版本号同步加一能省去大量“我明明改了为什么还是旧的”的排查时间。5.3 火狐安装 xpi 时提示附加组件已损坏或无法验证高版本火狐对扩展的签名校验越来越严格非官方签名通道的 xpi 直接拖入会被拦截提示“无法验证此附加组件能否使用”。原因是 Mozilla 从 Firefox 43 开始强制要求扩展签名之后安装未签名的 xpi 只能走 about:config 里的 xpinstall.signatures.required 开关临时关闭校验或者用 Firefox ESR 版本。解决方法是先在地址栏进入 about:config搜索 signatures 相关项确认扩展签名策略是否符合产品要求。不过这里有个现实问题企业内网环境可以直接关掉签名校验但面向互联网客户时最稳妥的方式是向厂商索取已经走完签名的 xpi 版本。另外代码引导安装的路径同样受签名策略限制location.href 只是触发了安装流程浏览器该拦截还是会拦。5.4 编辑完成后保存直接跳回登录页现象是文档编辑一切正常点保存后页面跳到登录页Session 丢失。这是独立窗口方案最典型的坑。在新架构里编辑窗口是外部程序打开的独立应用窗口它携带的会话上下文默认和原浏览器标签页不一致如果不做会话透传控件向服务器提交文档时就是一次全新的匿名请求。解决方式主要是确保原页面正确引用了 ntko-background-min.js并让 openWindow 调用发生在该脚本初始化之后。更进一步检查服务端的 Session 超时配置如果原来给 IE 内嵌场景设置的超时时间很短独立窗口编辑文档耗时较长也会觉得是“Session 丢了”。建议先把后台脚本加载移动到页面 head 区域的前置位置再验证保存流程如果仍然丢失联系厂商确认该版本的具体会话保持参数。5.5 浏览器升级后扩展自动被禁用现象是某个工作日 OA 突然打不开文档检查扩展发现 Chrome 里的 crx 扩展被标记为“不受支持”且无法重新启用。原因是 Chrome 一直在收紧非商店扩展的政策特别是开发者模式拖入的 crx在后续版本更新后会被自动停用。火狐同样存在类似机制版本大版本升级后扩展重新要求授权。解决方法是升级前先确认产品版本的浏览器兼容范围产品支持环境列表里通常标明了 Chrome/Firefox 大版本上限。如果浏览器被迫升级就需要同步更新 xpi、crx 到配套新版本单纯保留旧扩展在多数情况下无解。我现在的处理习惯是把三位文件版本号和浏览器大版本号记录在项目的 README 里每次浏览器升级前先比对再操作。6. 集成完怎么自检用 TANGER_OCX 对象和 OnDocumentOpened 事件验证加载状态6.1 控件对象的基本校验集成完成后第一件事是验证控件对象是否真实存在。打开业务编辑页F12 切到控制台执行 document.getElementById(TANGER_OCX)如果返回 object 说明控件已经加载返回 null 则回到上一章排查 classid 和 codebase。对象存在后再看它的类型控件的属性可以进一步验证。比如读取 fileopen 的当前值能返回布尔值就说明对象已就绪。6.2 事件触发的验证仅验证对象存在还不够控件加载还可能静默失败。更可靠的自检是写一个临时事件处理脚本监听 OnDocumentOpened看文档打开完成后事件是否真正触发。我一般会在正式页面上保留一个调试开关用 URL 参数控制是否启用调试输出。// 调试页面里增加一个调试参数例如 /oa/edit.jsp?debug1 var ntkoobj document.getElementById(TANGER_OCX); var debug location.search.indexOf(debug1) -1; if (debug ntkoobj) { ntkoobj.fileopen false; // 验证属性写操作 ntkoobj.BeginOpenFromUrl(/oa/test.docx); // 验证方法调用 }这段代码在调试模式下手动触发一次文档打开如果控制台没有异常堆栈且文档在独立窗口里能正常显示说明属性赋值、方法调用、事件链路都没有问题。之后再撤掉调试代码恢复正常业务逻辑。6.3 我现在的集成习惯实际操作里集成一个这样的控件大部分时间不是花在写代码上而是花在环境核对上。我养成的习惯是每次接手这类项目先把客户端浏览器的位数、Office 的位数、浏览器版本三个信息记在项目说明里再对照产品支持环境表做一轮预判最后才动手装插件。因为 NTKO 控件的本事再大也架不住客户端装的是 64 位 Office、浏览器却是 32 位 Chrome 这类错位情况。从那以后我每次上线前都会强制走一遍“环境对齐 → 插件安装 → 静态资源引用 → 事件触发验证”这个四步流程顺序错一个后面排查成本就翻一倍。希望这些踩过的坑能帮你少走几趟弯路。本文还有配套的精品资源点击获取
