React 界面

用单文件 TSX 编写可交互窗口：用户点确定后，界面把数据通过 返回结果 交给后续步骤；取消或关窗则视为用户取消。适合需要自定义布局、动态校验或比固定表单更灵活的输入场景。

:::info 与其它界面步骤怎么选

• 固定字段、拖拽设计表单：用 多字段表单。
• 需要 WPF / XAML、复杂桌面绑定：用 自定义窗口。
• 要加载外部网页或与网页双向通信：用 WebView2浏览器窗口。
• 键鼠自动化脚本、不需要弹窗界面：用 自动化脚本。
• 本模块：用 React + Quicker 内置组件快速做卡片式弹窗，逻辑写在 TSX 源码 里。

:::

当前模块定义​

快速开始​

在组合动作里添加 React 界面。步骤自带一份可运行的默认 TSX 源码，直接运行即可看到名称输入窗。

典型用法分三步：

1. 在上游步骤准备好 输入数据（词典或 JSON），例如 { "name": "任务 A", "title": "填写名称" }。
2. 界面里用 Quicker.getInput() 读取这份数据（只读）。
3. 用户点确定时调用 Quicker.close({ ... })，把对象写入本步骤 返回结果；后续步骤读取变量 reactResult（默认名）即可。

import Quicker from "Quicker";
import { Button, Field, Panel, Stack, TextField } from "QuickerUi";

export default function App() {
  const input = Quicker.getInput<{ title?: string; name?: string }>() ?? {};

  return (
    <main className="qk-ui-page">
      <Panel
        title={input.title ?? "React 界面"}
        footer={
          <>
            <Button onClick={() => Quicker.cancel()}>取消</Button>
            <Button variant="primary" onClick={() => Quicker.close({ name: "示例" })}>
              确定
            </Button>
          </>
        }
      >
        <Stack>
          <Field label="名称">
            <TextField defaultValue={input.name ?? ""} wide />
          </Field>
        </Stack>
      </Panel>
    </main>
  );
}

数据怎么进出动作​

本模块不提供在 TSX 里直接读写动作变量的 API（没有 vars.get / vars.set）。请按下面三种通道理解：

上游步骤 / 输入数据  →  Quicker.getInput()     （只读）
Host 草稿 storage   →  useQuickerStorage(...)  （按动作保存，可选）
Quicker.close(result) →  返回结果 / reactResult  （交给后续步骤）
Quicker.cancel()      →  已取消 = 真

输入数据 可以是词典、列表、数字、文本等；若填 JSON 文本，运行时会尝试解析成对象。界面里改动的内容，只有在你调用 Quicker.close 时才会回到动作。

TSX 源码编写规则​

TSX 源码 必须是单文件，并 export default 一个 React 组件。

允许导入的模块​

运行时只解析以下 import（区分大小写）：

示例：

import { useState } from "react";
import Quicker from "Quicker";
import { Button, Panel } from "QuickerUi";

以下写法不支持，保存或运行时会报错：

• import() 动态导入
• require(...)
• 从 npm 包、本地路径或其它名称导入（例如 "lodash"、"./helper"）

体积与其它限制​

• TSX 源码 不超过 128 KiB。
• 界面在沙箱中运行：不能任意访问网络、文件系统或执行系统命令。
• 编译失败时，窗口会显示错误信息，动作按失败或取消处理（取决于 取消后停止）。

Quicker API​

Quicker 由 Quicker 在运行时注入，不是 npm 包。

组件仍可通过 props 接收 input / close / cancel / notify（与上面 API 等价）；推荐直接使用 Quicker.*。

QuickerUi 组件​

从 QuickerUi 按需导入，用于快速搭界面（样式随 Quicker 主题变化）：

外层建议使用 <main className="qk-ui-page">，以便与窗口边距、主题一致。

草稿 storage 示例​

若希望用户上次填写的名称在同一动作下次运行时仍保留，可用 useQuickerStorage：

import Quicker from "Quicker";
import { TextField, useQuickerStorage } from "QuickerUi";

export default function App() {
  const input = Quicker.getInput<{ name?: string }>() ?? {};
  const [name, setName] = useQuickerStorage("name", input.name ?? "");

  return (
    <TextField value={name} onChange={(e) => setName(e.target.value)} wide />
  );
}

说明：

• 草稿按已保存的动作分别存储；未保存的临时动作仅在本机当次有效。
• 键名仅允许字母、数字、.、_、-，最长 128 字符；每个动作最多 64 个键，单值不超过 64 KiB，总容量约 256 KiB。
• 这是 Host 管理的草稿，不是浏览器网页里的 localStorage；也不会自动同步到其它电脑。

窗口行为​

• 窗口为卡片式布局，无传统系统标题栏；窗口标题 显示在卡片顶部。
• 窗口宽度 / 窗口高度 表示允许的最大尺寸（像素）；内容较小时窗口会随卡片收缩。
• 按 Esc 或点关闭，相当于 Quicker.cancel()。
• 取消后停止 为真时，取消或关闭会中止后续步骤（与多数界面步骤一致）。

输出与后续步骤​

后续步骤可判断 已取消，或读取 返回结果 里的字段，例如 {var:reactResult.name}（变量名以你在步骤里设置的为准）。

限制与排障​

相关链接​

• 多字段表单 — 固定字段、可视化表单设计
• 自定义窗口 — WPF / XAML 自定义界面
• 自动化脚本 — JavaScript 桌面自动化（数据流同样用 getInput / export default）
• 动作变量 — 在步骤之间传递数据