# thinplus

**Repository Path**: juuen/thinplus

## Basic Information

- **Project Name**: thinplus
- **Description**: 轻量化、沉浸式、无约束、纯ES语法的WEB开发框架。
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-09-06
- **Last Updated**: 2024-04-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: thin, thinjs, thinplus

## README

- [thinplus.js 使用手册](#thinplusjs-使用手册)
  - [简介](#简介)
  - [特性](#特性)
  - [如何使用](#如何使用)
    - [第一步：添加引用](#第一步添加引用)
    - [第二步：编写代码](#第二步编写代码)
  - [语法介绍](#语法介绍)
    - [模板（template）](#模板template)
      - [函数模板参数成员](#函数模板参数成员)
      - [对象模板成员](#对象模板成员)
  - [控制语句](#控制语句)
    - [IF 语句](#if-语句)
    - [SWITCH 语句](#switch-语句)
    - [WHEN 语句](#when-语句)
  - [数据渲染](#数据渲染)
    - [数据源](#数据源)
    - [数据漫游器](#数据漫游器)
    - [数据双向绑定](#数据双向绑定)
    - [SELECT 数据渲染](#select-数据渲染)
  - [事件处理](#事件处理)
    - [事件函数参数](#事件函数参数)
  - [数据漫游器默认值及格式化](#数据漫游器默认值及格式化)
    - [默认值](#默认值)
    - [格式化](#格式化)
    - [组合使用](#组合使用)
  - [其他说明](#其他说明)
  - [相关组件推荐](#相关组件推荐)

# thinplus.js 使用手册

## 简介

thinplus.js 是一个纯净的、轻量级、沉浸式前端框架。
设计灵感源于 thin.js ，thinplus 选择回归自然，采用标准 ES 代码编写，不依赖任何外部组件，不限制开发环境，提供一码到底的沉浸式开发体验。

## 特性

- 轻量化、纯净化
- 无运行环境依赖
- 无外部组件包依赖
- 沉浸式开发体验
- 数据垂直继承，随用随取
- 数据漫游器默认值
- 数据漫游器格式化

## 如何使用

### 第一步：添加引用

只需在 head 里添加 thinplus.js 的引用即可。

```html
<script src="xxxxx/thinplus.js"></script>
```

### 第二步：编写代码

```javascript
<script>let div=document.querySelector("div.container"); div.render(template);</script>
```

## 语法介绍

### 模板（template）

thinplus 是基于模板进行动态渲染，模板是指将 HTML 元素结构抽象为 Javascript 对象的一种书写表达。
目前渲染模板有如下几种：

- **对象模板（object template）**

  这是最常用模板（推荐），样例如下：

```javascript
HTMLElement.render({
	div: "这是对象模板",
	class: "css class",
	id: "element id"
});
```

- **字符串模板（string template）**

  这是文本模板，支持纯文本和 HTML 文本，样例如下：

```javascript
HTMLElement.render("这是<b>字符串模板</b>");
```

- **数组模板（array template）**

  这是组合模板，由对象模板、字符串模板和函数模板构成。样例如下：

```javascript
HTMLElement.render([
	{
		div: "这是对象模板",
		class: "css class",
		id: "element id"
	},
	"这是字符串模板"
]);
```

- **函数模板（function template）**

  这是自定义模板，支持匿名函数和自定义函数，样例如下：

```javascript
HTMLElement.render({
	div: function (r) {
		return r.data || "这是函数模板";
	}
});
```

#### 函数模板参数成员

回调函数参数为对象，对象的成员结构如下：

| 成员      | 类型        | 说明         |
| :-------- | :---------- | :----------- |
| container | HTMLElement | 当前容器元素 |
| data      | object      | 渲染数据对象 |

#### 对象模板成员

| 成员    | 类型                | 说明                                                                                                   |
| :------ | :------------------ | :----------------------------------------------------------------------------------------------------- |
| id      | string              | HTML 元素 ID 属性（全局属性），不支持数据漫游器                                                        |
| class   | string              | HTML 元素 class 属性（全局属性），不支持数据漫游器                                                     |
| name    | string              | HTML 元素 name 属性（常用属性），不支持数据漫游器                                                      |
| title   | string              | HTML 元素 title 属性（全局属性），不支持数据漫游器                                                     |
| style   | object              | HTML 元素 style 属性                                                                                   |
| a/a2    | object              | 成员 a 为元素属性对象的简写，该对象可以设置 HTML 元素属性值，仅当元素为超链接 A 时候，使用 a2 替代 a。 |
| click   | function            | 点击事件处理函数                                                                                       |
| event   | object              | 事件处理对象，使用对象结构设置 DOM 事件                                                                |
| data    | object/string       | 设置模板渲染数据源，支持数据对象、数组、数据漫游器两、Axios 数据源                                     |
| bind    | string              | 双向数据绑定，设置数据绑定路径                                                                         |
| value   | string              | 设置数据控件默认值，如 select、input、textarea                                                         |
| options | string/array/object | 设置 select 元素选项值                                                                                 |

## 控制语句

### IF 语句

根据条件真假来控制使用真/假模板,语法结构如下：

```javascript
{
   if: 布尔表达式|条件函数,
   then: 真模板,
   else: 假模板
}

```

样例：

```javascript
HTMLElement.render({
	div: {
		if: function (r) {
			return true;
		},
		then: { p: "真模板" },
		else: { p: "假模板" }
	}
});
```

### SWITCH 语句

根据条件值来匹配模板,语法结构如下：

```javascript
{
	switch:条件,
	case:{
		条件:模板,
		条件2:模板2,
		default:默认模板
	}
}
```

样例：

```javascript
HTMLElement.render({
	div: {
		switch: "条件",
		case: {
			条件: "模板",
			条件2: "模板2",
			default: "默认模板"
		}
	}
});
```

### WHEN 语句

根据条件判断是否渲染当前模板，语法结构如下：

```javascript
{
	div:模板,
	when:条件
}
```

样例：

```javascript
HTMLElement.render({
	div: "这是WHEN语句模板",
	when: function (r) {
		return true;
	}
});
```

## 数据渲染

### 数据源

在实际应用中渲染模板通常都带有数据源，这里的数据源是指对象模板渲染时候所要读取的业务数据对象，对象模板中使用 data 属性是用来设置当前模板及其子级渲染数据源。

数据源支持的形式包含：

- 对象
- 数组
- 数据漫游器
- Axios Promise 对象

  样例：

```javascript
HTMLElement.render({
	div: [{ h2: "[[title]]" }, { p: "[[month/max]]" }],
	data: {
		title: "最大的月份",
		month: { max: "十二月", min: "一月" }
	}
});
```

### 数据漫游器

数据漫游器是指访问数据源中具体字段所约定的一种标准化格式。

格式为：`[[datapath]]`，使用双中括号作为漫游器识别符号，`datapath` 是数据访问路径，使用斜杠`/`来区分数据层级关系。

当数据源为纯数值数组数据时候，数据漫游器访问方式为`[[.]]`，此时`datapath`为点号。

样例：

```javascript
HTMLElement.render({
	div: [{ h2: "[[title]]" }, { p: "[[.]]", data: "[[months]]" }],
	data: {
		title: "含有31天的月份",
		months: ["一月", "三月", "五月", "七月", "八月", "十月", "十二月"]
	}
});
```

### 数据双向绑定

数据双向绑定主要应用于数据控件，如 select、input、textarea。采用 bind 属性来设置数据路径。

<font color="red">注意：bind 属性和 data 属性不能够设置在同一个对象模板上</font>

样例：

```javascript
HTMLElement.render({
	div: [
		{ h2: "用户信息" },
		{ p: { input: "name", a: { type: "text" }, bind: "name" } },
		{ p: { input: "", name: "gender", a: { type: "text" }, bind: "gender" } },
		{ p: { input: "", name: "remark", a: { type: "text" }, bind: "remark" } },
		{
			button: "保存",
			click: function (e) {
				console.log(e);
				//保存数据
			}
		}
	],
	data: {
		name: "李四",
		gender: "男",
		remark: "天苍苍野茫茫风吹草低现牛羊"
	}
});
```

### SELECT 数据渲染

HTML 下拉列表元素 SELECT 可以通过 options 属性赋值进行下拉列表渲染，options 可以接受的值类型包括：函数、对象、字符串、数组、模板字符串。

样例如下：

```javascript
container.render({
	div: [
		function (r) {
			console.log(r);
		},
		{
			select: "",
			options: "[[dlist]]"
		},
		{
			select: "",
			options: ["苹果", "梨子", "橘子"]
		},
		{
			select: "",
			options: { 男: "man", 女: "woman" }
		},
		{
			select: "",
			options: function (r) {
				return ["苹果", "梨子", "橘子"];
			}
		},
		{
			select: "",
			options: "苹果,梨子,橘子"
		}
	],
	data
});
```

## 事件处理

通过添加事件监听器来实现对元素事件的处理。目前提供两种事件绑定方式：

- click 属性

  结构为：{click : 回调函数}

- event 属性

  结构为：{事件名 : 回调函数, ...}

样例：

```javascript
HTMLElement.render({
	div: [
		{
			select: "",
			name: "status",
			options: ["已创建", "支付中", "已完成", "已取消"],
			event: {
				change: function (e) {
					console.log(e);
				},
				click: function (e) {
					console.log(e);
				}
			}
		},
		{
			button: "保存",
			click: function (e) {
				console.log(e);
			}
		}
	]
});
```

### 事件函数参数

**参数结构**
事件回调函数为对象，对象成员结构如下：

```javascript
 {
     sender:{事件源},
     event:{事件},
     type:{事件类型},
     org_data:{原始数据源},
     new_data:{最新数据源}
 }
```

**参数说明**

| 名称     | 类型        | 描述       |
| :------- | :---------- | :--------- |
| sender   | HTMLElement | 事件源     |
| event    | object      | 事件       |
| type     | string      | 事件类型   |
| org_data | object      | 原始数据源 |
| new_data | object      | 最新数据源 |

## 数据漫游器默认值及格式化

### 默认值

数据漫游器支持对可能的空值提供默认值，格式如下：

```javascript
[[字段名 == 默认值]];
```

### 格式化

- 货币格式化

  使用方式为`[[字段名::货币代码]]`，如人民币：`[[price::CNY]]`

- 日期格式化

  使用方式有两种：`[[字段名::date]]`和`[[字段名::datetime]]`

### 组合使用

格式化必须始终放在最后，样例如下：
`[[createtime==2000/01/01::date]]`

## name 属性赋值说明

```javascript
// 第一种方式
{
	input: "name1";
}
// 第二种方式
{
	input: "",name:"name2";
}
// 第三种方式
{
	input: "",a:{name:"name3"};
}
```

第一种方式仅针对 select、input、textarea 元素，name 属性可以通过值的形式赋值给元素对象完成属性设置。但是这种形式优先级最低。

第二、第三种方式适合所有元素。

理论上赋值优先级：第三种 > 第二种 > 第一种。

## 其他说明

- HTML 元素对象模板第一个属性必须为 HTML 元素名称
- 对象模板中 data 属性和 bind 属性不能一起设置
- HTML 元素可以使用 HTMLElement.empty()方法清空所有内容包括子元素，支持链式调用，比如 HTMLElement.empty().render()
- 数组模板不支持嵌套数组模板
- 不支持 IE 浏览器，适用于现代浏览器。

## 相关组件推荐

- [thinbuilder](https://www.npmjs.com/package/thinbuilder)
- [thindb](https://www.npmjs.com/package/thindb)
- [axios](https://axios-http.com/zh/)