先决条件

在开始之前,请确保您已安装以下内容:

设置您的开发环境

1. 创建新的插件项目

您有三种选项来开始您的插件项目:

选项A:使用CodeSandbox(推荐快速开始)

  1. 访问我们的Blinko插件模板在CodeSandbox
  2. 点击”Fork”创建您自己的副本
  3. 开发服务器将自动启动
  4. 您将在http://localhost:3000看到连接说明:
    • 外部访问:ws://<sandbox-id>.csb.app:8080

这是最快的开始方式,因为它:

  • 不需要本地设置
  • 提供即时开发环境
  • 提供内置文档服务器
  • 支持轻松分享和协作

选项B:使用模板仓库

  1. 访问Blinko插件模板
  2. 点击”Use this template”按钮
  3. 按照GitHub提示创建您的仓库

选项C:克隆模板仓库

git clone https://github.com/blinko-space/blinko-plugin-template.git my-blinko-plugin
cd my-blinko-plugin

2. 安装依赖

一旦您设置好项目,安装依赖:

bun install

3. 启动开发服务器

启动开发服务器以开始处理您的插件:

bun dev

这将启动一个本地开发服务器,通常在ws://localhost:8080

项目结构

模板为您的插件提供了一个基本结构:

my-blinko-plugin/
├── dist/               # 构建输出目录
├── release/            # 发布构建输出
│   └── index.js        # 编译后的插件代码
├── src/                # 源代码目录
│   ├── locales/        # 国际化文件
│   ├── app.tsx         # 主React组件
│   ├── index.tsx       # 插件入口点
│   └── setting.tsx     # 插件设置组件
├── index.ts            # 开发入口点
├── plugin.json         # 插件元数据
└── vite.config.ts      # Vite构建配置

关键文件说明

plugin.json

此文件包含您插件的元数据:

{
  "name": "blinko-plugin-demo",
  "author": "blinko-offical",
  "url": "https://github.com/blinko-space/blinko-plugin-template",
  "version": "0.0.4",
  "minAppVersion": "0.0.0",
  "displayName": {
    "default": "Blinko plugin demo",
    "zh": "Blinko插件示例"
  },
  "description": {
    "default": "This is a blinko plugin demo, you can use it as a template to create your own plugin.",
    "zh": "这是一个blinko插件示例,你可以使用它作为模板来创建自己的插件。"
  },
  "readme": {
    "default": "README.md",
    "zh": "README_zh.md"
  }
}

关键字段说明:

  • name:插件的唯一标识符(必需)
  • author:插件作者的名称或组织(必需)
  • url:仓库或主页URL(必需)
  • version:遵循semver的插件版本(必需)
  • minAppVersion:需要的最低Blinko应用版本
  • displayName:本地化的插件名称
    • default:默认显示名称(英文)
    • zh:中文显示名称(可选)
  • description:本地化的插件描述
    • default:默认描述(英文)
    • zh:中文描述(可选)
  • readme:本地化的文档文件
    • default:默认README文件路径
    • zh:中文README文件路径(可选)

当您运行bun dev时,开发服务器:

  1. 启动一个WebSocket服务器用于通信
  2. 监视dist目录的变化
  3. 当源文件更改时自动重建
  4. 将更新的代码发送到已连接的Blinko客户端

您可以在以下地址访问您的开发服务器:

  • 本地:ws://localhost:8080
  • 网络:ws://<your-local-ip>:8080

使用Ngrok进行外部访问

如果Blinko未部署在您的本地网络中,您需要使用ngrok使您的插件可以从互联网访问:

  1. 首先启动您的开发服务器:
bun dev
  1. 在新终端中,运行ngrok命令:
bun ngrok

这将创建一个到您本地开发服务器的安全隧道,并输出类似内容:

✨ Tunnel established
🌍 Forwarding: wss://xxxx-xx-xx-xxx-xx.ngrok.io -> ws://localhost:8080

现在您可以在Blinko中使用ngrok URL(例如,wss://xxxx-xx-xx-xxx-xx.ngrok.io)连接到您的插件。

开发服务器提供实时反馈:

🎉 Development server running at ws://192.168.1.100:8080
🔌 New Blinko client connected
📦 Build code size: 1234 bytes, Filename: index_abc123.js
🔄 Build completed, file updated: index.js

后续步骤

将您的插件连接到Blinko

一旦您的开发服务器运行后,按照以下步骤将您的插件添加到Blinko:

  1. 打开Blinko并进入设置
  2. 点击”插件设置”
  3. 切换到”本地开发”选项卡
  4. 点击”添加本地插件”按钮
  5. 输入您的WebSocket URL:
    • 本地:ws://localhost:8080
    • 网络:ws://<your-local-ip>:8080
    • Ngrok:wss://xxxx-xx-xx-xxx-xx.ngrok.io(如果使用ngrok)
  6. 点击”连接”开始使用您的插件

如果连接成功,您将看到您的插件列为”本地插件”,旁边有一个绿色状态指示器。

连接问题故障排除

如果您无法连接到您的插件:

  1. 确保您的开发服务器正在运行(bun dev
  2. 检查WebSocket URL是否正确
  3. 如果使用本地网络URL,确保您在同一网络上
  4. 对于ngrok连接,确保使用ngrok提供的wss:// URL

其他资源

  • 发布插件到Blinko插件市场发布插件
  • 查看API参考了解可用的API
  • 加入我们的社区获取帮助并分享您的插件