Namespace, Primitive, Method

    naraku

    0.9.10 • Public • Published

    Naraku

    适合BI和OA系统的状态管理及数据可视化工具包,非前端也可以尽快掌握的组件


           好用记得点★一下
    

    名称由来

    《犬夜叉》中的BOSS奈落(ならく)的英文拼写。

    特性简介

    1. 在MVVM模式中,负责model-model的关系管理和model到viewModel的数据格式转换。
    2. 面向业务的状态管理。
    3. 事件驱动,基于发布订阅模式的数据/状态/消息总线,可以代替Redux等状态管理工具。
    4. 声明式语法为主,通过声明即可完成数据请求、联动、分页等常用操作。
    5. “简单粗暴”一招鲜式的解决方案,降低学习成本。
    6. 对BI系统三大常见操作:级联、过滤、分组-聚合有良好支持 。
    7. 内置支持Vue和React。

    正在开发中的演示项目 demo

    安装:

    npm install naraku@latest --save --registry=https://registry.npmjs.org

    yarn add naraku@latest --registry=https://registry.npmjs.org

    从npm源安装最新版

    引入:

    
    //  DataHub 和 $Transform 是 naraku 的两个核心组件
    import { DataHub,  $Transform } from 'naraku';
    

    DataHub组件

    DataHub是一种Store组件。
    
    主要用途:
    1. 数据级联自动请求数据  
    2. 用于保存全局上下文信息  
    3. 用于组件间的通讯
    

    DataHub设计思想简介

    1. 视图是数据的表现,数据变化则视图变化, 数据变化则触发事件。
    2. 对于选择,可以视为从候选数据集里抽取一个或几个值,放到选中数据集。
    3. 对于级联,可以通过监听父数据中选中值得变化,作出响应,获取数据 ,无论多少级,只需考虑父数据的变化即可。我们可以把这种级联关系视为一种依赖,既子数据依赖于选中的父数据,并且进一步泛化为多个依赖。除了级联关系,还可以通过监听数据变化的方式,自定义数据关系。
    4. 每一种组件体系(VUE、React等)都有自己的组件通信方式和上下文管理,并且往往不止一种方式,增加了学习难度,DataHub本身可作为全局通信总线,因此可以通过DataHub通信和传递上下文,无视各种眼花缭乱的方法。为了便于通信,DataHub支持方法注册,效果等同于组件暴露出的公有方法。

    DataHub和Radux、Rxjs的区别

    1. Radux强调对动作的统一调度,对于DataHub来说,只有一个基本动作:更新数据并触发事件。
    2. Rxjx强调数据的纵向流动管理,DataHub强调数据的横向关系管理。

    DataHub vs. dva vs. vuex

    概念 说明 DataHub dva vuex 技术栈 开源项目
    模型 保存状态和数据的对象 数据集 state对象 state对象 React ant-design-pro
    改变 改变模型的操作,处理业务逻辑 set操作 effects对象下的方法 mutations对象下的方法 Vue vue-element-admin
    还原 对操作结果处理,用于渲染 when回调 reducers对象下的方法 actions对象下的方法 通用 vue-naraku-demo

    三级上下文思想

        Vue和React都有各自的上下文实现,但DataHub可以作为跨技术平台的通用实现,降低学习和开发成本。
        DataHub默认将上下文分为三个级别:应用级、页面级、组件级。
    
    1. 当DataHub组件加载时,会自动创建一个全局实例,作为应用级上下文,可以通过DataHub.dh访问。
    2. 声明页面级组件的时候,可以使用DataHub.inject作为修饰器,当组件实例化之后,创建DataHub实例,生命周期与组件相同(React是在componentWillMount阶段创建,Vue在created阶段创建)。 在组件中通过this.dh访问。同时创建一个Controller,通过this.dhController访问。默认的,也添加了全局dh的引用,并监听变化。可以同过this.gDh访问(gDh表示globalDataHub),同时gDh也创建一个Controller,通过gDhController访问。
    3. 页面级组件可以通过props将自己的DataHub传递到子组件,当子组件得到DataHub实例后,可以通过datahub.bind(this)方法将父组件的datahub绑定。绑定后可以通过this.pDh(表示propsDataHub)访问, 同时会创建一个Controller,通过this.pDhController访问。若有必要,组件也可以使用DataHub.inject创建自己的DataHub实例,与父组件互不冲突。

    Controller的作用

    顾名思义,Controller是一个控制器,有自己的生命周期,其主要作用管理数据和事件的监听的生命周期。当Controller销毁时,自动解除事件和数据的监听。通过inject和bind方法创建的Controller实例,与组件有相同的生命周期,当组件销毁时自动解除监听。(React是componentWillUnmount阶段,Vue是beforeDestroy阶段)

    快速上手--在React中使用DataHub组件:

    import React from 'react';
    import { DataHub } from 'naraku'; 
    
    /*
      示例场景:根据选中的省份,级联获取城市列表
    */
    
    /*==注册数据请求方法,在实际项目中通常是写在独立的文件中===*/
    
    // 获取省份列表API
    DataHub.addFetcher('getProvince', (args)=>{
      const {
        param,  // 这个是请求参数,数据类型是Object
        data, // 这个是提交的数据,数据类型是Array
        form // 是否是表单数据集,数据类型Boolean
     } = args;
    
     // 实际项目中通常是异步请求数据
      return [{name: '辽宁省'},{name: ‘浙江省’}];
    });
    
    // 获取城市列表API
    DataHub.addFetcher('getCity', (args)=>{
      const {
        param,  // 这个是请求参数,数据类型是Object
        data, // 这个是提交的数据,数据类型是Array
        form // 是否是表单数据集,数据类型Boolean
     } = args;
    
    if (param.name === '辽宁省')  {
      return [{name: '沈阳市'},{name: '大连市'}]
    }
    if (param.name === '浙江省')  {
      return [{name: '杭州市'},{name: '宁波市'}]
    }
      return [];
    });
    
    /*====================================*/
    
    
    // 通过DataHub.inject方法将DataHub注入到React组件中 (此方法也支持vue)
    @DataHub.inject({  // 参数是数据配置信息,用来配置数据直接的关系
      // 获取城市列表
      city: {  // city是数据集在DataHub中的名字
         type:  'getCity',  // type是数据请求方法名
         dependence: 'selectedProvince' // 依赖项:选中的省份,只有满足依赖后才会请求数据
      },
      // 获取省份列表
      province: {  // province是数据集在DataHub中的名字
        type:  'getProvince'  
        // 没有依赖项,因此当DataHub组件初始化以后自动请求数据
      },
      myData: { //  没有type,表示是本地数据
        default: [{name: '张三'}]  //  default表示初始化数据
      }
    })
    class NarakuDemo extends React.Component{
    
      componentWillMount() {
        // DataHub注入到React组件中,默认的变量名是dh(DataHub);
        console.log(this.dh);  
        // 同时生成的还有一个与组件生命周期相同的Controller,用于组件和dh的交互,当组件销毁时,Controller所有的方法失效
        console.log(this.dhController);   
        // 读取数据集中的数据
        console.log(this.dhController.get('myData'));   // 数据集中的数据将被统一封装成数组,读取不存在的数据集返回空数组
        // 将数据写入数据集:选中的省份是浙江省,数据作为请求参数 
        this.dhController.set('selectedProvince', {name: '浙江省'}) // 此时满足了依赖条件DataHub请求数据,获取城市列表
       
        // when函数用来监听数据集的数据变化,当数据变化时,触发回调,与事件不同的是如果在监听之前已有数据,将立即返回数据
        this.dhController.when('city',  (data) => {
          console.log(data)
        });
      }
    
     render() {
      // 当数据和数据的状态发生变化时,自动重新渲染
      console.log(this.dh.get('city));  //get等方法可以直接用dh对象调用
      return null;
     }
    
    }
    

    DataHub构造器参数(DataHub.inject参数)

    名称 说明 常见使用场景
    action (旧名称type) Fetcher名称,即DataHub.addFetcher名称,没有则表示是本地数据,旧名称仍然可用 从服务端得到的数据
    dependence 依赖数据集名称,可以是字符串或数组,没有type则无效 级联
    filter 过滤数据集名称,可以是字符串或数组,没有type则无效 查询条件
    pagination 分页,是Boolean或object,没有type则无效 是否分页
    default 数据集的默认值 本地数据
    clear 当对应数据集变化时,清除本数据集 清除选中的值
    reset 当对应数据集变化时,重置本数据集为default,若没有配置default,则清空 重置表单
    snapshot 当对应数据集变化时,做快照保存到本数据集 对结果有进一步操作,并可以回滚

    DataHub数据状态列表

    名称 含义 常见场景
    undefined 未定义,数据集不存在或已删除 初始化时
    loading 数据集加载中 异步获取数据
    locked 数据集锁定 提交等场景,禁止操作数据
    set 数据可使用 读取渲染
    error 数据异常 获取数据出错

    Controller的API

    方法 说明 返回值 常见使用场景 示例
    when 监听数据 function
    on 监听事件 function
    once 一次性监听数据 function
    all 类似when,区别是当参数为数组时只要所有数据更新才会触发回调 function
    fetch 直接获取数据,不写入数据集 promise
    get 读取数据集中的数据,若该数据集不存在,则返回空数组 [] 读取数用于展示的数据列表
    first 读取数据集中的第一条数据,若该数据不存在,则返回空对象 {} 读取全局状态/参数等数据
    refresh 刷新数据集,重新请求数据(如果有type) undefined 提交表单后刷新列表
    submit 提交数据 promise 提交表单
    set 写入数据 undefined 操作数据
    blank 数据是否为空 boolean 展示数据
    locked 数据是否锁定 boolean 操作和展示数据
    assign0 merge第一条数据,数据类型必须是Object undefined 更新参数、状态
    delete 删除数据 undefined
    emit 发射事件 undefined 触发事件
    snapshot 数据快照 undefined 对数据进行操作之前用于还原的数据
    reset 重置数据集 undefined 表单重置
    status 获取/改变数据状态 string
    loading 是否是loading状态 boolean 显示或隐藏加载界面
    ready 是否是ready状态 boolean 初始数据是否可用
    error 是否是error状态 boolean 组件是否可用
    hasRunner 执行者函数是否存在 boolean
    register 注册执行函数 undefined 组件通信,注册通信用函数
    run 执行注册的函数 注册函数的返回值 组件通信,进行通信

    Transformer组件

    Transformer组件用于将数据转变为页面显示需要的格式 ,核心特性是分组聚合运算
    主要用于业务模型到视图模型以及视图模型之间的格式转换,基准数据格式为数组对象

    快速上手--使用Transformer组件:

    import { $Transform } from 'naraku';
    
    // 用$开头的含义是可以像jQuery那样连续调用
    // TODO ...
    

    方法 说明 返回值 常见使用场景 示例
    fromObject 从key-value结构转为对象数组 适配不同组件
    toObject 对象数组转为key-value结构 适配不同组件
    toFields 从对象数组的第一条数据中提取字段名 提取table列名
    operate 自定义操作
    map Array的map操作 同 Array
    filter Array的filter操作 同 Array
    fromModel 复杂模型转为数组对对象数组 model转为view-model,便于展示
    fromMatrix 二维数组转为对象数组 适配不同组件
    toMatrix 对象数组转为二维数组 适配不同组件
    fromTree 树形结构转为自连接关系对象数组 适配树形组件
    toTree 关系型对象数组转为树结构 适配树形组件
    toGrouped 分组聚合 忽略部分维度,将展示的维度聚合
    getData 获得转换后的数据
    getRefs 获得转换过程中生成的反射信息
    output 获得转换后的数据和生成的反射信息

    常用工具

    方法 说明 返回值 常见使用场景 示例
    noValue 判断值是否为null或undefined Boolean 值的非空判断
    blank 空函数 undefined 作为默认回调函数
    blankNull 空函数 null 作为默认回调函数
    same 返回输入参数 any 作为默认回调函数
    snapshot JSON对象快照 object 深克隆数据,避免浅克隆的问题
    localBaseUrl 返回当前URL string 用于请求数据
    paramToQuery 请求参数添加到URL后面 string get请求
    upperCase0 首字母大写 string 拼接单词并采用驼峰命名法
    NumberFormat.percent 小数转为百分比 string 格式化显示百分数
    NumberFormat.thsepar 添加千位分隔符 string 格式化显示长数字

    Install

    npm i naraku

    DownloadsWeekly Downloads

    209

    Version

    0.9.10

    License

    MIT

    Unpacked Size

    240 kB

    Total Files

    29

    Last publish

    Collaborators

    • felixgrey