# 云文档小组件概述
云文档小组件（Docs add-on）是飞书开放平台应用能力之一，支持应用在云文档中扩展内容或添加快捷操作，实现文档协作与企业工作流的打通，进而提升效率。本文档介绍云文档小组件的应用场景、功能特性、视图类型、接入流程等，带你快速熟悉云文档小组件能力。
## 什么是云文档小组件
「云文档小组件」是飞书文档推出的一套开放能力，支持企业 IT 和第三方服务商开发各类垂直场景的应用，实现文档协作与企业工作流的打通，进而提升效率。
- 对于企业 IT：可以通过自建应用的方式，快速地将业务工作流集成到文档，满足垂直的业务场景，降本增效。如打通项目管理系统、打通 OA 审批系统、打通任务督办系统等。
- 对于第三方服务商：可以通过在上架小组件的方式，发布特定场景的应用，供用户直接在文档中调用。如辅助排版的格式检查工具、浏览 3D 建模模型的应用、Mermaid 代码生成 UML 图形的应用等。
- 对于普通云文档用户：可以在文档协作过程中，在文档右上角的 **`...`** 菜单、 **`+`** 号或 `/` 命令快速唤起小组件，一个文档，搞定工作。了解文档已支持的小组件，参考飞书帮助中心文档[文档小组件简介](https://www.feishu.cn/hc/zh-CN/articles/799229201268-%E6%96%87%E6%A1%A3%E5%B0%8F%E7%BB%84%E4%BB%B6%E7%AE%80%E4%BB%8B)。
## 应用场景
### 场景一：集成业务工作流
基于文档小组件的开放能力，可实现将业务工作流集成到文档，满足垂直的业务场景，降本增效。如打通项目管理系统、打通 OA 审批系统、打通任务督办系统等。
**实际客户案例**：安克创新打通自研的“问题管理系统”，借助文档高效处理问题，实现快速响应
### 场景二：文档创作提效
基于文档小组件的开放能力，应用可实现文本绘图、批量设置格式、格式检查等能力，帮助用户提升文档创作效率。
应用名称 | 描述
---|---
**文本绘图** | 使用 Mermaid 语言，用几行文本代码快速创建流程图、时序图等复杂图形
- 实时查看预览编辑效果，所见即所得
- 内置多种图形模板，助你快速上手
**批量设置格式** | 支持快速设置 BIUS、字体颜色、对齐方式等多达 13 种文字格式，“刷一刷”即可快速应用设置好的格式，助你写作事半功倍
**文字排版助手** | 你的智能格式纠正助手，检测格式问题（中英空格、中数空格、全角半角符号等），一键优化，提升工作效率
**时间轴** | 图形化地按时间、步骤、顺序表达项目和事件的发展进程、里程碑、关键点等内容。帮助文档编辑者高效生动表达，阅读者高效愉悦阅读
## 云文档小组件类型
云文档小组件有以下两种类型。其中，正文小组件类型支持多个附属视图。了解更多，参考[组件配置](https://open.feishu.cn/document/uAjLw4CM/uYjL24iN/docs-add-on/03-cloud-doc-block-rapid-development-guide/appjson-configuration-instructions)。
类型 | 描述 | 图示
---|---|---
正文小组件 | 正文小组件属于正文内容，作为一个内容块功能与体验与其他内容块（如：思维导图、流程图）一致。 | 
悬浮小组件 | 悬浮小组件是独立于云文档内容的模块，可以自由拖动定义大小不受正文干扰。 | 
**正文小组件附属视图说明**
正文小组件附属视图以正文小组件为载体，包括全屏视图、悬浮卡片视图、弹窗视图和模态框视图。具体说明如下表所示。
**注意事项**：- 只有正文小组件类型可以启动附属视图，附属视图调用 API 的约束和限制以其所在正文小组件载体为准。
- 附属视图需要在 `app.json` 中提前声明，并调用相关 API 进行展示和隐藏。详情参考 [附属视图配置](https://open.feishu.cn/document/uAjLw4CM/uYjL24iN/docs-add-on/03-cloud-doc-block-rapid-development-guide/appjson-configuration-instructions)。
视图类型 | 描述 | 使用方式
---|---|---
全屏视图 | 视图充满整体可视区域 | 在 `app.json` 中声明 `contributes.fullscreen`，并使用 [Service.Fullscreen](https://open.feishu.cn/document/uAjLw4CM/uYjL24iN/docs-add-on/05-api-doc/basic-data-reference---base/Service.Fullscreen.enterFullscreen) API 进行展示和隐藏
悬浮卡片视图 | 让正文小组件浮出正文内容 | 在 `app.json` 中声明 `contributes.floatCard`，并使用 [Service.FloatCard](https://open.feishu.cn/document/uAjLw4CM/uYjL24iN/docs-add-on/05-api-doc/basic-data-reference---base/Service.FloatCard.enterFloatCard) API 进行展示和隐藏
弹窗视图 | 展示一个弹窗 | 在 `app.json` 中声明 `contributes.popup`，并使用 [View.Action.showPopup](https://open.feishu.cn/document/uAjLw4CM/uYjL24iN/docs-add-on/05-api-doc/basic-data-reference---base/View.Action.showPopup) API 进行展示和隐藏
模态框视图 | 展示一个模态框 | 在 `app.json` 中声明 `contributes.modal`，并使用 [View.Action.openModal](https://open.feishu.cn/document/uAjLw4CM/uYjL24iN/docs-add-on/05-api-doc/basic-data-reference---base/View.Action.openModal) API 进行展示和隐藏
## 接入流程
云文档小组件接入流程如下所示。详情参考[快速上手](https://open.feishu.cn/document/uAjLw4CM/uYjL24iN/docs-add-on/03-cloud-document-widget-quick-development-guide/03-cloud-document-widget-quick-developme)。
## 开放能力
云文档小组件支持以下文档开放能力：
能力 | 详情
---|---
**可获取文档信息** | 自身信息：文档标题、内容（块的类型及数据）、统计数据、权限信息、历史记录
环境信息：黑暗模式、文档模式、多语言
**可调用文档功能** | 内容操作：工具栏、选人/会话组件、名片预览、图片预览、复制粘贴、撤销还原、展开/折叠块等
容器操作：窗口滚动、容器比例调整、提示消息配置、模态弹窗
**可编辑文档内容** | 具体内容：标题、正文（文本、图片、表格、任务、公式、@、文件、云文档、iframe 等）
格式：标题格式、文本加粗/斜体/下划线/颜色、引用、分隔线、有序/无序列表、代码块
**注意事项**：不支持三方内容的编辑，如在云文档中的 iframe 的操作。
**可感知文档变化** | 用户操作：文档的打开与关闭、文档内容变化、Block 的悬浮选中
用户权限：可阅读、可编辑、可评论
**可与用户互动** | 识别用户身份、获取用户授权、阅读进度感知、权限感知、协同编辑
**可完全掌控小组件本身，自定义渲染** | 改变自身形态（内嵌块、全屏、悬浮、正文扩展）
- 读取与存储数据
- 可引入外部能力
## 上手体验
你可在文档右上角的 **`...`** 菜单、 **`+`** 号或 `/` 命令快速唤起小组件，体验官方小组件。
### 打开云文档小组件
加号菜单或“/”快捷命令 | 顶部菜单栏
---|---
 | 
### 官方小组件
以下为部分官方小组件示例。
- **文字排版助手**：文档格式自动检测、一键优化。详情参考飞书帮助中心文档[使用文字排版助手小组件](https://www.feishu.cn/hc/zh-CN/articles/317905737314-%E4%BD%BF%E7%94%A8%E6%96%87%E5%AD%97%E6%8E%92%E7%89%88%E5%8A%A9%E6%89%8B%E5%B0%8F%E7%BB%84%E4%BB%B6)。
- **批量设置格式**：一次设置，多处使用。详情参考飞书帮助中心文档[使用批量设置格式小组件](https://www.feishu.cn/hc/zh-CN/articles/591902762640-%E4%BD%BF%E7%94%A8%E6%89%B9%E9%87%8F%E8%AE%BE%E7%BD%AE%E6%A0%BC%E5%BC%8F%E5%B0%8F%E7%BB%84%E4%BB%B6)。
- **时间轴**：简单输入关键信息，即可生成时间轴。详情参考飞书帮助中心文档[使用时间轴小组件](https://www.feishu.cn/hc/zh-CN/articles/429331890039-%E4%BD%BF%E7%94%A8%E6%97%B6%E9%97%B4%E8%BD%B4%E5%B0%8F%E7%BB%84%E4%BB%B6)。
- **文本绘图**：基于 Mermaid 语法，用几行代码轻松绘制多种图形。详情参考飞书帮助中心文档[使用文本绘图小组件](https://www.feishu.cn/hc/zh-CN/articles/496118428959-%E4%BD%BF%E7%94%A8%E6%96%87%E6%9C%AC%E7%BB%98%E5%9B%BE%E5%B0%8F%E7%BB%84%E4%BB%B6)。
## API 参考
云文档小组件提供了一系列的 API，支持对文档内容及状态的增删查改等能力。借助这些 API ，开发者可以构建出丰富的云文档小组件功能。详情参考 [云文档小组件 API](https://open.feishu.cn/document/uAjLw4CM/uYjL24iN/docs-add-on/05-api-doc/05-api-doc)。
## 常见问题
### 1. 云文档小组件和云文档组件有什么区别？
云文档组件和云文档小组件是飞书开放平台中针对不同场景提供的两种能力，主要区别如下：
- 概念不同：
- 云文档小组件是飞书云文档内部的一种扩展能力，以块（Block）的形式存在，允许开发者在云文档中嵌入自定义的功能模块
- 云文档组件是一种网页组件，可以将云文档嵌入到普通 Web 网页中
- 适用场景不同：
- 云文档小组件用于在飞书云文档中直接集成业务流程或工具的场景
- 云文档组件用于在 Web 网页中直接查看或操作飞书云文档，适用需要在外部系统中集成飞书文档的场景
### 2. 开发一个小组件需要哪些技术能力？
小组件基于标准 Web 技术开发，需掌握以下基础知识：
- **HTML**：页面结构搭建
- **CSS**：样式设计与布局
- **JavaScript**：交互逻辑实现
另外，云文档小组件开发还有以下特性：
- **框架自由**：不局限框架，你可以选择自己熟悉的技术栈或者是组件库。
- **开箱即用模板**（推荐）：基于 React 生态的、从服务构建、调试、到发布的完整工具集
- **自定义方案**：可搭配任意构建工具，最终部署到平台 CDN 即可
### 3. 正文小组件附属视图中的弹窗视图和模态框视图有何区别？我该如何选择？
大多数情况下，建议使用模态框视图。模态框视图会自动拥有关闭按钮，标题和背景蒙层。
如果你不需要这些能力，则可以使用弹窗视图。弹窗视图的所有展示内容都由小组件开发者来绘制。