JOYZL ENO

总览

所有方法

从服务器获得的JSON对象以及JS创建的数据对象，在本文档中统称“实体对象”。

方法用途
eno.get从HTML标签元素获取单个实体对象
eno.gets从HTML标签元素获取多个实体对象
eno.set将单个实体对象设置到HTML标签元素
eno.sets将多个实体对象设置到HTML标签元素
eno.select查找单个匹配的HTML标签元素
eno.selects查找多个匹配的HTML标签元素
eno.createHTML字符串创建标签元素实例
eno.append将HTML字符串或标签元素实例添加到文档中指定位置
eno.replace用HTML字符串或标签元素实例替换文档中已有标签元素
eno.remove移除文档中标签元素
eno.hide隐藏文档中显示的标签元素
eno.show显示文档中隐藏的标签元素
eno.toggle切换指定标签元素显示并隐藏同级其它标签元素
eno.bind标签元素绑定事件
eno.entity从事件或标签元素获取关联的实体对象
eno.element从事件获取关联实体对象的标签元素
eno.target从事件获取特定目标标签元素
eno.query获取当前或指定URL中的查询参数

eno.get(element, selector, converter)
eno.gets(element, selector, converter)

从指定的HTML标签元素获取实体对象。 标签元素的 name 属性将作为实体对象字段名，普通标签元素的 innerText 将作为字段值； 如果是媒体标签元素 src 属性值将作为字段值； 如果是控件标签元素 value 属性将作为字段值。

element 参数表示从中检索实体对象的标签元素实例，如果同时指定selector参数， 则element作为选择器字符串匹配标签元素的限制范围。

selector 参数为选择器字符串，用于查找要从中检索实体对象的标签元素，如果同时指定element参数， 则element作为选择器字符串匹配标签元素的限制范围。 如果省略element则在整个文档中查找标签元素。

converter 参数接受一个方法作为值的转换处理，可以自定义元素值的获取方式。 必须为元素指定 name="name" 属性 以触发转换动作。 方法拥有三个参数 function(element, entity, name)， element 表示标签元素，entity 表示正在构建的实体对象，name 为name 属性的值。 默认的行为有“取值”和“赋值”，从元素取得值然后赋值给实体对象；方法的返回值将决定不同的行为： 如果没有返回值(undefined 未执行 return 或 retuen;)，则认为方法未执行任何处理，将执行默认取值和赋值行为； 如果返回 null 表示方法执行了取值与赋值处理，无须再执行默认行为； 如果返回其它值，表示方法仅执行了取值处理，将执行默认的赋值行为；

eno.get 返回单个实体对象，即便发现多个实体对象也仅返回单个实体对象。

eno.gets 以数组形式返回多个实体对象。即便只有单个实体对象也以数组返回。

支持以下重载形式：

eno.get(element)
eno.gets(element)

从element标签元素实例中检索实体对象。

eno.get(selector)
eno.gets(selector)

在整个文档中查找selector匹配的标签元素，然后在标签元素中检索实体对象。

eno.get(element, selector)
eno.gets(element, selector)

在element及其子元素查找selector匹配的标签元素，然后在标签元素中检索实体对象。

eno.get(element, converter)
eno.gets(element, converter)

从element标签元素实例中检索实体对象，并指定转换方法。

示例

从表单获取用户输入值

<form id="form1">
	<input name="id" type="hidden" value="iu7ytgfr5"/>
	<input name="name" type="text" value="无名"/>
	<input name="email" type="email" value="xxxx@joyzl.com"/>
	<select name="type" value="1">
		<option value="1">TYPE 1</option>
		<option value="2">TYPE 2</option>
	</select>
	<textarea name="remark">备注</textarea>
</form>
import eno from "@joyzl/eno";

let entity = eno.get("#form1");
console.log(entity);

尝试一下，点击下方按钮以从表单获取实体对象。

从列表获取实体对象数组

<div id="list1" class="g v vm1 brs">
	<div class="secondary pm">
		<div name="name">Simon</div>
		<div name="email">simon@joyzl.com</div>
	</div>
	<div class="secondary pm">
		<div name="name">Chen Luo</div>
		<div name="email">cl@joyzl.com</div>
	</div>
	<div class="secondary pm">
		<div name="name">Li Xiao Ming</div>
		<div name="email">lxm@joyzl.com</div>
	</div>
</div>
import eno from "@joyzl/eno";

let entities = eno.gets("#list1>div");
console.log(entities);

尝试一下，点击下方按钮以从列表获取实体对象。

Simon
simon@joyzl.com
Chen Luo
cl@joyzl.com
Li Xiao Ming
lxm@joyzl.com

利用自定义转换方法将性别字符串转换为整数值

import eno from "@joyzl/eno";

let entity = eno.get("#form1", function(element, entity, name) {
	if (name === "gender") {
		// 性别转换数值
		if(element.value == "男") {
			return 1;
		} else
		if(element.value == "女") {
			return 0;
		}
	} else
	if (name === "type") {
		entity.type = element.value;
		// 已取值赋值，阻止默认行为
		return null;
	}
	// 其它由默认行为处理
});
console.log(entity);

eno.set(element, selector, entity, converter)
eno.sets(element, selector, entity, converter)

将实体对象设置到指定的HTML标签元素以显示。 标签元素的 name 属性将对应实体对象字段名，普通标签元素的 innerText 将设置字段值； 如果是媒体标签元素 src 属性值将设置字段值； 如果是控件标签元素 value 属性将设置字段值。

标签元素必须设置 name 属性以对应实体对象字段名； 支持点语法，例如：name="user.name"，将对应实体对象 {user{name:"simon"}} 中的 "simon" 值； 如果字段值为数组，将合并数组值为字符串，以逗号分隔； 未设置 name 属性的标签元素将被忽略。

element 参数表示将显示实体对象的标签元素实例，如果同时指定selector参数， 则element作为选择器字符串匹配标签元素的限制范围。

selector 参数为选择器字符串，用于查找要显示实体对象的标签元素，如果同时指定element参数， 则element作为选择器字符串匹配标签元素的限制范围。 如果省略element则在整个文档中查找标签元素。

entity 要设置到标签元素的实体对象，必须指定此参数即便为 null 也不能省略。

converter 参数接受一个方法作为值的转换处理，可以自定义元素值的设置方式。 必须为元素指定 name="name" 属性 以触发转换动作。 方法拥有三个参数 function(element, entity, name)， element 表示标签元素，entity 表示正在设置的实体对象，name 为name 属性的值。 默认的行为有“取值”和“赋值”，从实体对象取得值然后赋值给标签元素；方法的返回值将决定不同的行为： 如果没有返回值(undefined 未执行 return 或 retuen;)，则认为方法未执行任何处理，将执行默认取值和赋值行为； 如果返回 null 表示方法执行了取值与赋值处理，无须再执行默认行为； 如果返回其它值，表示方法仅执行了取值处理，将执行默认的赋值行为；

eno.set 设置单个实体对象，即便为数组形式的多个实体对象也仅设置首个实体对象。

eno.sets 设置数组形式的多个实体对象。即便是单个实体对象也视为数组。

eno.sets 设置多个实体对象时，支持<template>模板； element和selector定位的标签元素视为容器，模板应位于容器中且在设置时被克隆，模板前后的同级其它标签将被保留。 如果未指定模板，则容器下属的所有标签元素将被视为模板。

支持以下重载形式：

eno.set(element, entity)
eno.sets(element, entity)

将实体对象设置到element标签元素。

eno.set(selector, entity)
eno.sets(selector, entity)

在整个文档中查找selector匹配的标签，然后将实体对象设置到标签元素。

eno.set(element, selector, entity)
eno.sets(element, selector, entity)

在element及其子元素查找selector匹配的标签，然后将实体对象设置到标签元素。

eno.set(element, entity, converter)
eno.sets(element, entity, converter)

将实体对象设置到element标签元素，并指定转换方法。

示例

实体对象设置到表单

import eno from "@joyzl/eno";

let entity = {...};
eno.set("#form2", entity);
<form id="form2">
	<input name="id" type="hidden" />
	<input name="name" type="text" />
	<input name="email" type="email" />
	<select name="type" >
		<option value="1">TYPE 1</option>
		<option value="2">TYPE 2</option>
	</select>
	<textarea name="remark"></textarea>
</form>

尝试一下，点击下方按钮将实体对象设置到表单。

实体对象数组构建列表

import eno from "@joyzl/eno";

let entities = [{...}];

// 构建列表
eno.sets("#list1", entities);
<div id="list1" class="g v vm1 brs">
	<div class="secondary pm">
		<div name="name"></div>
		<div name="email"></div>
	</div>
</div>

尝试一下，点击下方按钮用实体对象构建列表。

上面的示例存在一个缺陷，当网页刚呈现给用户之前还未设置实体对象时， 列表容器中的标签元素将以默认方式呈现给用户，这看起来有些残缺。 可以通过 <template> 标签指定模板来解决这个问题， 同时在没有数据可呈现时显示更友好的信息提示用户。

import eno from "@joyzl/eno";

let entities = [{...}];

// 隐藏等待消息
eno.hide("#list1", "#wait");
// 构建列表
eno.sets("#list1", entities);
<div id="list1" class="g v vm1 brs">
	<div id="wait">
		正在读取数据...
	</div>
	<template>
		<div class="secondary pm">
			<div name="name"></div>
			<div name="email"></div>
		</div>
	</template>
</div>

利用自定义转换方法将性别值转换为字符串

import eno from "@joyzl/eno";

let entities = [{...}];

eno.sets("#list1", entities, function(element, entity, name) {
	if (name === "gender") {
		// 性别转换字符
		if(entity.gender == 1) {
			return "男";
		} else
		if(entity.gender == 0) {
			return "女";
		}
	} else
	if (name === "type") {
		if(entity.type > 0){
			element.classList.add("primary");
		} else {
			element.classList.add("secondary");
		}
		// 阻止默认行为
		return null;
	}
	// 其它由默认行为处理
});

eno.select(element, selector)
eno.selects(element, selector)

查找匹配的HTML标签元素。

element 参数作为选择器字符串匹配标签元素的限制范围，如果未指定则在整个文档中查找。

selector 参数为选择器字符串，与原生 JavaScript 的 document.querySelector() 行为和选择器字符串格式完全相同。

eno.select 返回匹配的单个标签元素，即便有多匹配项个也仅返回第一个。

eno.selects 返回匹配的多个标签元素。即便仅有单个匹配项也以数组形式返回。

选择器字符串 CSS选择器，与样式表选择器的格式和行为完全相同； 详细描述请参考 CSS 3 Selectors 。

支持以下重载形式：

eno.select(selector)
eno.selects(selector)

将在整个文档中查找匹配的标签元素。

示例

在整个文档查找标签元素

import eno from "@joyzl/eno";

let element = eno.select("#list1");

在指定标签元素范围内查找

import eno from "@joyzl/eno";

let element = eno.select("#list1");
let items = eno.selectes(element, ".secondary");

// 以下两种形式结果相同

items = eno.selectes("#list1", ".secondary");
items = eno.selectes("#list1 .secondary");

eno.create(html)

创建HTML文本字符串为标签元素实例。此方法创建的标签元素实例基于当前文档上下文，但不会插入文档中。 如果创建的标签元素仅有一个根级，则返回根级标签元素实例； 如果创建的标签元素有多个根级，则以数组形式返回。

html 参数为字符串形式的HTML标签元素。

示例

通过HTML字符串创建标签元素实例

import eno from "@joyzl/eno";

const html = "<div><span>sample</span></div>";
let element = eno.create(html);

通过HTML文件创建标签元素实例

import eno from "@joyzl/eno";
import html from "./sample.html";

let element = eno.create(html);

注意：需要 WEBPack 的 html-loader 插件以支持引入HTML文件。

eno.append(element, selector, html)

创建HTML文本字符串为标签元素实例，并插入到指定标签元素的子项尾部。

element和selector 参数含义与 eno.select 完全相同。

html 参数为字符串形式的HTML标签元素。

支持以下重载形式：

eno.append(html)

将HTML标签元素插入到文档body中的尾部(document.body)。

eno.append(element, html)

将HTML标签元素插入到element中的尾部。

eno.append(selector, html)

将HTML标签元素插入到selector匹配标签元素中的尾部。

示例

将HTML文件插入文档body中

import eno from "@joyzl/eno";
import html from "./sample.html";

let element = eno.append(html);

将HTML文件插入指定标签元素中

import eno from "@joyzl/eno";
import html from "./sample.html";

let element = eno.append("main", html);

eno.replace(element, selector, html)

创建HTML文本字符串为标签元素实例，并替换指定标签元素。

element和selector 参数含义与 eno.select 完全相同。

html 参数为字符串形式的HTML标签元素。

支持以下重载形式：

eno.replace(element, html)

用HTML标签元素替换element。

eno.replace(selector, html)

用HTML标签元素替换selector匹配项。

示例

用HTML文件替换文档中指定的自定义标签元素

import eno from "@joyzl/eno";
import html from "./sample.html";

let element = eno.replace("custom-element", html);

eno.remove(element, selector)

移除文档中指定或匹配的标签元素。

element和selector 参数含义与 eno.selects 完全相同。

支持以下重载形式：

eno.remove(element)
eno.remove(selector)

示例

从文档中移除指定的标签元素

import eno from "@joyzl/eno";

eno.remove("#list1");

eno.hide(element, selector)

隐藏文档中显示的标签元素。如果标签元素已经隐藏则不会有任何效果； 此方法通过标签元素的 hidden 属性隐藏标签， 隐藏后可通过 eno.show 逆向操作。

element和selector 参数含义与 eno.selects 完全相同。

支持以下重载形式：

eno.hide(element)
eno.hide(selector)

eno.show(element, selector)

显示文档中隐藏的标签元素。如果标签元素已经可见则不会有任何效果； 如果标签元素通过特定的样式类隐藏，则此方法不会使其显示。 此方法主要用于 eno.hide 的逆向操作。

element和selector 参数含义与 eno.selects 完全相同。

支持以下重载形式：

eno.show(element)
eno.show(selector)

eno.toggle(element, selector, applyClass, otherClass)

切换指定标签元素显示并隐藏同级其它标签元素， 也可指定样式类代替默认的隐藏和显示行为。

element和selector 参数含义与 eno.selects 完全相同。

applyClass和otherClass 参数分别对应指定匹配标签元素和同级其它标签元素， 既：匹配项应用applyClass样式类，同时移除applyClass样式类； 其它项项应用otherClass样式类，同时移除applyClass样式类。

支持以下重载形式：

eno.toggle(element)
eno.toggle(selector)
eno.toggle(element, selector)
eno.toggle(element, applyClass, otherClass)
eno.toggle(selector, applyClass, otherClass)

示例

切换卡片形式内容显示


<div class="h brm sa pale dark">
	<div id="toggleA" class="w20 v vm1">
		<a name="#c1" class="selected pm">JOYZL ENO</a>
		<a name="#c2" class="secondary pm">JOYZL STYLE</a>
		<a name="#c3" class="secondary pm">JOYZL html-include</a>
	</div>
	<hr class="light" />
	<div id="toggleC" class="g">
		<div id="c1" class="pm">...</div>
		<div id="c2" class="pm" hidden>...</div>
		<div id="c3" class="pm" hidden>...</div>
	</div>
</div>
import eno from "@joyzl/eno";

eno.bind("#toggleA", "click", function(event) {
	const element = event.target || event.srcElement;
	// 切换选中效果
	eno.toggle(element, "selected", "secondary");
	// 切换内容显示
	eno.toggle("#toggleC", element.name);
});

尝试一下，点击下方左侧菜单切换显示。

JOYZL ENO 是 JSON 与 HTML 操作交互的 JavaScript 开源组件。 具有简单易用，性能卓越，自由灵活的特点； 标准函数调用，无任何额外配置，极少内存占用，无任何对象侵入，没有任何额外的依赖包。

官网 eno.joyzl.net 源码 Github

eno.bind(element, selector, eventName, listener)

标签元素绑定事件。

element和selector 参数含义与 eno.selects 完全相同。

eventName 参数指示须绑定的标签元素事件类型名称，例如："click"、"change"，事件类型名称是大小写敏感的字符串。

listener 参数指定事件监听回调方法（函数），方法形式为 function handleEvent(event)，其中 event 参数描述已发生的事件。

支持以下重载形式：

eno.bind(element, eventName, listener)
eno.bind(selector, eventName, listener)

事件监听最佳实践

当监听动态构建的HTML内容用户点击事件时，例如通过 eno.sets 生成的多项HTML内容， 常规的做法是为每一项可点击标签元素分别绑定监听事件回调方法。 eno 并不推荐这样的方案，缺点如下：

eno 推荐的方案是：对于动态构建的HTML内容，仅为这些变化内容的父级标签元素（容器）绑定事件， 利用事件冒泡规则和文档的树形结构由单个事件监听方法处理事件。 对于 eno.sets 生成的动态HTML内容，可通过 eno.entity 和 eno.element 方法分别获取用户点击的实体对象和关联的元素；这两个方法专门为此而设计。 对于其它方式构建的HTML元素，例如菜单列表，可通过为元素设置特定的属性来区分点击项； eno.target 方法专门用于此情形，用以判别用户是否点击具有特定属性的标签元素范围。

示例

监听动态内容点击事件，将通过监听动态内容的父级标签元素（容器）而获取点击的实体对象和元素。

<div id="list1" class="g v vm1 brs">
	<template>
		<div class="secondary pm">
			<div name="name"></div>
			<div name="email"></div>
		</div>
	</template>
</div>
import eno from "@joyzl/eno";

let entities = [{...}];

// 绑定容器事件
eno.bind("#list1", "click", function(event){
	const entity = eno.entity(event);
	const element = eno.element(event);
	if(entity){
		// 处理事件
		...
	}
});
// 构建列表
eno.sets("#list1", entities);

监听静态内容点击事件，将通过监听静态内容的父级标签元素（容器）而识别目标项。


<div id="menu1" class="w20 v vm1">
	<a name="#c1" class="selected pm">
		JOYZL ENO
	</a>
	<a name="#c2" class="secondary pm">
		JOYZL STYLE
	</a>
	<a name="#c3" class="secondary pm">
		JOYZL html-include
	</a>
</div>
import eno from "@joyzl/eno";

eno.bind("#menu1", "click", function(event) {
	// 获取具有name属性的目标标签元素
	const element = eno.target(event, "name");
	if(element){
		if(element.name === "#c1"){
			...
		} else 
		if(element.name === "#c2"){
			...
		} else 
		if(element.name === "#c3"){
			...
		}
	}
});

尝试一下，在下方列表点击。

eno.entity(e, selector)

从事件或标签元素获取由 eno.set 或 eno.sets 关联的实体对象。

e 参数可以为事件对象 Event 或 Element 标签元素。 传递事件对象时，将根据事件对象向上查找文档树结构获取关联的实体对象。 当作为 element 标签元素传递时， element和selector 参数含义与 eno.selects 完全相同； 可在没有触发事件时获取标签元素关联的实体对象。

支持以下重载形式：

eno.entity(event)
eno.entity(element, selector)

示例

请参考 eno.bind 的示例。

eno.element(e)

从事件或标签元素获取由 eno.set 或 eno.sets 关联实体对象的标签元素。

e 参数为事件对象 Event ，将根据事件对象向上查找文档树结构获取关联实体对象的标签元素。

示例

请参考 eno.bind 的示例。

eno.target(event, name, value)

根据事件对象获取具有指定属性或值的标签元素。 此方法利用文档树形结构特性用于简化事件处理。

event 参数为事件对象 Event ，将根据事件对象向上查找文档树结构获取关联实体对象的标签元素。

name 参数为要查找的属性名称。

value 参数为要查找的属性值。

支持以下重载形式：

eno.target(event)

此形式仅能获取事件触发源标签元素 与 Event.target 属性相同。

eno.target(event, name)

此形式获取事件触发源以及包含源的具有指定属性的标签元素，不检查属性值。

eno.target(event, name, value)

此形式获取事件触发源以及包含源的具有指定属性的标签元素，同时检查属性值。

示例

请参考 eno.bind 的示例。

eno.query(url, name)

获取当前或指定URL中的查询参数。

url 参数为要在其中查找的URL；缺省此参数时默认当前浏览器地址栏中的URL。

name 参数为要在URL中查找的参数名称；缺省此参数时将所有参数以JSON对象返回。

支持以下重载形式：

eno.query()
eno.query(name)
eno.query(url)