跳到正文
English

行为与脚本

组件的样子由样式表决定,行为由一份脚本决定。脚本只有一个文件,不依赖任何框架和库,放在 components/bundle.js,和样式表一起分发。

怎么用

  • 在页面里先引样式表,再引这份脚本,就够了。脚本加载后会自己找到页面里的组件并接管;之后动态加进来的内容,调用一次 Hairline.init(那个容器)。
  • 行为靠标记上的属性声明,不用写脚本就能用。属性都以 data-hao- 开头。
  • 不加载脚本,组件照样能看,只是不能动。所以标记要写成「静态时也成立」的样子:弹窗和菜单平时带 hidden,日历的容器里可以先放一份静态月历。
  • 开关、单选、勾选、分段控件、下拉、折叠面板用的是浏览器原生控件,本来就不需要脚本。

属性一览

属性写在哪作用
data-hao-open="id"按钮打开那个弹窗或底部弹层
data-hao-modal.hao-scrim这是一个真的模态层,铺满全屏
data-hao-close弹窗里的按钮关闭所在的弹窗
data-hao-initial弹窗里的按钮打开时焦点落到它上面
data-hao-menu="id"按钮打开那个菜单
data-hao-calendar.hao-cal画出可以翻月的月历
data-hao-toggle筛选标签、书签点一下切换选中
data-hao-chips="single"一组筛选标签的容器一组只能选一个
data-hao-checkall="组名"「全选」勾选框管同名的一组勾选框
data-hao-tip="文字"任何元素悬停或聚焦时出现气泡提示
data-hao-toast="文字"按钮点一下弹出轻提示
data-hao-stamp="id"按钮让那个容器里的印重盖一次
data-min data-max data-step.hao-stepper步进器的范围和步长

每个组件的说明里有自己那部分的细节。

脚本里能调的

调用作用
Hairline.init(容器)接管后来加进页面的内容
Hairline.dialog.open(元素)、.close()打开、关闭弹窗或底部弹层
Hairline.menu.open(菜单, 按钮)、.close()打开、关闭菜单
Hairline.toast(文字, 选项)弹出轻提示;选项有 ok、action、onAction、duration
Hairline.calendar.create(元素)把一个容器变成月历,返回它的控制对象
Hairline.calendar.lunar(日期)查一天的农历
Hairline.calendar.terms换成自己的节气数据来源
Hairline.calendar.source换成自己的农历数据来源
Hairline.stamp(容器)重播盖印

事件

组件变化时会在自己身上发出事件,往上冒泡,可以在任何一层监听。

事件谁发出带的数据
hao-open、hao-close弹窗、底部弹层无
hao-select菜单项无
hao-change标签页、月历、筛选标签、书签、步进器、评分、列表单选新的值
hao-files上传区拖进来的文件

无障碍上做到了什么

  • 焦点管理:弹窗和弹层打开时圈住焦点,页面其余部分设为不可操作,也不跟着滚动;关闭后焦点回到触发它的地方。菜单同理。
  • 键盘:菜单、标签页、月历、评分、列表单选都按通行的键盘操作习惯实现了方向键、Home、End,浮层另有 Esc。成组的控件只占一个 Tab 停靠点。
  • 语义:脚本会补上必要的状态属性(展开、选中、按下、当前日期),月历是完整的表格结构,每一天都有完整的读法。
  • 播报:轻提示放在礼貌的实时播报区里,不抢焦点。
  • 动效:系统开启「减弱动态效果」时,进场动效不播。

历法数据的准头

  • 农历用的是浏览器自带的数据,绝大多数日子是对的,但朔落在午夜前后的极少数日子会差一天(实测 2027 年春节就差了一天)。
  • 节气用的是近似算式,个别年份会差一天,只覆盖 2001 到 2100 年。
  • 两者都留了接口,可以换成权威数据:Hairline.calendar.source 和 Hairline.calendar.terms。产品里凡是不能错的日期,都应该换。

没做的

  • 下拉刷新、弹层的下拉关闭这类手势。
  • 表格的排序与筛选、分页的数据加载、上传的进度:这些和数据有关,由使用它的产品自己接。
  • 用脚本另造的下拉面板。下拉选择一直用原生控件;桌面上面板的样子由样式表改成和菜单一致,见 Select。
  • 这份脚本是给网页用的。原生的 iOS 应用里,这些行为由系统控件提供。