npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

litmoss-form

v6.0.0

Published

![GitHub](https://img.shields.io/github/license/liuxian496/litmoss-form) ![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/liuxian496/litmoss-form/test.yml) [![Coverage Status](https://coveralls.io/repos/github

Readme

litmoss-form

GitHub GitHub Workflow Status (with event) Coverage Status GitHub Repo stars

litmoss-form 是一个基于 React 的轻量表单库,提供跨组件的表单数据管理能力。核心理念是将表单数据的状态管理与表单UI控制解耦。

  • 跨组件收集表单数据:表单项通过 path 自动注册到 Form 上下文,无需逐层传递 props
  • 一次受控:只要表单组件封装时实现一次受控逻辑,页面开发即可免去重复的受控代码编写,使开发者专注于业务逻辑的编排。
  • 命令式 API:通过 useForm暴露getValues、setValues、validate 等方法
  • 可扩展的校验体系:通过 initLittenForm 全局注入通用校验断言和默认提示文案,同时支持自定义校验
  • 两种校验模式:全部校验(all)与分步校验(step)
  • 校验失败时,自动聚焦到第一个出错的表单项
  • UI无关:不依赖与任何UI库,任何UI库都能通过封装表单组件继承

在线文档

github pages:https://liuxian496.github.io/litmoss-form/

chromatic:https://6ac70cb7870df8e554fb05ff-jcxiqbiehx.chromatic.com/

安装

npm i litmoss-form

以下依赖为 peerDependencies,打包时不包含,需要在使用的项目中自行安装:

| 依赖 | 版本 | |----------------------|------------| | react | ^18.2.0 | | react-dom | ^18.2.0 | | classnames | ^2.5.1 | | cyndi | ^1.0.0 | | exception-boundary | ^2.0.1 | | litmoss-hooks | ^3.0.0 | | lodash | ^4.17.21 |

快速开始

1. 在工程入口全局初始化

在应用启动时调用一次 initLittenForm,注入通用校验断言与默认提示文案:

import { BaseValidationType, initLittenForm } from 'litmoss-form';

export const ValidationType = {
  ...BaseValidationType,
  StringRequired: 'stringRequired',
} as const;

export type ValidationType =
  (typeof ValidationType)[keyof typeof ValidationType];

initLittenForm<ValidationType, string, unknown>({
  commonValidationAssert: (value, type) => {
    switch (type) {
      case ValidationType.StringRequired:
        return typeof value === 'string' && value.trim() !== '';
      default:
        return true;
    }
  },
  getDefaultHelperInfo: (type) => {
    switch (type) {
      case ValidationType.StringRequired:
        return '该项为必填项';
      default:
        return '';
    }
  },
});

2. 使用表单

import { Form, useForm } from 'litmoss-form';

function Demo() {
  const [formRef, form] = useForm();

  function handleSubmit() {
    const errors = form?.validate({ focusOnError: true }) ?? [];
    if (errors.length > 0) return;

    console.log(form?.getValues());
  }

  return (
    <>
      <Form ref={formRef}>
        {/* 使用 useFormItemValue 封装的表单项组件 */}
        <MyTextField
          path="name"
          validations={[{ type: ValidationType.StringRequired }]}
        />
      </Form>
      <button onClick={handleSubmit}>提交</button>
    </>
  );
}

API 概览

组件

| 组件 | 说明 | |-----------|--------------------------------------------------------------------| | Form | 表单容器,通过 ref 暴露 FormRef。validationMode 默认为 all | | Mounter | 挂载完成后触发一次 onDidMount 回调,可用于级联表单等场景的初始化 |

Hooks

| Hook | 说明 | |--------------------|-----------------------------------------------------------------| | useForm | 返回 [ref, form],ref 传给 Form,form 为 FormRef 实例 | | useFormItemValue | 管理表单项的值,并向 Form 上下文注册 / 卸载该表单项 | | useHelperInfo | 根据 validations 执行校验,管理校验提示文本 |

FormRef

| 方法 | 说明 | |------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------| | getValues() | 获取表单当前全部数据 | | setValues(args) | 批量设置表单数据,args 形如 [{ path, value }] | | getValueByPath(path) | 获取指定表单项的值;setValueByPath 之后立即调用可读到最新值 | | setValueByPath(path, value) | 设置指定表单项的值 | | setHelpTextByPath(path, text) | 设置指定表单项的提示信息 | | validate({ focusOnError? }) | 校验表单,返回失败项的 { path, helpInfo } 数组;失败时默认聚焦首个错误项(focusOnError 默认 true) | | validateField(path, { focusOnError? }) | 校验指定表单项,失败时返回 { path, helpInfo } 数组,通过或路径不存在时返回空数组;失败时默认聚焦该项(focusOnError 默认 true) | | focusFieldByPath(path) | 聚焦指定表单项 |

常量

| 常量 | 说明 | |--------------------------------|--------------------------------------------------| | ValidationMode.all | 全部校验,收集所有失败项 | | ValidationMode.step | 分步校验,按注册顺序校验,遇到第一个失败项即停止 | | BaseValidationType.Customize | 自定义校验类型,需配合 validationAssert 使用 |

初始化

| 方法 | 说明 | |----------------------------|--------------------------------------------------------------------------------------| | initLittenForm(injector) | 全局注入 commonValidationAssert、getDefaultHelperInfo、getInitialValue(可选) |

自定义表单组件

组合使用 useHelperInfo 与 useFormItemValue 即可封装一个受控、支持校验提示的表单组件:

import { useRef } from 'react';
import { useFormItemValue, useHelperInfo } from 'litmoss-form';
import type { FormItemProps } from 'litmoss-form';

export const MyTextField = ({
  path,
  initialValue,
  validations = [],
}: FormItemProps<string, ValidationType>) => {
  const inputRef = useRef<HTMLInputElement>(null);

  const [helperText, verifyFormItem, setHelperText] = useHelperInfo<
    string,
    ValidationType
  >(validations);

  const [value, setValue] = useFormItemValue<string>(
    path,
    initialValue,
    verifyFormItem,
    setHelperText,
    inputRef
  );

  return (
    <div>
      <input
        ref={inputRef}
        value={value ?? ''}
        onChange={(e) => setValue(e.target.value)}
        onBlur={() => verifyFormItem(value ?? '')}
      />
      <div>{helperText}</div>
    </div>
  );
};

更多细节见 自定义表单组件封装指南。

文档

本地开发

npm i                                   # 安装依赖
npm run storybook                       # 启动 Storybook(端口 6006)
npm test                                # 运行测试
npm run test-storybook -- --coverage    # 运行 Storybook 测试并生成覆盖率
npm run lint                            # 代码检查
npm run build                           # 构建

License

Apache-2.0

如果你想请我喝一咖啡(Buy Me a Coffee)