Jiess文档

Appearance

jiess 实例 ​

jiess实例是一个全局单例，该对象用于提供全局的属性和方法

访问实例 ​

  • 通过$entry注册时，该函数会返回Jiess实例
  • 项目运行时，可调用$jiess()方法，获取Jiess实例

方法和属性 ​

$watch ​

  • 类型 Function
  • 参数 (proxy: ProxyConstructor, param?: any, callback: Function)
  • 详细 观察Jiess响应式（proxy）中指定字段（param）的变化，并通知callback

callback ​

js
function(newValue, oldValue) {
	// 分别为观察到的新值，和以前的旧值
	console.log(newValue, oldValue)
}

param参数 ​

  • 定义为字符串：指定需要观察的字段
  • 定义为对象时：
    • field：指定需要观察的字段
    • isSync：是否异步触发，一般在对对象的整体观察时用到
    • forceUpdate：观察到赋值操作，是否一定强制更新
js
import { $ref, $watch } from '@jiess/plus';
function setup() {
	// 创建响应式对象，并赋予初始值 1
	const count = $ref(1);
	// 自增，模拟触发响应式
	setInterval(() => ++count.value, 1000)
	// 观察响应式对象count中value属性的变化
	$watch(count, 'value', (newValue, oldValue) => {
	  console.log(newValue, oldValue)
	})
}

响应式对象整体观察 ​

  • 未定义param参数时
  • param定义为对象，且field未定义时

满足上述条件，则整体观察响应式对象，即观察响应式对象中的所有属性和子响应式的变化

js
import { $ref, $watch } from '@jiess/plus';
function setup() {
	// 创建响应式对象，并赋予初始值 1
	const data = $ref({ count: 1});
	// 自增，模拟触发响应式
	setInterval(() => ++data.value.count, 1000)
	// 观察响应式对象count中value属性的变化
	$watch(count, { isSync: false }, (newValue, oldValue) => {
	  console.log(newValue, oldValue)
	})
}

$watchEffect ​

  • 类型 Function
  • 参数 (fn:function, param?:object)
  • 返回 一个 memoized 回调函数
  • 详细

提供一个函数，并观察函数体中依赖的响应式的变化，如果变化，则再次执行该函数

在初始化过程中会执行（fn），并观察函数体（fn）中响应式数据的变化，如果发生变化，则自动执行（fn）； param为一个对象，可以提供tag属性，用于确保执行函数（fn）的唯一性，相同的tag仅会注册一次

返回该回调函数的 memoized 版本，该回调函数仅在某个依赖项改变时才会更新，也可以手动触发更新

js
import { $ref, $watchEffect } from '@jiess/plus';
function setup() {
	// 创建响应式对象，并赋予初始值 1
	const count = $ref(1);
	// 自增，模拟触发响应式
	setInterval(() => ++count.value, 1000)
	// 当依赖的响应式发生变化，便会自动执行
	$watchEffect(() => {
		// 这里使用Jiess响应式
	  console.log(count.value)
	})
}

model 同步或异步更新 ​

函数体中可以有多个响应式，而一个同步任务中也可以触发多个响应式：

  • model值为async（默认值）：等待一个异步，再执行一次fn函数
  • model值为sync：同步触发，即每个响应式变化执行一次fn函数
js
import { $ref, $watchEffect } from '@jiess/plus';
function setup() {
	// 创建响应式对象，并赋予初始值 1
	const count = $ref(1);
	// 自增，模拟触发响应式
	setInterval(() => ++count.value, 1000)
	// 当依赖的响应式发生变化，便会自动执行
	$watchEffect((val = count.value, field) => {
		// val为当前依赖响应式的值，field为触发字段
		console.log(val);
	}, { model: 'sync' })
}

在同步观察中，响应式的变化在第一事件通知到fn函数，而此刻响应式对象还未赋值完成， 所以需要通过fn函数的回参val拿到此刻最新的值，field为当前触发的字段

$isReactive ​

  • 类型 Function
  • 参数 (proxy: ProxyConstructor)
  • 返回 Boolean
  • 详细 用于检测传入的参数是否为Jiess响应式代理对象（响应式数据）
js
import { $ref, $isReactive } from '@jiess/plus';
function setup() {
	// 创建响应式对象，并赋予初始值 1
	const count = $ref(1);
	// true
	console.log($isReactive(count))
}

$val ​

  • 类型 Function
  • 参数 (proxy: ProxyConstructor, param?: any, iswarn = true)
  • 返回 Observer
  • 详细 观察Jiess响应式对象（proxy）的字段（param）的变化，并返回观察者对象

$val通常应用于页面的响应式更新，也就是咱们常说的数据驱动页面

js
import { $ref, $val } from '@jiess/plus';
function setup() {
	// 创建响应式对象，并赋予初始值 1
	const count = $ref(1);
	// 自增，模拟触发响应式
	setInterval(() => ++count.value, 1000)
	// 观察响应式对象count中value属性的变化，并更新页面
	this.add(this.render({
		children: $val(count, 'value')
	}))
}

观察者映射为真实数据

  • 属性绑定时提供的是Jiess观察者，但在解析过程中会透过观察器，直接应用真实的值
  • 观察者会持续观察响应式数据的变化，并及时的通知变化，以便更新页面渲染

由于响应式数据和观察器均与定义时的上下文无关，所以半自动的手动观察方案非常灵活， 您可以方便的对响应式数据和观察器作为数据传递，从而实现跨组件的响应式控制

param参数 ​

  • 定义为字符串或数字：指定需要观察的字段
  • 定义为对象时：
属性必要默认值类型说明
field是——String指定观察的键名
isSync否falseBooleanfalse是否同步观察
forceCheckSame否falseBooleanfalse是否深度判断相似性
done否——Function或AsyncFunctionfalse赋值前的处理函数
defaultValue否————done为异步函数时，若未指定，则将value作为初始值
js
import { $ref, $val } from '@jiess/plus';
function setup() {
	// 创建响应式对象，并赋予初始值 1
	const count = $ref(1);
	// 自增，模拟触发响应式
	setInterval(() => ++count.value, 1000)
	// 观察响应式对象count中value属性的变化，并更新页面
	this.add(this.render({
		children: $val(count, { field: 'value', isSync: true })
	}))
}

响应式对象整体观察 ​

  • 未定义param参数时
  • param定义为对象，且field未定义时

满足上述条件，则整体观察响应式对象，即观察响应式对象中的所有属性和子响应式的变化

js
import { $reactive, $val } from '@jiess/plus';
function setup() {
	// 创建响应式对象，并指定构造响应式深度1
	const info = $reactive({
		name: '小明',
		schoolInfo: { schoolName: '希望小学', grade: '六年级	' }
	}, 1);
	// 自增，模拟触发响应式
	setTimeout(() => {
		info.schoolInfo.grade = '五年级'
	}, 1000)
	// 未指定观察字段，则对响应式对象整体进行观察
	// 本例中，可以观察到响应式对象的子响应式变化
	$val(info).observe((val) => {
		console.log(val);
	});
}

响应式数据矫正 ​

在及时得到响应式的变化后，也经常需要对该数据进行修饰矫正，再更新页面

js
import { $reactive, $val } from '@jiess/plus';
function setup() {
	// 创建响应式对象，并指定构造响应式深度1
	const info = $reactive({
		name: '小明',
		schoolInfo: { schoolName: '希望小学', grade: '六年级	' }
	}, 1);
	// 自增，模拟触发响应式
	setTimeout(() => {
		info.schoolInfo.grade = '五年级'
	}, 1000)
	// 未指定观察字段，则对响应式对象整体进行观察
	this.add(this.render({
		children: $val(info, {
			field: 'schoolInfo',
			done: data => {
				// 观察schoolInfo，所以data为其最新值
				const { schoolName, grade } = data;
				return `${info.name}在${val}上学，今年已经${grade}了`
			}
		})
	}))
}

注：若（proxy）非Jiess响应式数据，控制台会警告，设iswarn设为false，可关闭警告

响应式数据矫正拓展 ​

响应式数据矫正可以理解为简化版的$computed，在实际应用中非常广泛

js
import { $reactive, $val } from '@jiess/plus';
function setup() {
	const arr = [{name:'张飞',age:18},{name:'关羽',age:20}];
	// 构造Jiess响应式数据，并指定构造深度
	const data = $reactive(arr, 2);
	// 自增，模拟触发响应式
	setTimeout(() => {
		data[0].age = 22
	}, 1000);
	this.add(
		this.render({
			// 对响应式的整体观察
			// 注：实际研发中常绑定为组件参数
			children: $val(data)
		}),
		data.map(item => {
			return this.render({ is: 'ul' },
				this.render({
					is: 'li',
					children: $val(item, {
						// 需要观察的字段
						field: 'age',
						// 调整最终的结果值
						done: age => {
							let tip = `${item.name}是：`;
							tip += age < 20 ? '弟弟' : '哥哥' ;
							return tip;
						}
					})
				}), '今年',
				this.render({
					is: 'li',
					// 对指定的字段进行观察
					children: $val(item, 'age')
				}), '岁'
			)
		})
	);
}

$reactive ​

  • 类型 Function
  • 参数 (object:object|array, deep?:number)
  • 返回 Proxy 响应代理对象
  • 详细

将数组或对象包装为Jiess响应式代理对象（响应式数据）

js
// setup 构造函数中
import { $reactive } from '@jiess/plus';
function setup() {
	// 接受数组或对象，返回响应式代理对象
	const data = $reactive({
	  count: 1
	});
	// 后续操作代理对象即可
	console.log(data.count) // 1
}

定义响应式构建深度 ​

$reactive默认的代理深度为0，即当前对象的属性会被观察，也可以控制构建深度

js
import { $reactive, $val } from '@jiess/plus';
function setup() {
	// 创建响应式对象，并指定构造响应式深度1
	const info = $reactive({
		name: '小明',
		// 深度为1，即可观察到schoolName和grade的变化
		schoolInfo: { schoolName: '希望小学', grade: '六年级	' }
	}, 1);
}

$ref ​

  • 类型 Function
  • 参数 (value:object|array, deep = 1)
  • 返回 Proxy 响应代理对象
  • 详细

将数据包装为Jiess响应式代理对象（响应式数据），其中value属性为实际代理值

js
import { $ref } from '@jiess/plus';
function setup() {
	// 创建响应式对象，并赋予初始值 1
	const count = $ref(1);
	// 响应对象的value属性为代理值
	console.log(count.value) // 1
}

注：$ref实质时基于$reactive的语法糖

定义响应式构建深度 ​

$ref默认的代理深度为1，及value属性为响应式对象，其子层级属性会被观察

$computed ​

  • 类型 Function
  • 参数 (val: function|object, model: string)
  • 返回 Proxy 响应代理对象
  • 详细

将函数或带有getter/setter的对象，包装为计算属性，计算属性也是Jiess响应式

  • 计算属性与$ref响应式相似，同样通过value取值
  • 计算属性与$watchEffect相似，getter函数体中的响应式变化，会触发重新计算
js
import { $reactive, $computed } from '@jiess/plus';
function setup() {
	// 使用开发者提供的对象，返回响应式代理对象
	const data = $reactive({
	  count: 1
	});
	
	const state = $computed(() => {
	  return data.count + '个'
	})
	// 该属性会随着依赖的响应数据而发生变化
	console.log(state.value) // 1个
}

$component ​

  • 类型 Function
  • 参数 (name: string, component: Component)
  • 返回
  • 详细

全局注册指定名称（name）的 Jiess组件

js
import { $component } from '@jiess/plus';
function setup() {
	import MyComponent from './MyComponent.js';
	$component('MyComponent', MyComponent);
	// ...使用时直接使用名称即可
	this.render({ is: 'MyComponent' });
}

$useComponent ​

  • 类型 Function
  • 参数 (name: string)
  • 返回 Jiess组件
  • 详细

根据指定名称（name）获取已在全局注册的 Jiess组件

js
import { $useComponent } from '@jiess/plus';
function setup() {
	// 获取全局注册的名为 MyComponent 的组件
	const MyComponent = $useComponent('MyComponent');
}

$set ​

  • 类型 Function
  • 参数 (proxy: ProxyConstructor, value: object, param: object)
    • proxy 数据源，为响应式对象
    • value 需要加入数据源的数据
    • param 其他配置参数
  • 返回 给定数据对应的响应式代理对象
  • 详细 将给定数据设置为指定响应式对象的属性
js
import { $set, $reactive } from '@jiess/plus';
function setup() {
	const data = $reactive({ title: '个人信息' });
	$set(data, 'info', { name: '张飞', age: 18 });
}