# @formdown/core 中文文档

规范地址：https://npmcn.com/package/%40formdown/core/

版本：0\.26\.1
npm 元数据更新时间：2026-11-09T07:21:51.721Z
中文译文更新时间：2026-11-15T08:37:25.743Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40formdown/core
原文对照：https://npmcn.com/package/%40formdown/core/?lang=original
项目主页：https://formdown.dev/
源码仓库：https://github.com/iyulab/formdown

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：399 kB，77 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2025-06-23T02:09:21.229Z
- 最新版本发布：2026-11-09T07:21:51.346Z
- 近 30 天下载量：4207（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：58（近 12 个月 39 个）

## 中文简介

Formdown 的核心解析和生成引擎

## 安装

```sh
npm install @formdown/core
```

也可以使用：`pnpm add @formdown/core`、`yarn add @formdown/core`、`bun add @formdown/core`

## README

# @ formdown/ core (中文(简体) )

Formdown 解析器,生成器和工具:将Formdown 读出——用形式字段标记为Markdown,并变成一个字段和 schema,使它成为HTML,编辑它的源而不会失去任何东西,并将所持有的数据写回Formdown.

```bash
npm install @formdown/core
```

```typescript
import { parseFormdown, getSchema, generateFormHTML } from '@formdown/core'

const source = '@name*: []\n@email*: @[]\n@notify(Email me about replies): c[switch]'
parseFormdown(source).forms   // the fields, with diagnostics for anything the parser could not read
getSchema(source)             // { name: { type: 'text', required: true, … }, …, notify: { type: 'checkbox', switch: true, … } }
generateFormHTML(source)      // the form as HTML
```

## 入境点

仅导入您使用的东西; 每个子路径只携带它需要的东西 .

| 导入 | 它给的是什么 |
| --- | --- |
| `@formdown/core` | 下面的一切 `FormManager` |
| `@formdown/core/parser` | `FormdownParser` ——领域,诊断和源位. 它发现首要问题,但只有在给读者读取时才读出YAML,所以它没有YAML的执行 |
| `@formdown/core/front-matter` | `yamlFrontMatter` (读者给出解析器), `readFrontMatter` |
| `@formdown/core/format` | `formatFormdown(fields)`, (中文(简体) ), `formatField(field)` —— 以Formdown文本写成的数据所持有的字段; 解析它使相同的字段返回 |
| `@formdown/core/schema` | `getSchema(content)` ——取自已解析的文本或内容 |
| `@formdown/core/generator` | `FormdownGenerator` —— HTML 从解析的内容 |
| `@formdown/core/form-manager` | `FormManager` ——解析,渲染,数据绑定和验证一起进行 |
| `@formdown/core/extensions` | 钩和插件 |
| `@formdown/core/messages/ko` | 韩语验证句子, 用于 `validateForm(…, { messages })` 或者说 `<formdown-ui>`是因为 `messages` |

验证是每个字段宣布的 `required` (和 `required-if`, (中文(简体) ), `minlength` 编号 : `maxlength`, (中文(简体) ), `min` 编号 : `max`,格式 `number`, (中文(简体) ), `email`, (中文(简体) ), `url`, (中文(简体) ), `tel` 财务报告和审定财务报表 `date`,以及 `pattern` 匹配整个值,如浏览器所做的:

```typescript
import { getSchema, validateForm, typedData } from '@formdown/core'
import { messages as ko } from '@formdown/core/messages/ko'

const schema = getSchema('@title(Title)*: [minlength=3]
@n: [number max=10]')
validateForm({ title: 'ab', n: '12' }, schema).errors
// [{ field: 'title', message: 'Must be at least 3 characters' }, { field: 'n', message: 'Value must be at most 10' }]
validateForm({}, schema, { messages: ko }).errors   // [{ field: 'title', message: 'Title 칸을 채워 주세요' }]
typedData({ n: '12' }, schema)                      // { n: 12 } — number fields' values as numbers
```

`messages` 替换任何规则的句子(`required`, (中文(简体) ), `minLength`, (中文(简体) ), `maxLength`, (中文(简体) ), `min`, (中文(简体) ), `max`, (中文(简体) ), `number`, (中文(简体) ), `email`, (中文(简体) ), `url`, (中文(简体) ), `tel`, (中文(简体) ), `date`, (中文(简体) ), `dateMin`, (中文(简体) ), `dateMax`, (中文(简体) ), `pattern`),与 `{label}`, (中文(简体) ), `{min}` 财务报告和审定财务报表 `{max}` 填入; 一个字段本身 `error-message` 胜过所有这些——这是字段所说的一句话,对于第一个规则,它的价值破裂.

```typescript
import { FormdownParser } from '@formdown/core/parser'
import { yamlFrontMatter } from '@formdown/core/front-matter'

new FormdownParser().parseFormdown(source)                                    // no front matter values
new FormdownParser({ frontMatter: yamlFrontMatter }).parseFormdown(source)    // as parseFormdown() reads them
```

## 文档

-   [语法](https://github.com/iyulab/formdown/blob/main/docs/SYNTAX.md) - 每一个领域、属性和诊断
-   [核心结构](https://github.com/iyulab/formdown/blob/main/docs/CORE_ARCHITECTURE.md) —— API,源位和编辑,将字段写为文本
-   [更改日志](https://github.com/iyulab/formdown/blob/main/CHANGELOG.md)

## 许可证

麻省理工学院

## 常见问题

### @formdown/core 是什么？

Formdown 的核心解析和生成引擎

### 如何安装 @formdown/core？

在项目目录运行 npm install @formdown/core，或使用 pnpm add / yarn add / bun add。

### @formdown/core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @formdown/core 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @formdown/core 可以商用吗？

@formdown/core 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @formdown/core 的下载量有多少？

根据 npm 官方下载统计，@formdown/core 在 2026/10/16 – 2026/11/14 这 30 天内被下载 4,207 次，日均约 140 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @formdown/core 还在维护吗？

最新版本 0\.26\.1 发布于 2026/11/09（6 天前）；至今共发布 58 个版本，其中过去 12 个月发布了 39 个；首次发布于 2025/06/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。