文档首页 / HareAdmin 开发手册

系统组件

表单组件需先 Form.api.bindevent($('form[role=form]')) 才会渲染与绑定事件。也可对单个能力调用 Form.events.*。

组件初始化
上传Form.events.plupload($("form"))
SelectPageForm.events.selectpage($("form"))
校验Form.events.validator($("form"))
城市Form.events.citypicker($("form"))
日期时间Form.events.datetimepicker($("form"))
下拉Form.events.selectpicker($("form"))
附件选择Form.events.faselect($("form"))
键值列表Form.events.fieldlist($("form"))
开关Form.events.switcher($("form"))

文件上传

文本框接收 URL + .plupload 上传按钮 + 可选 .fachoose 与预览容器。关键属性:

  • data-input-id:填充目标 input
  • data-mimetype:允许类型
  • data-multiple:多文件
  • data-preview-id:预览 UL
  • data-maxsize:大小限制
<input id="c-avatar" class="form-control" name="row[avatar]" type="text">
<button type="button" class="btn btn-danger plupload" data-input-id="c-avatar"
  data-mimetype="image/gif,image/jpeg,image/png" data-multiple="false"
  data-preview-id="p-avatar">上传</button>
<ul class="row list-inline plupload-preview" id="p-avatar"></ul>

云存储通过安装对应 storage 驱动插件启用,业务侧不要写死某一云厂商 SDK。

SelectPage

<input class="form-control selectpage" data-source="category/selectpage"
  data-field="name" data-primary-key="id" name="row[category_id]">

常用:data-source、data-field、data-primary-key、data-multiple、data-params(可设 function 做联动)。

富文本编辑器

给 textarea 加 class editor 即可。具体实现由编辑器驱动插件注册(如 wangeditor);未安装驱动时保持普通文本域。业务代码不要按名称硬加载某个编辑器包。

<textarea class="form-control editor" name="row[content]"></textarea>

自定义表单同样需要 Form.api.bindevent。同时只启用一个编辑器驱动(或按页面改选择器)。

表单验证

使用 Nice-validator:在元素上写 data-rule="required;mobile" 等。常用规则:required、checked、match、remote、integer、length、email、mobile、username、password。给 form 加 novalidate 可关闭。

其它

  • 城市:data-toggle="city-picker",可用 data-level / data-simple
  • 日期时间:datetimepicker / daterangepicker 相关 class 或 data 属性(以 CRUD 生成为准)
  • 开关 / 键值:由 Form.events 绑定;CRUD 会按字段后缀自动生成

更细的属性表以实际组件源码与生成模板为准;本章只保留当前栈下的用法入口。

树形下拉(Pid / 上级)

表单需要上级/分类下拉时,统一用 tree_select_options()(app/common.php),样式与系统分类、菜单规则一致。

$rows = Db::name('my_category')->order('weigh desc,id asc')->select()->toArray();
$parentList = tree_select_options($rows, 'name', 'pid', lang('None'), $excludeIds);
$this->view->assign('parentList', $parentList);
<select class="form-control selectpicker" name="row[pid]" data-live-search="true">
  {foreach name="parentList" item="vo"}
  <option value="{$key}">{$vo|raw}</option>
  {/foreach}
</select>
  • 缩进含 Tree 占位符,选项必须 |raw。
  • 编辑时传入 $excludeIds(自身及下级),避免挂到自己下面。

后台 AMD 模块(add / edit 弹层)

后台列表点「添加/编辑」时,Layer 会单独打开 add/edit 页面(新 iframe),不会继承列表页里的 define('backend/…')。若只在 index.html 里写 require.callback,弹层会去拉不存在的 /assets/js/backend/….js,控制台报 Script error for "backend/…",上传/选择附件等全部失效。

  • 必须:index / add / edit(及 detail 等动作页)各自能加载同一套 AMD 定义。
  • 推荐:抽成视图 script.html,各动作 {include file="…/script" /};不要新建 public/assets/js/backend/** 单页 JS(见 admin-no-extra-assets)。
  • 动态插入的上传行(如 SKU)追加 DOM 后,再调 Form.events.faupload($form) 与 Form.events.faselect($form)。
<!-- index.html / add.html / edit.html -->
{include file="shop/goods/script" /}

统一上传/选择:build_upload_field()

后台图片/附件字段优先用 build_upload_field()(app/common.php),生成 .faupload + .fachoose + 预览,避免各页手写不一致。

// 单图
{:build_upload_field('c-image', 'row[image]', (string)($row['image'] ?? ''), ['mode'=>'image'])}
// 图集(图片+视频)
{:build_upload_field('c-images', 'row[images]', (string)($row['images'] ?? ''), ['mode'=>'medias'])}
// 仅上传、不要选择库
{:build_upload_field('c-file', 'row[file]', '', ['mode'=>'file', 'choose'=>false])}
  • 模式:image / images / file / files / media / medias(media* = 图片+视频)
  • 类名以 .faupload / .fachoose 为准(兼容旧 .plupload)
  • 仍须页面完成 AMD Form.api.bindevent,否则按钮无响应