HY-UI

使用

使用前，我希望你对虎牙小程序开发流程有所了解。

初始化项目

安装hyext脚手架

$ npm i @hyext/cli -g

然后初始化项目

$ hyext init <project-name>

开发

基于react技术栈

js

开发者可以使用react开发小程序,虎牙小程序技术栈跨终端的实现方式：app端基于react-native，web端基于react-native-web，开发者只需要开发维护一套代码，小程序就可以在app端和web端运行，但是要兼容两端的差异，所以会受到以下约束。

不能引入带有原生模块的react-native第三方库。
可以引入纯js的react-native第三方库，但是需要在builder.config.compileNodeModules（Builder配置项中介绍）加上你的包名。
建议使用hy-ui组件开发小程序，如果你发现还需要react-native的其他模块，你也可以引入，但前提是react-native-web也实现了该模块。

hycss

hycss会受到rn端的约束，这些属性css版本是可用的,但其之外的css是不能用的，另外建议开发者使用flex进行布局，rn端完美兼容flex，开发者无需关心适配屏幕的问题，builder已经帮你们处理这些问题，开发者只需关心设计稿（宽度为750px）的尺寸去写样式就ok啦。

SDK使用

builder已经抹平了web和app的SDK差异，直接访问global.hyExt即可。

栗子

app.js文件

import React, { Component } from 'react';
import { Text, View } from '@hyext/hy-ui';
import 'app.hycss'

export default class App extends Component {
   render() {
       return (
           <View className={"hello_world_wrapper"}>
               <Text className={"hello_world"}>Hello World!</Text>
           </View>
       )
   }
}

app.hycss文件

.hello_world_wrapper {
  width: 300px;
  height: 300px;
}

.hello_world {
  font-size: 60px;
}

/* 如果不想样式单位自适应 去掉px即可 */
 .hello_world {
  font-size: 60;
}

Lint

为了尽可能规避代码层面上的各种问题，我们提供了一套lint配置, 可以帮助开发者减少bugs和消除开发中遇到的疑惑。

开启方式

project.config.json文件下

{
 "builder": {
  "config": {
    "enableLint": {
      "eslint": true, // true, 开启js的语法检查
      "stylelint": true// true, 开启css样式检查
    },
  }
}

Eslint

eslint提供js层面上得语法检查，包含eslint最基本的语法检查和虎牙小程序提供的语法检查。

Stylelint

stylelint提供样式层面上得语法检查，包含hycss和js所用到的css样式的语法检查。

构建器如何提供帮助？

构建器（builder-beyond）会根据你的enableLint配置做如下操作：

第一步，产出对应lint平台的最基本的配置文件（假如之前没有任何的lint配置文件），配置了eslint，会生成.eslintrc、.eslintignore文件，配置了stylelint，会生成.stylelintignore、.stylelint文件。

// .eslintrc内容
{
  "parser": "babel-eslint",
  "plugins": [
    "hyext-builder-beyond"
  ],
  "extends": [
    "plugin:hyext-builder-beyond/all"
  ],
  "env": {
    "browser": true,
    "es6": true
  }
}

// .eslintignore内容
node_modules

// .stylelint内容
{
  "extends": [
    "stylelint-config-hyext"
  ],
  "rules": {}
}

// .stylelintignore内容
node_modules

第二步，往package.json中的scripts注入对应lint的执行脚本(如果发现有同名的脚本命令，则不会被修改)，这样lint的语法检查就可以摆脱构建器的束缚，单独执行，如果你想构建器不需要语法检查，在配置中设对应项为false即可。

// package.json
{
  "scripts": {
    "stylelint": "stylelint '**/*.hycss'",
    "eslint": "eslint --ext .js ."
  },
}

// project.config.json 可停止构建时检查
{
 "builder": {
  "config": {
    "enableLint": {
      "eslint": false, 
      "stylelint": false
    },
  }
}

第三步，安装lint相关的依赖包。

扩展

如果你觉得构建器提供的基础配置无法满足你的需求，你可以添加额外的lint插件；

如果你不想用基础配置中的某一条rule, 可以在相应的配置文件中禁用该规则；

以上配置可查看eslint、stylelint的官方文档指导。

IDE插件辅助

eslint和stylelint在主流的IDE（Vscode, WebStorm等）中都有相应的插件可供开发者使用（十分好用）。

Debug

Web端

请先装react-developer-tools, 以下是调试方法，我们用图片解释。

1. 打开Chrome开发者工具，点击Elements选项，选取你要调试的节点, 你会看到编译出来的节点难以阅读，别担心，看下一步。

2. 点击Components选项, 查看节点对应的Component。

App端

直接用react-native自带的开发者工具debug

Builder配置项-位于project.config.json文件下

Name	Type	Required	Default	Description
webSDKVersion	string	false	'1.4.0'	web端SDK版本号
webTitle	string	false	'虎牙小程序'	PC主播端小程序标题
designWidth	number	false	750	设计稿宽度，默认750px（不建议修改）
buildConfig	object	false	在Entry List中介绍	构建配置，告诉平台，你的小程序可运行在哪个端
useCssLoader	boolean	true	false	使用hycss
https	boolean	false	true	本地开发是否开启https
host	boolean	false	'localhost'	本地开发的域名
compileNodeModules	array	false	undefined	需要web构建器编译的npm包名队列, 例如：['react-native-smart-tip']
enableLint	object	false	void	开启eslint语法检测，前面Lint部分有说
enableVW	boolean	false	false	开启样式转换，px转vw

Entry List

Web Entry

Name	ExtType	Platform	Entry	Runtime
web观众端	web_video_com	web	index.js	H5
pc主播端	pc_anchor_panel	pc	index_streamer.js	H5

App Entry

Name	ExtType	Platform	Entry	Runtime
app观众端	app_panel	app	index.js	React Native
主播端-助手app	zs_anchor_panel	app	index_streamer.js	React Native

// builder内置的entry
const DEFAULT_BUILD_CONFIG = {
  H5: [
     // web观众端
     {
      entry: 'index.js',
      extType: 'web_video_com',
      platform: 'web'
    }, 
  ],
  RN: [
    // app观众端
    {
      entry: 'index.js',
      extType: 'app_panel',
      platform: 'app'
    }
  ]
} 

// 想构建那个端的小程序都可以通过自定义entrys去实现，例如以下例子
{
  "builder": {
    "config": {
      "webSDKVersion": "1.1.0", 
      "webTitle": "example", 
      "useCssLoader": true,
      "buildConfig":{
        "H5": [
          {
            "entry": "index.js",
            "extType": "web_video_com",
            "platform": "web"
          }
        ],
        "RN": [
          {
            "entry": "index.js",
            "extType": "app_panel",
            "platform": "app"
          },
          // 新增一个主播助手App端入口
          {
            "entry": "index_streamer.js",
            "extType": "zs_anchor_panel",
            "platform": "app"
          }
        ]
      } 
    },
    "name": "@hyext/builder-beyond"
  }
}

全局变量

直接通过global对象访问

Name	Type	Description
global.__device	object	设备信息 { width: number(屏幕宽度), height: number(屏幕高度) }
global.__os	string	操作系统名称，共三种类型：'web'、'ios'、'android'

疑问

在App端，页面不能滚动，解决方案如下

// app.js
render() {
  return (
    <View className="container">
     <ScrollView className="scroller">
       你的页面
     </ScrollView>
   </View>
  )
}

/*
* app.hycss
*/
.container {
 position: absolute;
 top: 0;
 bottom: 0;
 left: 0;
 right: 0;
}

.scroller {
 flex: 1;
}

优缺点

优点

抹平平台间的差异，一套代码可运行多端，开发效率、可维护性都大大提高
hy-ui提供丰富可定制可扩展的组件，为你提供强大的业务支撑，加快开发效率

缺点

开发受限于react-navie的规范约束，没有纯web开发那么灵活

使用