跳到主要内容

模版开发

信号量总览​

Web 原生模版遵循同一协议：

  1. init（包含 craft）
  2. ready
  3. start
  4. end

完整代码示例（含 craft）​

import NianxieInteractionSDK from '@nianxie/nianxie-interaction-sdk';

type CraftPayload = {
  title: string;
  coverUrl?: string;
  rounds: Array<{ question: string; answer: string }>;
  timeLimitSec?: number;
};

const sdk = NianxieInteractionSDK.createNianxieInteractionSDK({
  source: 'webview',
  defaultTimeoutMs: 10000,
});

let craft: CraftPayload | null = null;
let started = false;
let ended = false;

function normalizeCraft(input: Partial<CraftPayload>): CraftPayload {
  return {
    title: input.title ?? 'Untitled Template',
    coverUrl: input.coverUrl,
    rounds: Array.isArray(input.rounds) ? input.rounds : [],
    timeLimitSec: input.timeLimitSec ?? 60,
  };
}

async function loadTemplateAssets(_craft: CraftPayload) {
  // TODO: 加载模版资源
}

function renderTemplate(_craft: CraftPayload) {
  // TODO: 根据 craft 组装页面
}

function startTemplateRuntime(_craft: CraftPayload) {
  // TODO: 启动模版运行时
}

export async function finishTemplate(result: Record<string, unknown>) {
  if (ended) return;
  ended = true;
  await sdk.sendEnd({ extras: result });
}

// [init] 收到 OnMiniInit 后进入：读取 craft 并完成装配
sdk.onInit(async () => {
  const context = sdk.getContext?.() as { craft?: Partial<CraftPayload> } | undefined;
  craft = normalizeCraft(context?.craft ?? {});

  await loadTemplateAssets(craft);
  renderTemplate(craft);

  // [ready] craft 装配完成后上报 NianxieMiniReady
  await sdk.sendReady({
    extras: { stage: 'template-ready', title: craft.title },
  });
});

// [start] 收到 OnMiniStart 后进入：开始正式交互
sdk.onStart(() => {
  if (started || !craft) return;
  started = true;
  startTemplateRuntime(craft);
});

Json Schema 定义示例​

备注

这里仅给定义示例，不展开说明。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["title", "rounds"],
  "properties": {
    "title": { "type": "string", "minLength": 1 },
    "coverUrl": { "type": "string" },
    "timeLimitSec": { "type": "integer", "minimum": 10, "maximum": 600 },
    "rounds": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["question", "answer"],
        "properties": {
          "question": { "type": "string" },
          "answer": { "type": "string" }
        }
      }
    }
  }
}

开发约束与提审建议​

  • 模版同样必须遵守完整信号量协议，不可跳步
  • init 阶段拿到 craft 后先做参数归一化，再进入渲染装配
  • 提交前建议执行 nx:preflight 和 nx:submit:prepare，提前发现运行时阻断问题

可参考官方仓库：

常见错误统一见：常见问题