Office 加载项开发最佳做法Best practices for developing Office Add-ins

有效的外接程序提供独特且极具吸引力的功能,采用具有视觉吸引力的方式扩展 Office 应用程序。若要创建出色的外接程序,需为用户提供极具吸引力的首次使用体验、设计一流的 UI 体验和优化外接程序的性能。将本文中描述的最佳实践应用于创建有助于您的用户快速有效地完成其任务的外接程序。Effective add-ins offer unique and compelling functionality that extends Office applications in a visually appealing way. To create a great add-in, provide an engaging first-time experience for your users, design a first-class UI experience, and optimize your add-in's performance. Apply the best practices described in this article to create add-ins that help your users complete their tasks quickly and efficiently.


如果您计划将加载项发布到 AppSource,并使其在 Office 体验中可用,请确保您符合商业市场认证策略If you plan to publish your add-in to AppSource and make it available within the Office experience, make sure that you conform to the Commercial marketplace certification policies.例如,若要通过验证,您的外接程序必须在支持您定义的方法的所有平台上工作(有关详细信息,请参阅section 1120.3Office 外接程序主机和可用性页面)。 For example, to pass validation, your add-in must work across all platforms that support the methods that you define (for more information, see section 1120.3 and the Office Add-in host and availability page).

提供明确值Provide clear value

  • 创建可帮助用户快速、高效地完成任务的外接程序。专注于对 Office 应用程序有用的方案。例如:Create add-ins that help users complete tasks quickly and efficiently. Focus on scenarios that make sense for Office applications. For example:
  • 使核心创作任务更快、更简单,且中断更少。Make core authoring tasks faster and easier, with fewer interruptions.
  • 在 Office 内启用新方案。Enable new scenarios within Office.
  • 在 Office 主机内嵌入补充服务。Embed complementary services within Office hosts.
  • 改善 Office 体验来提高工作效率。Improve the Office experience to enhance productivity.
  • 通过创建极具吸引力的首次运行体验,确保用户能够快速明确加载项的价值。Make sure that the value of your add-in is clear to users right away by creating an engaging first run experience.
  • 创建有效的 AppSource 一览。在标题和说明中明确介绍加载项的优势。请勿依赖品牌来传达加载项的用途。Create an effective AppSource listing. Make the benefits of your add-in clear in your title and description. Don't rely on your brand to communicate what your add-in does.

创建极具吸引力的首次运行体验Create an engaging first-run experience

  • 要用具有高可用性和直观性的首次体验吸引新用户。请注意,用户从商店下载外接程序之后,仍可决定是使用还是放弃该外接程序。Engage new users with a highly usable and intuitive first experience. Note that users are still deciding whether to use or abandon an add-in after they download it from the store.

  • 明确用户与您的外接程序交互所需执行的步骤。使用视频、泡沫垫、分页面板或其他资源来吸引用户。Make the steps that the user needs to take to engage with your add-in clear. Use videos, placemats, paging panels, or other resources to entice users.

  • 在启动时强调您的外接程序的价值主张,而不只是让用户登录。Reinforce the value proposition of your add-in on launch, rather than just asking users to sign in.

  • 提供用以指导用户的教学 UI,并使您的 UI 富有个性化。Provide teaching UI to guide users and make your UI personal.


  • 如果内容外接程序绑定到用户文档中的数据,请将那些用于向用户显示要使用的数据格式的示例数据或模板包含在内。If your content add-in binds to data in the user's document, include sample data or a template to show users the data format to use.


  • 提供免费试用版。如果加载项需要订阅,请让某些功能无需订阅也可使用。Offer free trials. If your add-in requires a subscription, make some functionality available without a subscription.

  • 让注册非常简单。预先填充某些信息(如电子邮件、显示名称),并跳过电子邮件验证。Make signup simple. Prefill information (email, display name) and skip email verifications.

  • 避免弹出窗口。如果必须使用它们,请引导用户启用弹出窗口。Avoid pop ups. If you have to use them, guide the user to enable your pop up.

如需你在开发首次运行体验时可应用的模式,请参阅适用于 Office 加载项的 UX 设计模式For patterns that you can apply as you develop your first-run experience, see UX design patterns for Office Add-ins.

使用加载项命令Use add-in commands

  • 使用加载项命令,为加载项提供相关 UI 入口点。有关详细信息(包括设计最佳做法),请参阅加载项命令Provide relevant UI entry points for your add-in by using add-in commands. For details, including design best practices, see add-in commands.

应用用户体验设计原则Apply UX design principles

  • 确保你的外接程序的外观和功能很好地补充了 Office 体验。使用 Office UI FabricEnsure that the look and feel and functionality of your add-in complements the Office experience. Use Office UI Fabric.

  • 支持内容胜过支持部件版式。避免使用对用户体验毫无价值的不必要的 UI 元素。Favor content over chrome. Avoid superfluous UI elements that don't add value to the user experience.

  • 保持用户处于可控状态。确保用户了解重要的决定,并且可以轻松地倒退外接程序执行的操作。Keep users in control. Ensure that users understand important decisions, and can easily reverse actions the add-in performs.

  • 使用品牌唤起用户的信任感和亲切感。但不要过度使用品牌或向用户做广告推销。Use branding to inspire trust and orient users. Do not use branding to overwhelm or advertise to users.

  • 避免滚动。优化为 1366 x 768 分辨率。Avoid scrolling. Optimize for 1366 x 768 resolution.

  • 不包含未授权的图像。Do not include unlicensed images.

  • 在加载项中使用简单明确的语言Use clear and simple language in your add-in.

  • 考虑辅助功能 - 方便所有用户都可以与加载项轻松交互,并提供屏幕阅读器等辅助技术。Account for accessibility - make your add-in easy for all users to interact with, and accommodate assistive technologies such as screen readers.

  • 针对所有平台和输入方法(包括鼠标/键盘和 触摸)的设计。确保 UI 可响应不同的外观设置。Design for all platforms and input methods, including mouse/keyboard and touch. Ensure that your UI is responsive to different form factors.

触摸优化Optimize for touch

  • 使用 Context.touchEnabled 属性检测运行加载项的主机应用是否已启用触控。Use the Context.touchEnabled property to detect whether the host application your add-in runs on is touch enabled.


    Outlook 不支持此属性。This property is not supported in Outlook.

  • 确保所有控件都相应符合触控交互的尺寸大小。例如,按钮有足够大的触摸目标,且输入框要足够大,方便用户输入。Ensure that all controls are appropriately sized for touch interaction. For example, buttons have adequate touch targets, and input boxes are large enough for users to enter input.

  • 不依赖于诸如悬停或用鼠标右键单击等非触摸式输入方法。Do not rely on non-touch input methods like hover or right-click.

  • 确保外接程序可以在纵向和横向模式中正常工作。请注意在触控设备上,外接程序的一部分可能通过软键盘隐藏。Ensure that your add-in works in both portrait and landscape modes. Be aware that on touch devices, part of your add-in might be hidden by the soft keyboard.

  • 使用旁加载在实际设备上测试加载项。Test your add-in on a real device by using sideloading.


若要对设计元素使用 Office UI Fabric,需要处理其中许多元素。If you're using Office UI Fabric for your design elements, many of these elements are taken care of.

优化和监视加载项性能Optimize and monitor add-in performance

  • 创建快速 UI 响应的感觉。外接程序的加载时间应在 500 毫秒以内。Create the perception of fast UI responses. Your add-in should load in 500 ms or less.

  • 确保所有用户交互响应时长都在一秒内。Ensure that all user interactions respond in under one second.

  • 为长时间运行的操作提供加载指示器。Provide loading indicators for long-running operations.

  • 将 CDN 用于主机图像、资源和公用库。尽可能地从一个位置进行加载。Use a CDN to host images, resources, and common libraries. Load as much as you can from one place.

  • 请按照标准 Web 实践来优化您的网页。在生产中,仅使用库的缩小版本。仅加载所需的资源,并优化加载资源的方式。Follow standard web practices to optimize your web page. In production, use only minified versions of libraries. Only load resources that you need, and optimize how resources are loaded.

  • 如果操作执行需要一段时间才能完成,请向用户提供反馈。请注意下表中列出的阈值。有关详细信息,请参阅 Office 加载项的资源限制和性能优化If operations take time to execute, provide feedback to users. Note the thresholds listed in the following table. For additional information, see Resource limits and performance optimization for Office Add-ins.

    交互类Interaction class 目标Target 上限Upper bound 人类感知Human perception
    即时Instant <=50 毫秒<=50 ms 100 毫秒100 ms 没有明显的延迟。No noticeable delay.
    快速Fast 50-100 毫秒50-100 ms 200 毫秒200 ms 最小限度的明显延迟。不需要反馈。Minimally noticeable delay. No feedback necessary.
    典型Typical 100-300 毫秒100-300 ms 500 毫秒500 ms 较快,但不够快,不能称之为快速。不需要反馈。Quick, but too slow to be described as fast. No feedback necessary.
    快速响应Responsive 300-500 毫秒300-500 ms 1 秒1 second 不快,但仍然感觉反应灵敏。不需要反馈。Not fast, but still feels responsive. No feedback necessary.
    连续Continuous > 500 毫秒>500 ms 5 秒5 seconds 中等等待时间,不再感觉反应灵敏。可能需要反馈。Medium wait, no longer feels responsive. Might need feedback.
    受限Captive > 500 毫秒>500 ms 10 秒10 seconds 较长,但不足以执行其他操作。可能需要反馈。Long, but not long enough to do something else. Might need feedback.
    扩展Extended > 500 毫秒>500 ms > 10 秒>10 seconds 长到足以在等待时执行其他操作。可能需要反馈。Long enough to do something else while waiting. Might need feedback.
    长时间运行Long running > 5 秒>5 seconds > 1 分钟>1 minute 用户当然可以执行其他操作。Users will certainly do something else.
  • 监视您的服务运行状况,并使用遥测监视用户的成功。Monitor your service health, and use telemetry to monitor user success.

  • 最大限度地减少外接加载项与 Office 文档之间的数据交换。Minimize data exchanges between the add-in and the Office document. 有关详细信息,请参阅避免在循环中使用 context. sync 方法For more information, see Avoid using the context.sync method in loops.

加载项市场营销Market your add-in

  • 将加载项发布到 AppSource,并在网站中对它进行宣传。创建有效的 AppSource 一览Publish your add-in to AppSource and promote it from your website. Create an effective AppSource listing.

  • 使用简洁且富有描述性的加载项标题。字符数不得超过 128 个。Use succinct and descriptive add-in titles. Include no more than 128 characters.

  • 为您的外接程序撰写简短且富有吸引力的描述。回答"此外接程序解决哪些问题?"这一问题。Write short, compelling descriptions of your add-in. Answer the question "What problem does this add-in solve?".

  • 在您的标题和说明中传达外接程序的价值主张。不要依赖于您的品牌。Convey the value proposition of your add-in in your title and description. Don't rely on your brand.

  • 创建有助于用户查找和使用加载项的网站。Create a website to help users find and use your add-in.

使用支持 Internet Explorer 的 JavaScriptUse JavaScript that supports Internet Explorer

对于某些版本的 Office 和 Windows,运行外接程序的 JavaScript 引擎由 Internet Explorer 提供。For some versions of Office and Windows, the JavaScript engine in which add-ins run is provided by Internet Explorer. Internet Explorer 引擎不支持高于 ES5 的 JavaScript 版本。The Internet Explorer engine does not support versions of JavaScript later than ES5. 这意味着,如果没有特殊处理,加载项所使用的 JavaScript 文件不能使用在 ES5 后添加到语言中的语法、类型或方法。This means that without special handling, the JavaScript files that your add-in serves cannot use syntax, types, or methods that were added to the language after ES5. 这并不意味着必须以 ES5 语法编写This does not mean that you must write in ES5 syntax. 有两个其他选项:You have two other options:

  • ECMAScript 2015 (也称为 ES6)或更高版本 JavaScript 中或在 TypeScript 中编写代码,然后使用编译器(如babeltsc)将代码编译为 ES5 JavaScript。Write your code in ECMAScript 2015 (also called ES6) or later JavaScript, or in TypeScript, and then compile your code to ES5 JavaScript using a compiler such as babel or tsc.
  • 在 ECMAScript 2015 或更高版本的 JavaScript 中编写,但还要加载一个polyfill库,如core-JS ,使 IE 能够运行您的代码。Write in ECMAScript 2015 or later JavaScript, but also load a polyfill library such as core-js that enables IE to run your code.

另请参阅See also