Awesome

react-native-easy-app （RN开发 一站式解决方案）

English version doc here

安装

npm install react-native-easy-app --save

或者

yarn add react-native-easy-app

功能点

• 支持快捷[同步]访问AsyncStorage
• 支持灵活、可配置的Http请求
• 灵活的基础控件(无感知多屏适配)

快速开始

详细使用方法，请参考示例项目 Sample, Sample_MobX, Sample_Redux, Sample_Hook

您也可以参考文章对react-native-easy-app使用介绍： 简书

• 用AsyncStorage快速实现一个可持久化的数据存、取管理器

     export const RNStorage = {// RNStorage 自定义数据存储对象
         token: null, //  字符串类型
         isShow: null, // 布尔类型
         userInfo: null, // 对象类型
     };
  

    import { XStorage } from 'react-native-easy-app';
    import { AsyncStorage } from 'react-native';
    
    const result = await XStorage.initStorageSync(RNStorage, AsyncStorage);
    if (result) {
        ... // RNStorage 【属性访问代码片段】
    }
    
    // ----------上下，同、异步两种初始化方法 2选1--------------------------
    
    XStorage.initStorage(RNStorage, AsyncStorage, () => {
        ... // RNStorage 【属性访问代码片段】
    });
  

   // RNStorage 【属性访问代码片段】 
   
   // 当自定义对象 RNStorage 被初始化完成之后，就可以对其任何属性进行取值、赋值操作；
   // 对RNStorage 属性的取、赋值操作会被自动映射成 AsyncStorage 的getItem与setItem方法；
               
   console.log(RNStorage.isShow);
   // 相当于 [ console.log(await AsyncStorage.getItem('isShow')) ] 
   
   RNStorage.token = 'TOKEN1343DN23IDD3PJ2DBF3==';
   // 相当于 [ await AsyncStorage.setItem('token',TOKEN1343DN23IDD3PJ2DBF3==') ] 
   
   RNStorage.userInfo = {name: 'rufeng', age: 30};
   // 相当于 [ await AsyncStorage.setItem('userInfo',JSON.stringify({ name:'rufeng', age:30})) ] 
  

  XStorage 对象

  方法	参数	返回值类型	描述
  initStorage	(targetObj, storageImp, initCallback, dataCallback?)	void	将【targetObj】对象中的属性与【AsyncStorage】中的字段建立映射，形成绑定关系
  initStorageSync	(targetObj, storageImp, dataCallback?)	Promise<boolean>	以Promise形式将【targetObj】与【AsyncStorage】建立绑定关系
  multiGet	keys :string[]	Promise<[string, string][]>	等价于 AsyncStorage.multiGet()
  saveItems	keyValuePairs :string[][]	Promise<void>	等价于 AsyncStorage.multiSet()
  removeItems	keys :string[]	Promise<void>	等价于 AsyncStorage.multiRemove()
  clear	none	void	等价于 AsyncStorage.clear()

  XStorage.initStorage 方法参数描述

  参数名	是否必需	形式	描述
  storageObj :object	是	{ token:undefined, userName:undefined, ...}	需要持久化的数据列表对象
  storageImp :AsyncStorage	是	AsyncStorage	数据持久化实现基础(AsyncStorage实例)
  initializedFunc :callback function	是	()=>{ ... }	持久化映射成功成功后的回调
  dataChangedFunc ?:callback function	否	(dataSet)=>{ ... }	持久化数据变更后的回调

  <u>注意：若项目的React Native 版本高于0.60，storageImp的参数，建议使用 '@react-native-community/async-storage'中的【AsyncStorage】实例</u>

• 支持可配置的Http请求

  • 一切基于配置（配置可选，自由设定）

  import { XHttpConfig, XHttpConst } from 'react-native-easy-app';
  
  XHttpConfig().initLogOn(true)
               .initBaseUrl('https://www.baidu.com')
               .initTimeout(15000)
               .initContentType(XHttpConst.CONTENT_TYPE_URLENCODED)
               .initLoadingFunc((isLoading)=>{
                  ...
               })
               .initHeaderSetFunc((headers, request) => {
                  ...
               })
               .initParamSetFunc((params, request) => {
                  ...
               })
               .initParseDataFunc((result, request, callback) => {
                  let {success, json, response, message, status} = result;
                  ...
                }
           );
  

  XHttpConfig 对象 （所有方法都是可选的）

  方法	参数	返回类型	描述
  constructor	serverTag ?:string	XHttpConfig Builder	与XHttp(serverTag)保持一致(用于多服务器请求配置)，默认为空
  initBaseUrl	baseUrl :string	XHttpConfig Builder	设置Http请求公共的BaseUrl
  initTimeout	timeout :number	XHttpConfig Builder	设置公共的默认请求超时时间
  initLogOn	logOn :bool	XHttpConfig Builder	设置是否打印Http请求日志
  initContentType	contentType :string	XHttpConfig Builder	设置Http请求默认的ContentType
  initLoadingFunc	(isLoading) => {...}	XHttpConfig Builder	Http公共请求状态回调，isLoading为true表示请求进行中
  initHeaderSetFunc	(headers, request) => {...}	XHttpConfig Builder	请求header设置拦截器；可在此处，为请求添加公共的headers参数
  initParamSetFunc	(params, request) => {...}	HttpRequest Builder	请求body(params)设置拦截器；可在此处，为请求添加公共的params参数
  initParseDataFunc	(result, request, callback) => {...}	XHttpConfig Builder	请求回调拦截器；可在此处，为接口返回数据做公共解析处理
  initEncodeURIComponent	encodeComponent :boolean	HttpRequest Builder	全局设置是否对参数进行encodeURLComponent编码，内容类型为：application/x-www-form-urlencoded 时
  initNetworkExceptionFunc	(NetInfo,(message, code) => {...})	HttpRequest Builder	给请求库提供检查当前网络状态的工具库(@react-native-community/netinfo的实例对象) [require => android.permission.CHANGE_NETWORK_STATE]

• 发送请求模板

     import { XHttp } from 'react-native-easy-app';
  
     let url = 'v1/account/login/';
     let param = { phone: '18600000000', authCode: '123456'};
     let header = { Authorization: "Basic Y3Rlcm1pbmF......HcVp0WGtI"};
     let callback = () => (success, json, message, status, respoonse) => {
          if (success) {
             showToast(JSON.stringify(json))
          } else {
             showToast(message)
          }
     };
  
     * 可设置的参数以builder形式拼接
     XHttp().url(url)
         .header(header)
         .param(param)
         .internal(true)
         .rawData()
         .pureText()
         .timeout(10000)
         .extra({tag: 'xx'})
         .contentType('text/xml')
         .loadingFunc((loading)=> showLoading('请求中，请稍候...', loading))
         .configCommonFunc(true,true)
         .[formJson|formData|formEncoded]()
         .[get|post|put|patch|delete|options](callback);
    
  

  HttpRequest 对象

  方法	参数	返回类型	描述
  constructor	serverTag :string	HttpRequest Builder	与XHttpConfig(serverTag)保持一致(用于多服务器请求配置)，默认为空
  url	url :string	HttpRequest Builder	设置请求的url；若XHttpConfig中配置了baseUrl，当前只需要配置接口url后缀即可
  header	{ Accept, Authorization ... } :object	HttpRequest Builder	设置当前请求的header参数；若与XHttpConfig中配置的公共header参数同名，则以当前设置为准
  param	{ userName, password ... } 或 FormData :object	HttpRequest Builder	设置当前请求的params参数(可以传FormData对象)；若与XHttpConfig中配置的公共params参数同名，则以当前设置为准
  paramRaw	{ userName, password ... } 或 FormData :object	HttpRequest Builder	设置当前请求的paramsRaw参数, 当前传入的参数不会做任何处理，直接作为fetch请求的的body
  contentType	contentType :string	HttpRequest Builder	设置当前请求的ContentType；若XHttpConfig中设置公共的ContentType，则以当前设置为准
  internal	internal :bool	HttpRequest Builder	用于请求区别标记，默认为true；通常在XHttp中传入，在XHttpConfig的回调拦截器中使用，拦截器的request中可取该值
  extra	{customTag ...}	HttpRequest Builder	用于请求区别标记，通常在XHttp中传入，在XHttpConfig的回调拦截器中使用，拦截器的request中可取该值
  timeout	timeout :number	HttpRequest Builder	设置当前请求的超时时长，单位毫秒
  loadingFunc	(isLoading)=>{ ... }	HttpRequest Builder	当前接口请求状态回调；isLoading为true表示请求进行中
  configCommonFunc	( enableHeaderFunc :bool, enableParamFunc :bool )	HttpRequest Builder	设置在XHttpConfig添加的**[initHeaderSetFunc] [initParamSetFunc]**是否生效，默认为true（生效）
  rawData	none	HttpRequest Builder	设置返回的接口数据是否为原始未处理过的数据；若调用，则会忽略XHttpConfig中设置**[initParseDataFunc]**函数作用
  pureText	none	HttpRequest Builder	设置返回的接口数据是否为纯文本数据（框架默认为接口为json数据，若后台返回的数据为非json结构时间使用：如 XML 格式
  formJson	none	HttpRequest Builder	等价于设置当前接口请求类型 ( headers['Content-Type'] = 'application/json' )
  formData	none	HttpRequest Builder	等价于设置当前接口请求类型 ( headers['Content-Type'] = 'multipart/form-data' )
  formEncoded	none	HttpRequest Builder	等价于设置当前接口请求类型 ( headers['Content-Type'] = 'application/x-www-form-urlencoded' )
  get	(success, json, message, status ,response) => void	void	get 请求及回调
  post	(success, json, message, status ,response) => void	void	post 请求及回调
  options	(success, json, message, status ,response) => void	void	options 请求及回调
  put	(success, json, message, status ,response) => void	void	put 请求及回调
  delete	(success, json, message, status ,response) => void	void	delete 请求及回调
  patch	(success, json, message, status ,response) => void	void	patch 请求及回调
  request	(method, (success, json, message, status ,response) => void )	void	以指定的请求method，发送请求并回调
  execute	method :string	Promise	以指定的请求method，发送请求并返回一个Promise对象
  fetch	method :string	Promise	以指定的请求method，发送请求并返回一个Promise对象，返回的数据不做任何处理，以RN原生fetch的方式结果原样返回

  new HttpRequest() ==> XHttp()

  推荐通过 XHttp() 的形式来发送Http请求会更便捷

• 发送请求

  • 同步请求

     import { XHttp } from 'react-native-easy-app';
     
     const url = 'https://www.google.com';
    
     const result = await XHttp().url(url).execute('GET');
     const {success, json, message, status, response} = result;
     
     if(success){
        this.setState({content: JSON.stringify(json)})
     } else {
        showToast(message)
     }
  

  • 异步请求 方式1

     XHttp().url(url).get((success, json, message, status, response)=>{
         if (success){
            this.setState({content: JSON.stringify(json)});
         } else {
            showToast(msg);
         }
     });
  

  • 异步请求 方式2

     XHttp().url(url).execute('GET').then(({success, json, message, status, response}) => {
         if (success) {
              this.setState({content: JSON.stringify(json)});
         } else {
              showToast(message);
         }
      })
  

  • 灵活的基础控件

     XImage
     XText
     XView
     
     XFlatList
     
     XWidget
     .initResource(AssetsBaseUrl)    // XImage组件的icon属性的uri前缀
     .initReferenceScreen(375, 677); // UI 整体尺寸缩放参考屏幕尺寸
  

  XView，XImage，XText都包含raw属性，若raw值为true，则会忽略XWidget.initReferenceScreen( referenceWidth, referenceHeight )的设置：不自动处理多屏尺寸适配

  XView 组件

  属性	类型	描述
  raw	bool	默认为false，若为true 则不会自动处理多屏幕尺寸适配
  ...	...	若包含onPress或onLongPress属性，则等同于TouchableXXX系列组件,否则等同于View组件,并拥有其相应的属性

  XImage Object

  属性	类型	描述
  raw	bool	默认为false，若为true 则不会自动处理多屏幕尺寸适配
  icon	string	相当于Image的source属性，可以接受的参数格式如：[https://xxx.yy.com/image.jpg]，[data: image / png; base64, iVBORw0KGgoAAAAN ...]，[require ('./ image.jpg')]
  iconSize	number	图标的尺寸，优先级高于style的width与height
  ...	...	如果设置了onPress和onLongPress函数，XImage将被XView包裹，并且外部传入的属性将会自动被分配给正确的控件

  XText 组件

  属性	类型	描述
  raw	bool	默认为false，若为true 则不会自动处理多屏幕尺寸适配
  text	string	文本
  textExtend	bool	如果包含图标，则等效于将Text组件设置属性: {flex:1}
  icon	string	相当于Image的source属性，可以接受的参数格式如：[https://xxx.yy.com/image.jpg]，[data: image / png; base64, iVBORw0KGgoAAAAN ...]，[require ('./ image.jpg')]
  iconSize	number	图标尺寸
  iconStyle	number	图标Image的样式
  resizeMode	string	图标Image的resizeMode
  iconMargin	number	图标与文本之间的距离
  iconPosition	string	图标在当前控件中的位置，可以设置的值有： 'top', 'right', 'bottom', 'left'
  ...	...	如果设置了onPress和onLongPress函数，XImage将被XView包裹，并且外部传入的属性将会自动被分配给正确的控件

  XFlatList 组件

  属性	类型	描述
  data	array	相当于FlatList组件的data属性
  refreshStatus	object	XFlatList列表在不同刷新状态展示的UI样式及文本设置对象
  indicatorProps	object	设置下拉刷新控件RefreshControl的样式及属性
  onRefresh	() => {...}	相当于FlatList控件的onRefresh属性
  onLoadMore	() => {...}	当列表滚动到底部，被执行的回调方法（需要加载更多数据时）
  renderEmptyViewFunc	(status, isEmpty) => {...}	自定义各种状态下的EmptyView的实现
  renderFooterViewFunc	(status, isEmpty) => {...}	自定义各种状态下的FooterView的实现
  ...	...	FlatList组件的所有剩余属性

  FlatList 组件刷新状对象示例

   const RefreshStatus = {
     Idle: {}, //闲置状态
   
     RefreshingData: { text: '加载中，请稍候...'}, //下拉刷新中..
     NoData: { text: '加载完成，无数据'}, //下拉刷新（无数据）
     LoadFailure: { text: '加载失败'}, //下拉刷新（加载失败）
   
     LoadingMoreData: {moreText: '数据加载中…'}, //加载更多,进行中...
     NoMoreData: {moreText: '已加载全部数据'}, //加载更多（无数据）
     LoadMoreFailure: {moreText: '点击重新加载'}, //加载更多（加载失败）
     
     NetException: {text: '网络异常', moreText: '网络异常，点击重试'}, // 网络异常
   }
  

详细使用方法，请参考示例项目 Sample, Sample_MobX, Sample_Redux, Sample_Hook

您也可以参考文章对react-native-easy-app使用介绍： 简书

版本日志

• 1.7.0 XStorage的初始参数storageImp(AsyncStorage实例)设定为必需参数，并移除了版本号。
• 1.7.4 设置XHttpConfig默认超时时间为15秒；更新readme文件，增加XStorage同步初始化代码片断。
• 1.7.5 移除特定请求的参数urlEncoded处理，只支持全局编码或者不编码；修复非formEncoded类型下的编码处理。
• 1.7.6 设置XHttpConfig默认contentType为application/x-www-form-urlencoded；设置XText默认的图标处于文本的顶部。
• 1.7.7 XText增加iconStyle，resizeMode属性;XHttp普通参数增加支持传入FormData，原参数paramRaw支持不做处理直接发送请求。
• 1.7.8 修复XImage在有点击事件的时候，不支持tintColor样式的bug。
• 1.7.9 XFlatList增加ref属性：ref => this.flatList = ref，以便XFlatList能支持FlatList所拥有的相关方法，使用方式如：this.refreshList.flatList.scrollToOffset({...})
• 1.7.12 当请求成功后，及时清除无意义的超时计时器，减少不必要的计时器资源的浪费。
• 1.7.13 XFlatList增加属性renderFooter、indicatorProps以便更灵活的控制其样式及属性
• 1.7.16 XFlatList增加属性indicatorProps、renderEmptyViewFunc、renderFooterViewFunc等属性，可以自定义indicator、各种状态下的emptyView以及FooterView的布局实现
• 1.7.17 XFlatList增加属性renderPreEmptyViewFunc，用于列表未做任何数据加载时的EmptyView的布局自定义实现
• 1.7.18 HttpConfig增加initNetworkExceptionFunc方法，通过用户指定的@react-native-community/netinfo实例对象，在请求时根据当前网络状态做相应的回调处理
• 1.7.19 XFlatList合并renderPreEmptyViewFunc到renderEmptyViewFunc方法中，移除XText对allowFontScaling的默认支持
• 1.7.20 修复屏幕适配方法validReferSize判断条件错误的bug
• 1.7.23 移除了XStorage从持久化中读取数据到内存时的不必要的数据类型转换实现
• 1.7.25 兼容XStorage数据存储不能有效处理undefined类型数据的bug（在IOS上会报异常）
• 1.7.26 重命名XHttpConfig方法initHttpLogOn为initLogOn、重命名XFlatList方法renderRooterViewFunc为renderFooterViewFunc、修正readme文档描述