API 概览 | 如快开发者文档

本页汇总了插件侧常用能力与快速上手方式，建议先通读，再按需跳转到对应模块查看细节与示例。

快速导航

上下文（Context）：/api/context
截图（Screenshot）：/api/screenshot
本地存储（LocalStorage）：/api/storage

快速上手

UI 环境（@sofastapp/api）No-View 环境（@sofastapp/api/node）

import {
  Context,
  Screenshot,
  LocalStorage,
  getSessionId,
  getCurrentCommand,
} from '@sofastapp/api';

// 读取/设置/清空/监听搜索框内容
const text = await Context.getSearchContent();
await Context.setSearchContent('Hello Sofast');
await Context.clearSearchContent();
const unwatch = Context.watchSearchContent((v) => console.log('search =', v));

// 触发截图
await Screenshot.start();

// 插件存储
await LocalStorage.setItem('k', 'v');
const all = await LocalStorage.allItems<Record<string, any>>();

// 读取会话参数
const sid = getSessionId();
const cmd = getCurrentCommand();

import {
  ctx,
  log,
  progress,
  done,
  fail,
  onError,
  LocalStorage,
} from '@sofastapp/api/node';

onError();
(async () => {
  const { args } = ctx();
  log('start', { args });
  progress(0.2);
  const n = (await LocalStorage.getItem<number>('counter')) ?? 0;
  await LocalStorage.setItem('counter', n + 1);
  progress(1);
  done({ ok: true, counter: n + 1 });
})().catch(fail);

能力一览

UI 环境（`@sofastapp/api`）

Context.getSearchContent(): Promise<string> – 读取搜索框内容
Context.setSearchContent(val: string): Promise<void> – 设置搜索框内容
Context.clearSearchContent(): Promise<void> – 清空搜索框内容
Context.watchSearchContent((val: string) => void): () => void – 监听搜索框内容
Context.setFooter(spec: FooterButtonSpec | FooterButtonSpec[]): Promise<void> – 注册底部 Footer（按钮/Action Panel）
Screenshot.start(): Promise<void> – 触发截图
LocalStorage.getItem<T>(key: string): Promise<T | undefined> – 读取键值（使用泛型指定类型）
LocalStorage.setItem(key: string, value: unknown): Promise<void> – 设置键值（内部以 JSON 持久化，非 JSON 可序列化的值会报错）
LocalStorage.removeItem(key: string): Promise<void> – 删除键
LocalStorage.allItems<T extends object>(): Promise<T> – 读取全部键值对
LocalStorage.clear(): Promise<void> – 清空全部键值

No-View 环境（`@sofastapp/api/node`）

ctx(): { command?: string; args?: any; pluginPath?: string } – 获取执行上下文
log(message: string, data?: any, level?: 'info'|'debug'|'warn'|'error') – 输出日志
progress(p: number, data?: any) – 上报进度（0~1）
done(result?: any) – 结束并返回结果（可选）
fail(error: unknown) – 上报错误并结束
onError() – 捕获未处理异常/拒绝
LocalStorage.* – 与 UI 环境一致，数据保存在插件根目录 data/storage.json

约定与提示

命名约定

搜索内容相关 API 统一为 getSearchContent / setSearchContent / clearSearchContent / watchSearchContent
UI 默认入口为 index.html，无需在清单中配置入口字段
清单仅使用顶层 commands 字段（不再兼容旧结构）

会话参数

UI 加载时会在 URL 上附带：?sid=<sessionId>&cmd=<command>。如需在 UI 内切换逻辑，可读取 cmd 并在内部路由或条件渲染中使用。

版本要求

如快 v0.9.0+ 才支持新 Worker API 与顶层 commands 清单结构。

快速导航 ​

快速上手 ​

能力一览 ​

UI 环境（@sofastapp/api） ​