fcode-json-schema

Factorial Code — 输入参数模式

流程的输入参数由 parametersSchema.json 中的 JSON Schema 定义。 fcode-forms 会将同一模式渲染为 Web 表单，因此设计模式本身就是在设计表单。值会作为 fcode.context.parameters 传入代码（参见 fcode-javascript / fcode-python）。

模式使用 react-jsonschema-form 渲染，因此其 ui: 选项也适用。

如何编写

1. 顶层为 "type": "object"，包含一个 properties 映射（每个字段对应一项）和一个可选的 required 数组。
2. 为每个字段选择 type（string、integer、number、boolean、array、object），并添加验证规则（minimum / maximum、format、enum / oneOf、uniqueItems、嵌套的 properties）。
3. 使用每个字段的 ui 对象控制渲染（例如 "ui": { "ui:widget": "textarea" }）。
4. 打开 assets/parametersSchema.sample.json，查看一个涵盖所有受支持类型、可完整复制粘贴的模式——请以此为基础调整字段，而不要猜测结构。

字段类型和控件（示例中）

• 文本 — "type": "string"；format: "email"；ui:widget 可设为 textarea、color、hidden 或 file。
• 机密信息 — "isSensitive": true 会遮蔽输入内容（例如密码 / 令牌）。
• 数字 — integer / number，并可设置 minimum / maximum。
• 布尔值 — "type": "boolean"。
• 选项 — enum（下拉选择）、由 { const, title } 组成的 oneOf（带标签的单选按钮，使用 ui:widget: "radio"），或搭配 ui:widget: "checkboxes" 和 uniqueItems 的数组。
• 结构化数据 — 带有自身 properties / required 的嵌套 object；字符串数组或对象数组（type: "array" + items）；通过 "ui": { "ui:field": "json" } 输入原始 JSON。
• 条件字段 — 使用顶层 dependencies 根据其他字段的值显示 / 隐藏字段（参见示例中的 anotherBooleanField）。
• 字段周围的内容 — 每个字段都可设置一个 markdown 对象，其中的 before / after 字符串会在字段上方 / 下方渲染为区块 Markdown（支持完整 GFM，包括表格）。详情和完整示例见 fcode-forms 的 references/advanced.md。
• 长表单 — 字段约十个或更多时，可使用根级 ui:steps 节点拆分为多个步骤；参见 fcode-forms 的 §Multi-step forms。
• 连接外部账户 — 设置为 string 或 boolean，并配置 "ui": { "ui:widget": "oauth", "ui:options": { "authorizationUrl": … } }，即可渲染一个按钮，在弹出窗口中完成 OAuth 流程（对于 object，使用 "ui:field": "oauth"；参见示例中的 oneOauthConnectField）。契约和回调见 fcode-forms 的 §Connect an external account。

注意事项

• 文件字段（"ui:widget": "file"）会在流程运行前自动上传到 Storage；传入的参数是 fcode.storage://… 引用，而非文件内容。调用 fcode.storage.download(...) 前，请去掉此前缀。
• isSensitive: true 仅影响显示 / 遮蔽效果——仍应从机密变量中读取值，切勿将其硬编码。
• OAuth 字段的 authorizationUrl 必须通过 preRenderProcess 变量注入 { "$ref": "#/variables/x" }——切勿使用 {{x}}，因为 Mustache 会将其 HTML 转义，导致控件拒绝该 URL（按钮会呈禁用状态，并在控制台显示警告）。
• 模式是表单字段的唯一数据源——要更改字段，请编辑模式，而不是表单嵌入代码。
• 模式是数据，不是代码——其中不能包含可执行 JavaScript，且所有表单文本均为 Markdown（不会渲染原始 HTML）。客户端行为应放在嵌入页面中实现——参见 fcode-forms。
• 可翻译可见文本：模式字符串（标题、描述、ui:placeholder）可使用 fcode.i18n("key") 标记；表单提供服务前会在服务器端替换这些标记——参见 fcode-i18n。