跳到主要内容
文心 · 万形

数据录入

这一类永远按惯例处理，无论所在轨道—— 第三层仲裁规则。表单就是表单。

文本输入

查看代码 · Source
<label class="wx-field">
  <span class="wx-field__label">标题 <span class="wx-field__required">必填</span></span>
  <input class="wx-input" name="title" placeholder="给它起个名字" required>
  <span class="wx-field__hint">显示在列表和分享卡片上。</span>
</label>
<label class="wx-field">
  <span class="wx-field__label">摘要</span>
  <textarea class="wx-input" name="summary" rows="3"></textarea>
</label>
<label class="wx-field">
  <span class="wx-field__label">邮箱</span>
  <input class="wx-input" type="email" value="zopiya@" aria-invalid="true" aria-describedby="err-1">
  <span class="wx-field__error" id="err-1">邮箱格式不正确——缺少域名部分。</span>
</label>

何时使用、何时不用与 API

组件何时使用 · 不用契约（ARIA / 脚本）
wx-form / wx-field有提交目标的字段组；单一搜索框不必包完整 form 布局。form、fieldset/legend；每个控件有嵌套或 for label，错误用 aria-invalid + aria-describedby。
wx-input / wx-select / wx-number文字、有限选项和数值；复杂选择优先原生能力，不造 div 下拉。原生 input/select；select 外层 wx-select-wrap 只画箭头。
wx-check / wx-radio / wx-switch独立多选、互斥选择、即时开关；提交型布尔值仍可用 checkbox。原生 checkbox/radio；switch 是 button role="switch" aria-checked，状态不得用 class。
wx-slider-field / wx-slider / wx-rate连续范围、可读数评分；精确输入同时给 number，不让位置成为唯一信息。原生 range 有可访问名和文字值；rate 的每个 radio 有含文字的 native label，点击框由 --touch-target-min 决定。
wx-upload / wx-upload-list需要文件选择；普通附件链接不是上传区。原生 input type=file 保留可点击 label；文件状态文字化。
wx-search站内/列表检索；短页面不放装饰性搜索。input type=search 有 label（可 sr-only）；查询与结果状态由采用者脚本管理。
wx-autocomplete / wx-date-picker / wx-time-picker有限建议、日期、时间；跨时区、复杂排期仍需专门产品方案。分别基于 datalist、input type=date、input type=time；保留 label 和原生校验。

错误态同时改变颜色、加粗边框、并给出文字说明。三重编码是第一层底线。

选择

只用原生 <select>。自定义下拉是键盘与读屏器的负债， 这套系统没有理由去背。箭头用旋转边框画，不用渐变。

查看代码 · Source
<label class="wx-field">
  <span class="wx-field__label">分类</span>
  <span class="wx-select-wrap">
    <select class="wx-select" name="cat">
      <option>设计</option><option>工程</option><option>随笔</option>
    </select>
  </span>
</label>

原生增强输入

浏览器已经提供可靠的建议、日期和时间控件时，优先把它们接进统一的字段外观，而不是重造一套键盘交互。

查看代码 · Source
<label class="wx-field"><span class="wx-field__label">负责人</span><input class="wx-input wx-autocomplete" list="owners" placeholder="输入或选择"><datalist id="owners"><option value="林舟"></option><option value="陈岚"></option><option value="周砚"></option></datalist></label>
<div class="wx-cols" style="margin-block-start:var(--space-6)">
  <label class="wx-field"><span class="wx-field__label">发布日期</span><input class="wx-input wx-date-picker" type="date" value="2026-08-30"></label>
  <label class="wx-field"><span class="wx-field__label">发布时间</span><input class="wx-input wx-time-picker" type="time" value="09:30"></label>
</div>

勾选与单选

查看代码 · Source
<label class="wx-check"><input type="checkbox" checked> 公开发布</label>
<label class="wx-check"><input type="checkbox"> 允许评论</label>
<hr class="wx-rule">
<label class="wx-radio"><input type="radio" name="lic" checked> 保留所有权利</label>
<label class="wx-radio"><input type="radio" name="lic"> 署名 4.0</label>

开关

状态由位置 + 边框表达，不只靠颜色。role="switch" + aria-checked，绝不用 .is-on。

离线可读
查看代码 · Source
<div class="wx-cluster">
  <button class="wx-switch" type="button" role="switch" aria-checked="false" aria-label="离线可读" data-wx-entry-switch></button>
  <span>离线可读</span>
</div>

数字与滑块

滑块的值必须能读成数字——滑块位置本身不是可访问的读数。

行长上限36 em
2848
查看代码 · Source
<label class="wx-field">
  <span class="wx-field__label">每页条目</span>
  <input class="wx-number" type="number" value="20" min="10" max="100" step="10">
</label>
<div class="wx-slider-field" style="margin-block-start:var(--space-6)">
  <div class="wx-slider-field__row"><span>行长上限</span><output class="wx-slider-field__value" id="entry-demo-line-length-output" for="entry-demo-line-length">36 em</output></div>
  <input class="wx-slider" id="entry-demo-line-length" type="range" min="28" max="48" value="36" aria-label="行长上限" data-wx-entry-slider data-wx-output="entry-demo-line-length-output" data-wx-unit="em">
  <div class="wx-slider-field__scale"><span>28</span><span>48</span></div>
</div>

评分

用 ■ 方块而不是星形图标——填充与描边的差别在灰度下依然可读。 "禁止填充型图标"针对的是图标集风格，评分标记是数据标记，和图表里的柱子同类。

视觉方块保持 16px；每一项的可点击区域由 --touch-target-min 控制，紧凑界面至少 24px， F2 表单轨会升至 48px。名称仍写在原生 label 里，不能只把分数藏在 title 属性。

评分
查看代码 · Source
<fieldset style="border:0;padding:0;margin:0">
  <legend class="wx-field__label">评分</legend>
  <span class="wx-rate">
    <input type="radio" name="r" id="r5"><label for="r5"><span class="wx-sr-only">5 分</span></label>
    <input type="radio" name="r" id="r4" checked><label for="r4"><span class="wx-sr-only">4 分</span></label>
    <input type="radio" name="r" id="r3"><label for="r3"><span class="wx-sr-only">3 分</span></label>
    <input type="radio" name="r" id="r2"><label for="r2"><span class="wx-sr-only">2 分</span></label>
    <input type="radio" name="r" id="r1"><label for="r1"><span class="wx-sr-only">1 分</span></label>
  </span>
</fieldset>

上传

这套系统提供的是原生文件选择的语义与外观骨架。产品确实需要拖放时， 四边虚线框是卡片禁令的一个有理由的例外：边界不是装饰，它就是信息， 标示可放置区域到哪里为止。让步仍有限度：虚线发丝、无填充、无阴影；拖放与校验逻辑不由 kit 假装提供。

  • design-spec.pdf 2.4 MB · 静态示例

这里仅展示文件列表结构，不模拟选择或移除行为。

查看代码 · Source
<label class="wx-upload">
  <input type="file" multiple>
  <span class="wx-upload__prompt">点击选择文件</span>
  <span class="wx-upload__hint">拖放、格式/大小校验、文件列表与服务端复核由采用者按产品规则实现。</span>
</label>
<ul class="wx-upload-list" aria-label="静态文件列表结构示例">
  <li class="wx-upload-list__item">
    <span class="wx-upload-list__name">design-spec.pdf</span>
    <span class="wx-upload-list__size">2.4 MB · 静态示例</span>
  </li>
</ul>
<p class="wx-field__hint">这里仅展示文件列表结构，不模拟选择或移除行为。</p>
查看代码 · Source
<label class="wx-search">
  <span class="wx-sr-only">搜索</span>
  <input class="wx-search__input" type="search" placeholder="搜索组件…">
</label>

表单

wx-form 是字段的容器与提交上下文。它不接管提交——提交由采用者处理， 组件负责的是布局、分组、错误汇总与状态区的位置。

联系方式
查看代码 · Source
<form class="wx-form" novalidate>
  <div class="wx-form__errors" role="alert" tabindex="-1">
    <p><strong>有 1 项需要修改：</strong></p>
    <ul><li><a href="#form-demo-email">邮箱格式不正确</a></li></ul>
  </div>
  <fieldset class="wx-form__section">
    <legend>联系方式</legend>
    <label class="wx-field" for="form-demo-email"><span class="wx-field__label">邮箱 <span class="wx-field__required">必填</span></span>
      <input class="wx-input" id="form-demo-email" type="email" value="zopiya@" aria-invalid="true" aria-describedby="form-demo-email-err">
      <span class="wx-field__error" id="form-demo-email-err">邮箱格式不正确——缺少域名部分。</span>
    </label>
  </fieldset>
  <div class="wx-form__actions">
    <button class="wx-btn wx-btn--text" type="button">取消</button>
    <button class="wx-btn wx-btn--primary" type="submit">提交</button>
  </div>
</form>
构件职责契约
wx-form__errors提交失败后的汇总，每条链到出错字段。role="alert" + tabindex="-1"，提交后把焦点移过来。
wx-form__section相关字段分组。原生 fieldset + legend，不是 div 加标题。
wx-form__actions动作区，主操作在最后，取消在它之前。至多一个 wx-btn--primary。

表单属于第三层仲裁规则：数据录入与反馈类组件永远按惯例处理， 无论所在轨道。一个纯阅读轨的文档站里，它的搜索框和表单同样使用完整语义色、清晰可供性与标准交互反馈。 表单页讲的是校验时机与整页编排。