For AI agents: the complete documentation index is available at /next/zh/llms.txt, the full documentation bundle is available at /next/zh/llms-full.txt, and this page is available as Markdown at /next/zh/ui/components/form.md.
lynx-ui logo
lynx-ui
  • 简体中文
  • Form

    一个适用于 ReactLynx 的无样式表单组件,提供表单上下文和收集字段值的提交基础能力。
    Info

    你可以查看源码来了解它的运行原理,也欢迎大家提 PR 来丰富其能力。

    基础用法

    使用 <Form> 来管理表单状态、处理表单验证和提交

    示例

    使输入框抬起以避让键盘

    通过自动调整视图来防止屏幕键盘遮挡输入框

    结构

    <FormRoot>
      <FormField />
      <FormSubmitButton />
    </FormRoot>

    组件 API

    FormRoot

    childreniOSAndroidHarmony
    类型ReactNode
    表单内容
    initialValuesiOSAndroidHarmony
    类型Record<string, unknown>
    表单字段的初始值
    onChangediOSAndroidHarmony
    类型(values: Record<string, unknown>) => void
    任意字段值变化时触发的回调函数,接收整个表单的数据
    onSubmitiOSAndroidHarmony
    类型(values: Record<string, unknown>) => void
    表单提交时触发的回调函数

    FormField

    asiOSAndroidHarmony
    类型Input | RadioGroupRoot | Checkbox | TextArea | Switch
    指定渲染的组件类型
    childreniOSAndroidHarmony
    类型ReactNode
    表单字段的子节点,通常用于标签或复杂结构
    classNameiOSAndroidHarmony
    类型string
    类名
    confirmTypeiOSAndroidHarmony
    类型send | search | go | done | next·默认值'send'
    输入框确认按钮类型
    idiOSAndroidHarmony
    类型string·默认值'input'
    输入框 id
    inputFilteriOSAndroidHarmony
    类型string
    输入框内容过滤正则表达式
    maxLengthiOSAndroidHarmony
    类型number·默认值140
    输入框最大长度
    nameiOSAndroidHarmony
    类型string
    表单字段的唯一标识符
    onBluriOSAndroidHarmony
    类型(value: string) => void
    输入框失焦事件
    onChangediOSAndroidHarmony
    类型(value: unknown) => void
    当前字段值变化时触发的回调函数
    onConfirmiOSAndroidHarmony
    类型(value: string) => void
    输入框确认按钮点击事件
    onFocusiOSAndroidHarmony
    类型(value: string) => void
    输入框聚焦事件
    onSelectionChangeiOSAndroidHarmony
    类型(selectionStart: number, selectionEnd: number) => void
    输入框选择范围改变事件
    placeholderiOSAndroidHarmony
    类型string
    输入框占位符
    readonlyiOSAndroidHarmony
    类型boolean·默认值false
    输入框是否可交互
    ref
    类型ForwardedRef<{blur: () => Promise<void>, focus: () => Promise<void>, getValue: () => Promise<{selectionEnd: number, selectionStart: number, value: string}>, setSelectionRange: (selectionStart: number, selectionEnd: number) => Promise<void>, setValue: (value: string) => Promise<void>}>
    showSoftInputOnFocusiOSAndroidHarmony
    类型boolean·默认值true
    输入框是否聚焦时显示软键盘
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    typeiOSAndroidHarmony
    类型number | text | digit | password | tel | email·默认值"text"
    输入框内容类型
    disablediOSAndroidHarmony
    类型boolean·默认值false
    如果设置为 true,RadioGroup 将不能接受交互。
    checkboxPropsiOSAndroid
    类型ViewProps
    Checkbox 支持将原始视图属性直接展开到这个属性中。
    indeterminateiOSAndroid
    类型boolean·默认值false
    是否为不确定状态。
    bouncesiOS
    类型boolean·默认值true
    输入框是否开启 iOS bounces 效果
    lineSpacingiOSAndroid
    类型number | px | rpx
    输入框行间距
    maxLinesiOSAndroidHarmony
    类型number·默认值40
    输入框最大输入行数
    switchPropsiOSAndroid
    类型ViewProps
    Switch 支持将原始视图属性直接展开到这个属性中。

    FormSubmitButton

    buttonPropsiOSAndroidHarmony
    类型ViewProps
    按钮支持将原始视图属性直接展开到这个属性中。
    classNameiOSAndroidHarmony
    类型string
    类名
    disablediOSAndroidHarmony
    类型boolean·默认值false
    决定按钮是否被禁用。
    onSubmitiOSAndroidHarmony
    类型(values: Record<string, unknown>) => void
    提交按钮点击后,在表单内部提交逻辑执行后触发的回调函数
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    childreniOSAndroidHarmony
    类型| ReactNode | ((state: {active: boolean, disabled: boolean}) => ReactNode)
    子组件

    基于状态的样式与渲染

    该组件通过以下一种或两种方式暴露运行时状态。下表仅展示每个状态实际支持的方式:

    • UI variant class:支持时,对应组件节点会动态加上 ui-<state> 形式的类名,可用 .ui-<state> { ... } 选择器定制样式;
    • Render-prop 字段:支持时,当 children 传入函数,状态会以 children({ <state>: boolean, ... }) 的形式作为参数传入,便于在运行时做条件渲染。

    UI variants applied by FormSubmitButton based on its render state.

    类名渲染属性类型说明
    ui-activeactiveboolean按钮当前是否处于按下态(且未被禁用)。 提交按钮处于按下态且未被禁用时生效。
    ui-disableddisabledboolean按钮是否处于禁用态。 提交按钮被禁用时生效。
    除非另有说明,本项目采用知识共享署名 4.0 国际许可协议进行许可,代码示例采用 Apache License 2.0 许可协议进行许可。