wx.* API 支持状态

容器向页面注入全局 wx 对象。目前 60 个接口有真实行为， 18 个接口以空实现提供兼容。所有异步接口只支持回调风格，不返回 Promise。

网络

GET / HEAD 会把 data 序列化为查询串，其他方法发送请求体； 未显式设置时自动补 Content-Type: application/json，data 为字符串时原样发送。responseType: "arraybuffer" 时 data 是 ArrayBuffer，可配合 Uint8Array 处理下载的二进制内容。 success 回调的 cookies 字段汇总了整条重定向链上的 Set-Cookie（键为 cookie 名），可用于登录态透传。

回调语义与微信一致：只要服务端返回了 HTTP 响应（包括 401 / 404 / 500），都会走 success， 由脚本按 statusCode 自行判断；fail 只在网络层失败时触发 （DNS、连接被拒、超时、TLS 等），且同样带上 statusCode、 data、header，errMsg 形如 "request:fail timeout"。

url 以 / 开头时按商店服务端地址解析，便于首页这类 “由服务端下发、内容随服务端更新”的小程序直接请求 /api/v1/miniapp-home。

wx.request({
  url: 'https://example.com/api/list',
  method: 'POST',
  data: { page: 1 },
  success(res) {
    this.setData({ items: res.data.items });
  }
});

数据源（SMB）

容器内置 libsmb2，通过 wx.smb.* 访问局域网 SMB 共享 （Windows 共享、群晖、飞牛、极空间等）。连接与列目录为阻塞操作，在 工作线程执行；success / fail 回调在宿主主线程触发。 会话 id 随容器进程存活，不持久化到磁盘。

wx.smb.connect({
  server: '192.168.1.100',
  share: 'movies',
  user: 'admin',
  password: 'xxx',
  success(res) {
    var smbId = res.id;
    // 递归扫描视频文件：path 传目录，name 为完整路径
    wx.smb.listFiles({
      id: smbId,
      path: '/',
      success(files) {
        this.setData({ files: files.filter(function (f) { return !f.isDir; }) });
      }
    });
  },
  fail(err) {
    console.error(err.errMsg);
  }
});

// 播放：拿本地代理地址后交给 video（或 setData 到 src）
var url = wx.smb.streamUrl({ id: smbId, path: '/movies/a.mp4' });

播放走容器本地 HTTP 代理（127.0.0.1），支持 Range 请求（返回 206 Partial Content），由 MPV 直接拉取局域网数据流， 无需把整段视频读入内存。单次代理读取上限 4MB，MPV 会按 Range 分块请求。

媒体库索引（wx.media）

把“遍历目录 + 索引”下沉到宿主：索引按数据源落盘，目录修改时间未变化时 直接复用旧结果，后续进入只读本地索引，毫秒级返回。适用于影片数量多、 每次进入都要重扫的场景（如 SMB 影视库）。

// 先读库（有索引时立即返回），无索引或需要刷新时再触发增量扫描
wx.media.library({
  sourceId: source.id, root: '/',
  success(page) {
    if (page.list.length) render(page.list);
    else wx.media.scan({
      sourceId: source.id, id: smbId, root: '/',
      success(res) { console.log('indexed', res.total); }
    });
  }
});

界面交互

游戏能力

// 手柄驱动的方块 + 联机回显
const socket = wx.connectSocket({ url: 'wss://echo.websocket.events' });
socket.onMessage(res => console.log('recv', res.data));

function loop(ts) {
  const pad = wx.getGamepadState();
  player.x += pad.axes[0] * 4;
  if (pad.buttons.a) jump();
  requestAnimationFrame(loop);
}
requestAnimationFrame(loop);

Switch 硬件（wx.nx）

wx.nx 只在本机型容器上有意义：桌面构建返回 { supported: false }，用于页面布局预览。红外、NFC 都依赖右 Joy-Con， 红外相机需要把右 Joy-Con 从本体上拆下来才能取到画面（插在本体上镜头被遮挡）。

// 体感 + 红外画面
function loop() {
  const m = wx.nx.motion.state();
  tilt = m.angle[0];

  const ir = wx.nx.ir.state();
  if (ir.running && ir.mode === 'image') {
    ctx.drawIrCamera(0, 0, 320, 240);
    ctx.draw();
  }
  requestAnimationFrame(loop);
}
wx.nx.ir.start('image');
requestAnimationFrame(loop);

// 红外手势：根据最大聚类块的密度做张手/握拳判定
wx.nx.ir.start('gesture');
setInterval(() => {
  const hand = wx.nx.ir.state().hand;
  if (hand && hand.pixels > 900) {
    console.log(hand.density > 0.62 ? '握拳' : '张开');
  }
}, 100);

// NFC：发现卡片后挂载读取
wx.nx.nfc.start();
setInterval(() => {
  const nfc = wx.nx.nfc.state();
  if (nfc.state === 'found') wx.nx.nfc.mount();
  if (nfc.state === 'mounted') console.log(nfc.amiibo.name, nfc.amiibo.appAreaSize);
}, 200);

// 自定义 HD 震动波形
wx.nx.rumble.play({ lowFreq: 90, highFreq: 90, lowAmp: 1, highAmp: 0.2, duration: 700 });

画布

绘制 API：fillRect、strokeRect、clearRect、 beginPath、closePath、moveTo、lineTo、 rect、arc、fill、stroke、 fillText、drawImage、drawIrCamera、save、restore、 translate、scale、rotate。 所有指令缓存在 JS 侧，调用 ctx.draw() 后才提交为当前帧， 由 NanoVG 按 node.absWidth / canvasWidth 缩放回放。

const ctx = wx.createCanvasContext('game');
ctx.setFillStyle('#10dc78');
ctx.fillRect(x, y, 32, 32);
ctx.draw();

媒体

const ctx = wx.createVideoContext('demoVideo');
ctx.play();
ctx.seek(30);
ctx.setPlaybackRate(1.5);
ctx.setVolume(60);
ctx.requestFullScreen();
ctx.addSubtitle('https://example.com/movie.zh.srt');

// 音频：所有实例共用一路纯音频播放器（Switch 的音频渲染器是进程级单例，
// 多路 mpv 同时出声会崩）。同一时刻只播一个音源；音效播完后会自动恢复
// 被打断的循环音轨，并回到原来的播放位置。
const bgm = wx.createInnerAudioContext();
bgm.src = '/assets/bgm.wav';
bgm.loop = true;
bgm.volume = 0.4;
bgm.play();

const beep = wx.createInnerAudioContext();
beep.src = '/assets/beep.wav';
beep.play();                    // 打断 BGM；结束（onEnded）后 BGM 自动接着放
beep.destroy();                 // 页面卸载时释放

<video> 支持的扩展属性：initial-time（起播秒数）、 playback-rate（倍速，1 为正常）、volume（0-100）、 subtitle（外挂字幕地址，支持 smb://会话id/路径 或 sdmc:/... 本地路径）、http-headers（鉴权直链的 Cookie）、 autoplay、loop、muted、poster、 object-fit。

事件：bindplay、bindpause、bindended、 bindtimeupdate、binderror、bindloadedmetadata、 bindwaiting、bindprogress、bindseekcomplete、 bindfullscreenchange。全屏时画面铺满内容区，按 B 退出并派发 bindfullscreenchange（{ fullScreen }）。

实际解码由 nxkit::MPVCore 完成。桌面构建默认关闭 NXKIT_WITH_MPV，需要安装 libmpv 并重新配置；未启用时 video 只显示 poster 与占位控制条，并派发 binderror。

小程序互跳

const recent = wx.miniapp.listRecent();
wx.miniapp.launch(recent[0].id);

首页小程序就是靠这两个接口组织“推荐 / 最近使用”的；客户端启动时会先请求 /api/v1/miniapp-home 拿到首页小程序，再按版本安装运行。

数据缓存

缓存按小程序包隔离，保存在 miniapp/storage/<hash>.json。

路由

wx.navigateTo({ url: '/pages/detail/detail?id=42' });

// detail.js
Page({
  onLoad(query) {
    this.setData({ id: query.id });
  }
});

系统信息与启动参数

剪贴板与更新

兼容占位接口

以下接口存在但不会产生效果，用于让微信代码平滑运行：

setNavigationBarColor、showNavigationBarLoading、 hideNavigationBarLoading、setKeepScreenOn、 setPreferredFramesPerSecond、reportAnalytics、 reportEvent、onNetworkStatusChange、 onAppShow、onAppHide、onError、 onUnhandledRejection、pageScrollTo 及对应的 off* 接口。

全局对象