示例插件

下载完整项目，运行并修改代码。

Plugin API v1

Documentation content is currently available in Simplified Chinese.

第一次开发时，从 Hello 开始。之后可以按下面的顺序增加参数、状态和页面。每个项目都有 manifest.json 和操作说明，代码插件另有可运行入口，下载后可通过“加载开发文件夹”运行。

项目	你会用到的功能	下载
Hello	动作参数和步骤结果	源码 · 安装包
文本处理	文本输入、列表和数字输出	源码 · 安装包
状态按钮	枚举状态和按钮外观切换	源码 · 安装包
计数器	独立实例、页面交互和配置	源码 · 安装包
插件全局设置	自定义配置页、宿主保存与私密字段	源码 · 安装包
网络组件	一次性数据请求和后台联网	源码 · 安装包
服务提供方	发布一个求和服务	源码 · 安装包
极简天气	复用天气服务并提供独立界面	源码 · 安装包
静态图标包	无后台的图标资源贡献	源码 · 安装包
服务消费方	调用求和服务	源码 · 安装包

#运行计数器

加载计数器后，在设备编辑器中放置两份。点击第一份，第二份的计数应该保持不变。再修改其中一份的步长，下一次点击应使用新的步长。这可以帮助你理解实例状态与实例配置的区别。

#运行服务示例

先加载并启动提供方，再加载消费方。在流程中执行消费方的求和动作，输入 [1, 2, 3]，结果应为 6。停止提供方后再次执行，可以看到消费方如何处理服务不可用的情况。

#修改项目

这些项目使用 example.* ID。为你的插件发布新包时，替换为自己的 ID；服务示例还需要同时修改消费方的 dependencies、uses 和代码中的目标插件 ID。

#天气界面：复用其他插件的后台

weather-card 是独立界面示例。先启用 builtin.weather 1.2.0，再关联或安装示例，在超级块目录中添加“极简天气”。它声明 dependencies 与 uses，城市选项和天气均来自公共服务，本身不请求网络权限。

json

{
  "apiVersion": 1,
  "id": "example.weather-card",
  "name": "极简天气（复用服务）",
  "version": "1.0.0",
  "description": "只定义界面，通过天气插件获取数据和城市选项",
  "hostPlatforms": [
    "windows",
    "macos",
    "linux",
    "harmonyos"
  ],
  "main": "index.js",
  "permissions": [],
  "dependencies": {
    "builtin.weather": "^1.2.0"
  },
  "uses": [
    {
      "pluginId": "builtin.weather",
      "serviceId": "forecast",
      "version": 1
    }
  ],
  "contributes": {
    "widgets": [
      {
        "id": "card",
        "title": "极简天气",
        "page": "pages/card/index.html",
        "defaultSize": {
          "cols": 2,
          "rows": 1
        },
        "settingsSchema": {
          "properties": {
            "city": {
              "type": "string",
              "title": "城市",
              "control": "search-select",
              "dynamicOptions": true,
              "default": "cn:beijing",
              "titleKey": "widgets.card.settingsSchema.properties.city.title"
            }
          }
        },
        "titleKey": "widgets.card.title"
      }
    ],
    "dataProviders": [
      {
        "id": "forecast",
        "widget": "card",
        "lifetime": "request",
        "visibility": "instance",
        "responseSchema": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            },
            "source": {
              "type": "string"
            },
            "temperature": {
              "type": "number"
            },
            "description": {
              "type": "string"
            },
            "icon": {
              "type": "string"
            },
            "hourly": {
              "type": "array",
              "items": {
                "type": "object"
              },
              "maxItems": 6
            },
            "daily": {
              "type": "array",
              "items": {
                "type": "object"
              },
              "maxItems": 5
            }
          },
          "required": [
            "city",
            "source",
            "temperature",
            "description",
            "icon",
            "hourly",
            "daily"
          ]
        },
        "maxBytes": 16384
      }
    ]
  },
  "i18n": {
    "defaultLocale": "zh-CN",
    "resources": {
      "zh-CN": "locales/zh-CN.json",
      "en-US": "locales/en-US.json"
    }
  },
  "nameKey": "plugin.name",
  "descriptionKey": "plugin.description"
}

"use strict";
const { definePlugin } = require(process.env.FLYONDECK_SDK_PATH);
const call = (context, method, args) => context.plugins.call("builtin.weather", "forecast", method, args);
definePlugin({
  widgetOptions: { card: { city: (request, context) => call(context, "searchCities", request) } },
  dataProviders: { forecast: ({ settings }, context) => call(context, "getForecast", { city: settings.city }) }
});

#静态图标包

icon-pack 只提供 Studio 单色图标，不包含后台入口。安装并启用后，在按钮外观或图标设置中搜索“播放”或“暂停”。停止后台不影响静态资源；禁用图标包会将其从可选目录移除。

json

{
  "apiVersion": 1,
  "id": "example.icon-pack",
  "name": "示例图标包",
  "nameKey": "plugin.name",
  "version": "1.0.0",
  "hostPlatforms": [
    "windows",
    "macos",
    "linux",
    "harmonyos"
  ],
  "permissions": [],
  "hostCapabilities": {
    "required": {
      "icons.library": 1
    }
  },
  "i18n": {
    "defaultLocale": "zh-CN",
    "resources": {
      "zh-CN": "locales/zh-CN.json",
      "en-US": "locales/en-US.json"
    }
  },
  "contributes": {
    "iconPacks": [
      {
        "id": "studio",
        "title": "Studio 单色图标",
        "titleKey": "packs.studio.title",
        "paint": "monochrome",
        "index": "icons/index.json",
        "license": "CC0-1.0"
      }
    ]
  }
}

json

{
  "schemaVersion": 1,
  "icons": [
    {
      "id": "play",
      "title": "播放",
      "titleKey": "icons.play.title",
      "keywords": [
        "play",
        "播放",
        "开始"
      ],
      "file": "icons/play.svg"
    },
    {
      "id": "pause",
      "title": "暂停",
      "titleKey": "icons.pause.title",
      "keywords": [
        "pause",
        "暂停"
      ],
      "file": "icons/pause.svg"
    }
  ]
}