跳转到内容

API 参考 ​

各模块共同遵循 API 约定。

业务方优先从根入口使用稳定 API:

ts
import {
  BridgeError,
  ClipboardError,
  StorageError,
  DbError,
  createBridgeLogTransport,
  unwrapBusinessEnvelope,
  createBridge,
  createClipboard,
  createDb,
  createEnvironment,
  createHttp,
  createLogger,
  createStorage,
  HttpError,
  type ApiContractBuilder,
  type ApiType,
  type Bridge,
  type ClipboardClient,
  type Db,
  type Environment,
  type HttpApiDefinitionTree,
  type HttpApiFromDefinition,
  type HttpCallInput,
  type HttpCallOptions,
  type HttpEndpointDefinition,
  type HttpOptions,
  type HttpClient,
  type Logger,
  type StorageArea
} from '@freenotes/web-runtime';

常用工厂 ​

API说明
createStorage(type?, options?)创建 localStorage 或 sessionStorage 实例。
createDb()创建 IndexedDB manager。
createEnvironment(options?)创建不可变环境与 capability 快照。
createClipboard()创建文本剪贴板实例。
createBridge(options?)创建 H5 和宿主环境通信的 Bridge 实例。
createLogger(options)创建使用显式 transport 的平台无关 Logger。
createHttp(options?)创建配置式业务 HTTP API 实例。

Capability 实例类型 ​

API返回类型
createBridge(options?)Bridge
createClipboard()ClipboardClient
createDb()Db
createEnvironment(options?)Environment
createHttp()HttpClient
createLogger(options)Logger
createStorage(type?, options?)StorageArea

实例类型按领域角色命名,不统一添加信息量较低的 Runtime 后缀。ClipboardClient 避免与 DOM 的 Clipboard 类型冲突,HttpClient 表达配置后的请求客户端,StorageArea 表达具体的 local/session storage 区域。

HTTP 类型 ​

类型说明
HttpClientcreateHttp() 的返回类型。
HttpOptionsbaseURL、headers、timeout、retry 和 interceptors 配置。
HttpApiDefinitionTreecreateApi() 接收的递归 endpoint 配置树。
HttpApiFromDefinition根据配置树推导出的业务方法树。
ApiContractBuildercreateApi((contract) => ...) 回调中的契约辅助对象。
ApiType<T>contract.type<T>() 返回的编译期标记类型。
ApiContract<T>编译期 marker 或 Standard Schema 契约。
StandardSchemaV1HTTP 接受的框架无关运行时 schema 接口。
StandardSchemaIssueschema 校验失败时保留在 HttpError.issues 的问题项。
HttpEndpointDefinition单个 endpoint 的 method、url、契约标记和 transport 配置。
HttpCallInput未声明契约标记时的通用 path、query、data、options 输入。
HttpCallOptions单次请求的 timeout、headers、signal 等覆盖配置。
HttpErrorHTTP、业务 envelope 或请求构造失败时抛出的错误。

配置本身就是 HTTP 契约。业务不需要维护 Get/Post/... 类型树,也不需要为 method 添加 as const。详细示例见 HTTP 指南。

生成文档 ​

完整的根入口类型由 TypeDoc 生成:

当前 package 同时暴露根入口和 bridge、clipboard、db、environment、http、logger、storage 显式 subpath。

维护者重新生成 API 文档:

bash
pnpm docs:api

让基础能力保持简单,让业务开发更加专注。