开发指南/开发多维表格插件/多维表格数据表视图开发指南
# 多维表格数据表视图开发指南

## 步骤一：创建插件应用

1. 登录[Lark开发者后台](https://open.larksuite.com/app)。
1. 在开发者后台首页，单击 **创建企业自建应用**，填写应用名称、描述以及图标信息，然后单击 **创建**。

![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/acdac87264faa1ba8ff7858aaf4907cb_6uF6VR31Oo.png?height=1526&lazyload=true&width=2512)

> 本指南以 **企业自建应用** 为例介绍如何开发多维表格数据表视图。如果你想创建一个给不同企业使用的应用，可选择 **创建商店应用**。创建商店应用请参考[一、服务商入驻](https://open.larksuite.com/document/uMzNwEjLzcDMx4yM3ATM/uUzNwEjL1cDMx4SN3ATM)。关于 **商店应用** 和 **企业自建应用** 更详细的区别和介绍请查阅 [应用类型简介 - 快速了解Lark中的应用类型 - 开发文档 - Lark开放平台](https://open.larksuite.com/document/home/app-types-introduction/overview)。

3. 点击左侧 **添加应用能力**，选择 **多维表格插件** ，选择 **数据表视图**，最后点击 **+添加**。

![35.png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/2f285fa6fc51680d24c51ee048ef5cff_hsuaQOF6Db.png?height=1604&lazyload=true&width=3250)

![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/a0340da0cc94d5baa4d5e90cd30b9515_y7kmQ0Jsjb.png?height=1692&lazyload=true&width=3596)

4. 记录 App ID 和 BlockTypeID。
在创建出来的页面，记录下 BlockTypeID，切换到 **凭证与基础信息**，记录下 App ID。App ID 和 BlockTypeID将用于项目初始化。

![数据表视图-appid.png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/d5e50f6fda12da9e38280e2904f55085_lTX7GsyfBu.png?height=1424&lazyload=true&width=2530)

![数据表视图-blk.png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/8d69c6e078af29bf4c6a9a8a68496cf2_FPPIbqzQqg.png?height=1572&lazyload=true&width=2632)

## 步骤二：搭建开发环境

你需要在本地安装Lark开发者工具并使用工具初始化自动化插件项目。

1. 安装 CLI。
```
npm install @lark-opdev/cli@latest -g -f
```
> CLI 详细使用方式和指令请参考：[Lark开发者工具-命令行](https://open.larksuite.com/document/uYjL24iN/uEzMzUjLxMzM14SMzMTN/ide-with-commands)。
2. 登录 CLI。
	- CLI 初次使用需要登录，打开终端，执行下面命令`opdev login`登录CLI。

- 这里开发环境选择 `Lark`： 

![cli登陆.png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/518971a6fc6cbdcef4e3484fc70a06a4_trdNQyjdhf.png?height=264&lazyload=true&width=1680)

- 选择开发环境后会自动打开浏览器扫码登录页面，请根据指示进行登录：
    ![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/29a9d31d89de178dbb46556595685fc0_sh8z12oWkk.png?height=1826&lazyload=true&width=2344)

- 扫码完成登录后命令行会提示登录成功：

![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/d09ec83ffa1cff6b5afba3ffde0f46d9_McqybeIn86.png?height=100&lazyload=true&width=734)

3. 创建项目。使用下面命令创建模板项目：
	- app-dir 需替换成你项目的目录名。
	- view-dir 需替换成你插件的目录名。
    ```
    opdev create ${app-dir}/${view-dir}  -a bitable-extensions -s table-view
    ```
	创建过程中会询问 `Do you need to create a new application?`
	- 选择`No`，则会要求填写步骤一中获取的 ID 信息 ： App ID 和 BlockTypeID。你也可以在创建完成后的项目中修改block.json文件中的blockTypeID和app.json文件中的appId，让代码用于你的其它应用插件。关于这2个文件的详细说明，可以参考本文中问题整理中的**代码上传的原理与二次开发**。

![8.png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/34ab2a6658ff74426b67b92c0e9bf50a_fgM8O0me2u.png?height=226&lazyload=true&width=1136)

> 生成的模板是一个 React Demo Project，符合 NPM Module 定义，如果需要创建其他模板比如vue模板，可以使用`opdev create`命令，按照提示填写项目存放路径，并选择对应模板即可。
    > ![image.png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/a05d4404ad9c504480516b3e41b71ed4_CiAwJE0zju.png?height=230&lazyload=true&width=1290)
        >
        > 在生成模板的 `block.json` 文件中的 `blockTypeID` 字段就是初始化的时候命令行中所填的 BlockTypeID 。
        >
        > `app.json` 文件中的 `appId` 就是初始化的时候命令行中所填写的 App ID。
	- 选择 Yes ，如果没有ISV资质，将自动创建一个**企业自建应用**以及一个**视图插件**。

![10.png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/013a305f86afcae1bcc3b93e250f4a07_V5PG2McI8B.png?height=206&lazyload=true&width=1648)

如果有ISV资质，则可以选择创建商店应用`Store Apps`，或者企业自建应用 `Custom Apps`。

4. 初始化项目。
使用下面命令安装项目依赖：
```
cd ${app-dir}/${view-dir} 
npm install
```

## 步骤三：调试

默认创建出来的项目使用 React + Typescript + Webpack 作为开发环境；你也可以选择习惯使用的开发环境，例如 Vue；但请保持使用 Webpack 开发，并安装 [@lark-opdev/block-bitable-webpack-utils](https://www.npmjs.com/package/@lark-opdev/block-bitable-webpack-utils)。

1. 执行下面命令启动 WebpackDevServer 进入开发调试。
```
npm run start
```
其会自动帮你打开一篇多维表格文档，并带上 `debugPort=${当前应用端口}` 的调试参数。

2. 在打开的多维表格页面中，点击 **新建视图按钮**。

![记录视图-新建视图-1.png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/1aa05e4ca2e0e2325cdd89a37f7d8959_CRj4tlugME.png?height=1824&lazyload=true&width=3134)

3. 或者点击 **添加更多插件**。

![记录视图-新建视图-2.png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/6afab8eeef28c9844f8b4d99db411b43_R4Kt1sCDfB.png?height=2304&lazyload=true&width=3028)

4. 选择你本地开发的组件（一般是 blk_xxx），点击 **+** **添加插件**。

![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/f1f25fec1ef5095644ba74b120515f51_fHaQ3A8z7x.png?height=1862&lazyload=true&width=2782)

5. 在新 Tab 中调试你的插件。

![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/7da3741b097b71837481f2be5d0b5cf8_5DcybqegYy.png?height=1738&lazyload=true&width=2914)

### 通过 SDK 调用 API

我们通过 [@lark-opdev/block-bitable-api](https://www.npmjs.com/package/@lark-opdev/block-bitable-api) 这个 SDK 提供了一些 API 能力，可以读写 Bitable 数据，请参考API列表。
```
// 调用示例
import { bitable } from "@lark-opdev/block-bitable-api";
const tableMetaList = await bitable.base.getTableMetaList();
```

### 申请 API 对应的权限

1. API 的调用受权限管控，请根据具体 API 所需的调用权限进入开发者后台，找到 **权限管理** 页面，搜索对应的权限。

![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/e23b5a573e8acd28d161982b8339d40b_N2ZuPbEJ5U.png?height=546&lazyload=true&width=1758)

2. 点击**开通权限**按钮。

![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/00847d73b2a0b08d12058b47f402edab_sG7gObu0Ft.png?height=1064&lazyload=true&width=3174)

3. 重新发布一次应用，版本详情中可见刚才申请的权限，待申请发布的应用灰度后权限就会生效。

![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/be98fb5ef53018c9f9781dce6aca9af0_vEQGkR7Jj8.png?height=1312&lazyload=true&width=1670)

### 优化调试

如果你期望更换打开的多维表格文档，可以更改 `block.json` 中的 `url` 属性。
```
{
  "manifestVersion": 1,
  "blockTypeID": "blk_6412ffb4a38040143c2d8bc5",
  "projectName": "table_view",
  "url": "https://example.feishu.cn/base/KjexxxX7CaR8CgsZVNGbKHCOcMh?table=tbl6u74ixxxeA9aC&view=vewkevI7IE"
}
```
如果你期望以固定的 v 或 vb 打开多维表格，可以在 `debug.json` 中增加如下属性：
> v/vb 简单理解就是多维表格的版本，通过指定不同的版本号可以提前调试一些暂时还未上线的功能。
```
{
  "v": "1.0.1.xxxx",
  "vb": "1.0.0.xxxx"
}
```

## 步骤四：发布与安装

### 发布

1. 上传代码
你可以使用下面命令来使用编译并上传：
```
npm run upload
```
也可以使用下面命令来只上传：
```
opdev upload ./dist
```
上传过程中，需要输入**插件的版本号**，请使用形如 `0.0.1` 的语义化版本，且保证版本递增。

![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/c5de5fee643f17a072f933efc0be180d_m5Q2JVFSSC.png?height=132&lazyload=true&width=852)

2. 重新进入开发者后台，切换到 **数据表视图**。**小组件** **版本** 选刚上传时填入的版本号，然后上传图标、填写名称和介绍。最后点击 **保存**。

![34.png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/3e3ef0d6d0a5aa6f68fc166b30270412_aUCN3GfZUJ.png?height=2106&lazyload=true&width=2950)

> 这里以 **企业自建应用** 的发布流程为例。 如果你使用的是 **商店应用**，则需要注意商家发布需要经过严格的审核流程，详细流程请参考[一、服务商入驻](https://open.larksuite.com/document/uMzNwEjLzcDMx4yM3ATM/uUzNwEjL1cDMx4SN3ATM)。
3. 发布
	- 切换到 **版本管理与发布**。然后点击 **创建版本**。![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/f932585f036a21e2bee2c98bd078507c_dByBJUzdcy.png?height=1726&lazyload=true&width=3408)

- 填入 **应用版本号**、**更新说明**（注意：这里的版本是应用版本，一个应用可能有多个插件）。
![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/e53720756095c5d7dda8adb02cd039f5_ysvVX0TY5x.png?height=1774&lazyload=true&width=3426)

- 确认权限和可见性范围，确认无误后点击 **保存**。
	- 点击 **申请线上发布**，等待管理员审核。
![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/72c41e3e8d5d6cbe44d3fe9f1f4f8ad9_9LH6JLITCc.png?height=1792&lazyload=true&width=3440)

### 安装

这里以企业自建应用为例，应用审核通过后可见用户便可以将你的插件安装到多维表格插件视图中。
点击添加插件按钮：
![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/5e88872f1c8cfd32d13d3f22b28227c6_dMmnoWOk0i.png?height=1678&lazyload=true&width=2884)
添加后便能够在多维表格的插件视图中看到你的应用了：
![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/60176979eacad86d3560c7e198057849_UaSivDBzGK.png?height=1778&lazyload=true&width=2910)

## 常见问题

### Q：代码上传的原理与二次开发
当执行npm run upload时，开发工具@lark-opdev/cli会在执行该命令的目录同层级下寻找app.json，并识别其中的appId字段，其中appId的含义便是开放平台中的你的应用的应用凭证，如果想将代码上传到其他的应用，就可以修改app.json中的appId字段为目标应用的appId

![image.png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/b62b3ab961ffb3c12969e2a8e5c983df_hMdu7r7yDc.png?height=936&lazyload=true&width=2630)

接下来会在执行该命令下一层级的目录中的block.json中找到blockTypeID，这里的blockTypeID是应用（appId对应的应用）中的某个应用能力的BlockTypeID。

需要注意应用能力的类型需要与代码的模板类型对应上，比如自动化插件代码中的blockTypeID只能填写开放平台中的**多维表格自动化操作**类型的BlockTypeID，而不可填写为**多维表格记录视图**或者**多维表格数据表视图**的BlockTypeID。

![image.png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/e3a1c35fe6cb2b637a299fa56a9ca9e1_NQVm0eXJbG.png?height=788&lazyload=true&width=1956)

然后@lark-opdev/cli会在当前登陆用户的应用中根据根据app.json中appId找到需要上传的目标应用，然后根据blockTypeID在该应用下找到对应的应用能力，最终将代码上传到该应用能力。

如果想要将代码上传到其他的应用能力中，就可以直接修改这2个文件，之后再执行`npm run upload`。

如果上传失败，可以使用`opdev whoami` 命令查看当前登录用户。确保当前用户的开放平台中拥有app.json中appId对应的应用，并且该应用中拥有block.json中blockTypeID对应的应用能力。