快速上手开发

本文介绍如何快速上手开发一个 Hello World 自建小程序。请提前阅读小程序开发简介，准备好开发环境，并了解你即将使用的开发者工具。

开发一个在前端可安装使用的 Hello World 小程序需要以下几步：

创建小程序
安装小程序开发工具
初始化小程序
启动小程序
预览小程序
发布小程序
安装使用自建小程序

第一步：创建小程序

创建小程序的步骤如下：

前往小程序：首先打开维格表，打开任意一张表格，点击右上角的「小程序」。
前往小程序中心：点击左上角的「+」添加一个小程序，打开「小程序中心」，点击「空间站自建」后，会看到「创建小程序」的入口。
编辑自建小程序信息：
1. 输入小程序名称
2. 选择从一个组件模板开始开发

第二步：安装小程序开发工具

在终端中执行下列命令：

npm install -g @apitable/widget-cli

安装小程序开发工具

第三步：初始化小程序

这一步是为了认证你的开发者身份，并创建新组件的项目文件。

如果你此前未生成过 API Token，在执行完 init 命令后，需要输入 API Token。

获取 API Token 的步骤如下：

登录维格表，点击左下角的个人头像，进入「用户中心」，前往「开发者配置」界面。
点击「+」号生成 API Token。注意：首次生成时需要绑定邮箱。
复制 API Token。

注意：
请妥善保管你的 API Token，如果 API Token 泄露，他人可能随意篡改你的表格中的数据。
如果 API Token 意外泄露，你可以在「开发者配置」界面重新生成 Token，保证数据安全。

第四步：启动小程序

这一步是为了启动小程序的本地服务，进入开发模式。

第五步：预览小程序

为了在小程序面板中成功预览自建小程序，需要解除浏览器对加载本地代码的安全限制。请按照以下步骤操作：

方案一：allow-insecure-localhost（适用于旧版本的 Chrome 浏览器）

将以下代码复制到 Chrome 浏览器 URL 栏，按回车访问：
```
chrome://flags/#allow-insecure-localhost
```
对高亮的“Allow invalid certificates for resources loaded from localhost”，选择 enable：
重启浏览器

方案二：temporary-unexpire-flags-m118（未来可能被移除）

在新版本的 Chrome 浏览器中，由于 #allow-insecure-localhost 标志已被移除，您可以通过以下步骤启用类似功能：

将以下代码复制到 Chrome 浏览器 URL 栏，按回车访问：
```
chrome://flags/#temporary-unexpire-flags-m118
```
启用这个标志以允许不安全的本地主机连接。
重启浏览器
将以下代码复制到 Chrome 浏览器 URL 栏，按回车访问：
```
chrome://flags/#allow-insecure-localhost
```
对高亮的“Allow invalid certificates for resources loaded from localhost”，选择 enable：
重启浏览器

注意：这个方法可能不是长期有效的，具体取决于 Chrome 浏览器的后续更新。

方案三：手动访问一次本地资源

运行小程序开发环境，通常会通过 widget-cli start 命令启动，并获取一个类似于 https://localhost:9000/widget_bundle.js 的本地服务地址。
直接在浏览器中访问这个地址。
浏览器可能会因为安全问题而阻止访问。此时，点击「高级」选项，然后选择「继续前往（localhost）」以允许访问。
接下来就可以继续预览小程序了。

为什么需要这么做？
小程序开发时，需要通过维格表网页加载本地地址的资源，由于浏览器安全规范，本地代码也需要使用 https 协议。所以必须解除浏览器对于加载本地 https 代码的安全限制才可让小程序正常运行。

第六步：发布小程序

你的自建小程序开发完毕之后，就可以发布到小程序中心供其他空间站成员安装使用了。

在执行发布动作之前，我们还需要做一些润色工作：

准备一张 64*64的 png 图片作为你的小程序图标，替换掉根目录下的 package_icon.png。
进入根目录下 widget.config.json 文件修改 name 和 description, 给你的小程序取一个名字并且加上功能描述。

开发完成并预览无误后，先在终端输入 Ctrl + C 退出运行状态，再执行下列命令发布：

widget-cli release

// 如果你使用的是社区版或私有化版本，同时未配置 OSS 对外地址，则需要指定编译后代码上传地址
widget-cli release --uploadHost <host>

发布成功后，你的小程序代码将上传到维格表的服务器。

此时，你可以点击小程序菜单里的“退出开发模式”，便能看到你的最新小程序的效果了，并且也能在小程序中心 -> 空间站自建下方看到你新发布的小程序。

同时，需要注意的是自建小程序仅能由小程序创建者的账号发布和更新。如果需要更换自建小程序的发布者可以让小程序创建者或小程序所在空间站管理员移交发布权。

附录：小程序工程文件目录结构

打开 widget-cli 生成的小程序工程文件夹，你会看到以下目录结构：

my-widget
├── dist/
├── node_modules/
├── src/
│   └── index.ts
├── .gitignore
├── .apitable.yml
├── author_icon.png
├── cover.png
├── package_icon.png
├── package.json
└── widget.config.json

dist/：存放构建完毕的文件地址，你不需要对此文件夹下的内容进行修改
node_modules/：标准的 JavaScript 依赖包目录，你不需要对此文件夹下的内容进行修改
src/：这里是你主要工作的目录，绝大部分开发工作在此完成
.gitignore：描述哪些文件需要被 git 忽略掉，一般情况下不需要编辑此文件
.apitable.yml：维格表私有配置文件，通常这里面会存放 host 和 token 的本地缓存，widget-cli 会自动维护里面的内容，不需要手动编辑（需要注意检查当前使用的 widget-cli 是 @apitable/widget-cli 还是 @vikadata/widget-cli，如果是前者，私有配置文件名为 .apitable.yml，如果是后者，那么则为.vika.yaml。建议使用 @apitable/widget-cli，@vikadata/widget-cli 已停止更新维护）
- host：维格表 API 的 host 地址，通常情况下不需要修改
- token：用户令牌，可以鉴别当前用户是否有对小程序的发布权，请妥善保管和管理
author_icon.png：用户头像图片，64*64 的 png 文件，你可以将其替换成你想要的头像
cover.png：用户头像图片，16:9 的 png 文件, 推荐 464*264，你可以将其替换成你想要的图片
package_icon：小程序图标，64*64 的 png 文件，你可以将其替换成你想要的小程序图标
package.json：标准的 JavaScript 依赖描述文件，你可以根据社区标准来维护这个文件
widget.config.json：小程序配置文件，里面包含了小程序的配置信息比如、组件名、描述，你可以根据需要修改它。下节有具体描述。

widget.config.json

{
  /** [自动生成] 小程序代码包的 Id，初始化时自动生成 */
  "packageId": "wpkvaNpJiDstV",
  /** [自动生成] 全局小程序代码包的 Id，发布到全局时自动生成*/
  "globalPackageId": "wpkSybhcxsmGM"
  /** [自动生成] 空间站 ID，小程序必须绑定一个空间站 */
  "spaceId": "spczdmQDfBAn5",
  /** [自动生成] 小程序代码入口, 支持 js 和 ts */
  "entry": "./src/index.ts",
  /** [可修改] 小程序名称，显示在小程序安装界面*/
  "name": {
    "zh-CN": "开发者模板",
    "en-US": "developerTemplate"
  },
  /** [可修改] 小程序图标路径，发布时自动上传，显示在小程序安装界面, 请使用 64x64 png 文件*/
  "icon": "./package_icon.png",
  /** [可修改] 小程序封面图，发布时自动上传，显示在小程序安装界面, 请使用 16:9 的图片，推荐使用 464 x 264 的 png 或 jpg 文件 */
  "cover": "./cover.png",
  /** [可修改][可选] 作者名称，显示在小程序安装界面（站内小程序不生效） */
  "authorName": "Vika",
  /** [可修改][可选] 作者图标路径，发布时自动上传，显示在小程序安装界面, 请使用 64x64 png 文件（站内小程序不生效）*/
  "authorIcon": "./author_icon.png",
  /** [可修改] [可选] 作者官网地址，点击作者图标后跳转（站内小程序不生效）*/
  "authorLink": "https://vika.cn",
    /** [可修改] [可选] 作者联系邮件（站内小程序不生效）*/
  "authorEmail": "dev@vikadata.com",
  /** [可修改] 小程序描述，显示在小程序安装界面 */
  "description": {
    "zh-CN": "developerTemplate 的描述",
    "en-US": "developerTemplate description"
  },
  /** [可选] 沙箱环境，是否启动沙箱环境渲染小程序 */
  "sandbox": true,
  /** [可选] 运行环境（mobile：移动端，desktop：桌面端），指定小程序的运行环境，如果不填默认["mobile", "desktop"] */
  "runtimeEnv": ["mobile", "desktop"],
  /** [可选] 安装环境（dashboard：仪表盘，panel：小程序面板），指定小程序的安装环境，如果不填默认["dashboard", "panel"] */
  "installEnv": ["dashboard", "panel"]
}

第一步：创建小程序​

第二步：安装小程序开发工具​

第三步：初始化小程序​

第四步：启动小程序​

第五步：预览小程序​

方案一：allow-insecure-localhost（适用于旧版本的 Chrome 浏览器）​

方案二：temporary-unexpire-flags-m118（未来可能被移除）​

方案三：手动访问一次本地资源​

第六步：发布小程序​

附录：小程序工程文件目录结构​

widget.config.json​