@quicktvui/ai 1.0.0

package/rules/.docs/zh-CN/sample/hello-tv.md

@@ -0,0 +1,98 @@
+
+# HelloTV
+
+HelloTV是基于 [QuickTVUI](http://quicktvui.com/) 框架的视频点播直播应用，面向使用遥控器交互的安卓大屏设备。
+项目目的是让开发者通过对本项目源码的简单修改，快速实现一些TV端常见的功能页面，从而加速开发进度。如果使用者并不具备编程能力，可以参考[HelloTV-Case](https://github.com/quicktvui/HelloTV-Case)项目，简单修改该项目配置文件就可以快速实现一个标准化的视频类应用。
+点播页面包括瀑布流首页、内容列表、筛选、搜索、详情、历史、收藏、登录等，直播页面包括多级列表页、播放详情页等。
+以下是一些页面效果：
+
+***瀑布流首页***
+
+<img width="95%" src="https://extcdn.hsrc.tv/data_center/files/2024/07/10/9a62dd70-e787-4d5f-8294-d2acd79c23bf.jpeg"/>
+
+***搜索***
+
+<img width="95%" src="https://extcdn.hsrc.tv/data_center/files/2024/07/10/9204f370-3230-4f56-b7df-c4da1283fd89.jpeg"/>
+
+***筛选***
+
+<img width="95%" src="https://extcdn.hsrc.tv/data_center/files/2024/07/10/3c860f27-cefe-47a9-b3ea-c9bbe761e2e2.jpeg"/>
+
+***详情页***
+
+<img width="95%" src="https://extcdn.hsrc.tv/data_center/files/2024/07/10/c2c6d9e0-ca8a-4ff1-a5ce-e639395ad33f.jpeg"/>
+
+***内容编辑页***
+
+<img width="95%" src="https://extcdn.hsrc.tv/data_center/files/2024/07/10/fc811902-d468-4828-b030-0f7561c1816b.jpeg"/>
+
+## 快速开始
+
+### 调试
+#### 1. 确认编译环境
+建议windows:
+- node version 16.20.2
+- npm version 8.10
+
+
+#### 2. 安装运行Runtime
+下载并安装 [运行环境](/zh-CN/runtime/runtime) (需要日志时使用debug包，否则使用release)
+
+#### 3. 安装依赖
+进入项目录下
+```bash
+npm install --legacy-peer-deps
+```
+#### 4. 编译调试
+```bash
+npm run dev
+```
+#### 5. 打开运行Runtime apk，查看效果
+
+点击下图加载测试代码
+
+<img width="95%" src="/guide/basic/debug_runtime_ok.jpg"/>
+
+
+::: warning 注意：这里电脑调试地址要改成你电脑本机ip
+:::
+
+```bash
+adb shell am broadcast -a  com.extscreen.runtime.ACTION_CHANGE_DEBUG_SERVER --es ip 192.168.xx.xx(电脑IP地址)
+```
+关于adb等其它配置具体说明请查看 <u>[安装和环境配置](/zh-CN/guide/basic/installation) </u>
+
+
+最后看到加载出页面，表示完成调试，即可随时修改源码查看效果。
+
+
+#### 6. 打包生成APK
+
+[APK配置](https://github.com/quicktvui/hellotv/blob/master/android/README.md)
+
+``` bash
+# 生成debug包
+npm run build-apk-debug
+# 生成release包
+npm run build-apk-release
+```
+打包完成后apk在 `./android/app/build/outputs/apk/` 文件夹下
+
+
+
+## 开发进度
+- [x] 瀑布流首页
+- [x] 搜索页
+- [x] 媒资详情页
+- [x] 筛选页
+- [x] 多级列表页
+- [x] 一键打包生成APK
+
+以上页面开发完成
+
+开发中
+- [ ] 内容编辑页
+- [ ] 短视频浏览
+
+## 其他
+更多信息请查看[源码](https://github.com/quicktvui/hellotv)

package/rules/.docs/zh-CN/sdk/cus_component.md

@@ -0,0 +1,249 @@
+## Component是什么？
+
+Component是为sdk提供扩展显示组件的模块，例如播放器等。 如果SDK默认提供的组件无法满足需求，可以通过自定义的方式实现自己的功能，例如自己的UI组件。
+
+## 如何自定义？
+
+自定义功能需要注意一下几点：
+
+* Component实现IEsComponent接口
+* View实现IEsComponentView接口
+* 方法必须是public方法，且同一个Component中不允许同名方法
+* 方法的第一个参数必须是自定义的View本身
+* 属性方法必须使用EsComponentAttribute的注解
+* 注解可设置index来决定属性设置的优先级，值越小，优先级越高，取值范围0~100，默认值100
+* 参数支持类型：
+* 基本数据类型：`int`, `String`, `boolean`
+* 数组类型：`EsMap`, `EsArray`
+* 回调类型：`EsPromise`
+
+### Android端代码:
+
+::: details 点击查看源码
+
+``` java
+// 创建View // 实现IEsComponentView接口
+public final class VideoPlayerView extends FrameLayout implements IEsComponentView {
+    public VideoPlayerView(Context context) {
+        super(context);
+    }
+}
+
+//将View与Component关联 实现IEsComponent接口
+public class MyVideoComponent implements IEsComponent<VideoComponent.VideoPlayerView> {
+    @Override
+    public VideoPlayerView createView(Context context) {
+        return new VideoPlayerView(context);
+    }
+    // 对应vue标签的属性 <video-player ref="video" :autoPlay=false />
+    @EsComponentAttribute(index = 0) // 如果各属性之间存在顺序执行问题，可指定属性调用顺序
+    public void autoPlay(VideoPlayerView view, boolean auto){
+        view.autoPlay(auto);
+    }
+    // 对应vue标签的属性  <video-player ref="video" :src=videoUrl />
+    @EsComponentAttribute
+    public void src(VideoPlayerView view, String url) {
+        view.setUrl(url);
+    }
+
+    // 对应vue标签的方法 this.$refs.video.pause()
+    @Override
+    public void dispatchFunction(VideoPlayerView view, String eventName, EsArray params, @Nullable EsPromise promise) {
+        switch (eventName){
+            case "play":
+                String url = params.getString("url");
+                break;
+            case "pause":
+                break;
+            case "getPosition": // 获取播放进度
+                if(promise != null) {
+                    promise.resolve(view.getCurrentPlayPositioin());
+                }
+                break;
+        }
+    }
+
+    // 对应vue标签的回调  <video-player @player-status-changed="onPlayerStatusChanged" />
+    @Override
+    public void onPlayerStatusChanged(int playerStatus) throws RemoteException {
+         EsMap esMap = new EsMap();
+         esMap.pushInt("playerStatus", playerStatus);
+         //sendUIEvent方法：向UI控件发送事件
+         EsProxy.get().sendUIEvent(view.getId(), "onPlayerStatusChanged", esMap);
+    }
+
+    @Override
+    public void destroy(VideoView view) {
+    }
+}
+```
+
+:::
+
+## 注册
+
+### 1. SDK注册方式
+
+``` java
+InitConfig initConfig = InitConfig.getDefault();
+initConfig.setAppId("注册的APPID")
+   .setSdkInitCallback(new EsKitInitCallback() { //使用EsKitInitCallback监听 注册你需要的自定义模块
+       @Override
+       public void onEsKitInitSuccess() {
+           // 注册到SDK
+           EsManager.get().registerComponent(MyVideoComponent.class.getName());
+       }
+   });
+```
+
+### 2. Vue注册方式
+
+::: details vue3注册方式
+
+```text
+//vue3注册方式
+
+/**
+ * 播放器view
+ */
+function registerMyVideoPlayerViewComponent(app: ESApp) {
+
+  const videoViewComponent = {
+    component: {
+      name: 'MyVideoComponent',
+      processEventData(evtData, nativeEventParams: {
+        position: number
+      }) {
+        const {handler: event, __evt: nativeEventName} = evtData;
+        switch (nativeEventName) {
+          //------------------播放进度回调-----------------------
+          case 'onPlayerPositionChanged':
+            event.position = nativeEventParams.position;
+            break;
+          default:
+        }
+        return event;
+      },
+    },
+  }
+  registerElement('MyVideoComponent', videoViewComponent);
+
+  //
+  const VideoViewImpl = defineComponent({
+    emits: [
+      'player-position-changed',
+      //需要自己添加 名字自拟
+    ],
+    setup(props, context) {
+      const videoPlayerViewComponentRef = ref()
+
+      const start = (progress: number): void => {
+        console.log('-------ESVideoPlayerViewComponent--------start-------->>>>')
+        Native.callUIFunction(videoPlayerViewComponentRef.value, 'start', [progress], (res) => {
+          //console.log('res-------->>>>' , res)
+        });
+      }
+      const seekTo = (progress: number): void => {
+        Native.callUIFunction(videoPlayerViewComponentRef.value, 'seekTo', [progress], (res) => {
+          //console.log('res-------->>>>' , res)
+        });
+      }
+      const pause = (): void => {
+        console.log('-------ESVideoPlayerViewComponent--------pause-------->>>>')
+        Native.callUIFunction(videoPlayerViewComponentRef.value, 'pause', (res) => {
+          //console.log('res-------->>>>' , res)
+        });
+      }
+      const getCurrentPosition = (): void => {
+        Native.callUIFunction(videoPlayerViewComponentRef.value, 'getCurrentPosition',
+          (res) => {
+            //console.log('res-------->>>>' , res)
+          });
+      }
+      const getDuration = (): void => {
+        Native.callUIFunction(videoPlayerViewComponentRef.value, 'getDuration',
+          (res) => {
+            //console.log('res-------->>>>' , res)
+          });
+      }
+
+      return () => {
+        return h(
+          'MyVideoComponent', {
+            ref: videoPlayerViewComponentRef,
+            onPlayerPositionChanged: (evt) => {
+              context.emit('player-status-changed', evt.position);
+            },
+          },
+        )
+      }
+    },
+  })
+  app.component('VideoPlayer', VideoViewImpl);
+}
+
+```
+
+:::
+
+::: details Vue2注册方式
+
+```text
+  //vu2注册方式
+function ESAndroidPlayerViewComponent() {
+  Vue.registerElement('MyVideoComponent', {
+    component: {
+        name: 'MyVideoComponent',
+    }
+  }),
+  Vue.component('VideoPlayer', {
+    methods: {
+        pause(){
+            Vue.Native.callUIFunction(this.$refs.player, 'pause', [], (res) => {
+              console.log('res', res)
+            });
+        },
+        seekTo(position){
+            Vue.Native.callUIFunction(this.$refs.player, 'seekTo', [position], (res) => {
+                console.log('res', res)
+            });
+        },
+        getCurrentPositoin(callback){
+            Vue.Native.callUIFunction(this.$refs.player, 'getCurrentPosition', [],
+          (res) => {
+            callback(res)
+          });
+        },
+    }
+  })
+}
+
+```
+
+:::
+
+## Vue调用
+
+::: details 点击查看源码
+
+```vue
+<video-player
+  ref="video"
+  class="video"
+  :autoPlay="false"
+  :src='videoUrl'
+  @player-status-changed='onPlayerStatusChanged'
+/>
+```
+
+```text
+function onPlayerStatusChanged(e) {
+   const playerStatus = e.playerStatus;
+   console.log(`接收到的播放状态:${  playerStatus}`);
+}
+
+this.$refs.video.seekTo(1000)
+this.$refs.video.pause()
+```
+
+:::

package/rules/.docs/zh-CN/sdk/cus_module.md

@@ -0,0 +1,163 @@
+## Moudle是什么？
+
+Module是基于快应用基础架构扩展出来的自定义模块，是为sdk提供扩展功能的模块，例如下载功能、Toast等。
+
+如果SDK默认提供的功能无法满足需求，可以通过自定义的方式实现自己的功能，例如自己的加密算法、支付模块等。
+
+## 如何自定义？
+
+自定义功能需要注意一下几点：
+
+* Module实现IEsModule接口
+
+* 方法必须是public方法，且同一个Module中不允许同名方法
+
+* 参数支持类型：
+
+* 基本数据类型：`int`, `String`, `boolean`
+
+* 数组类型：`EsMap`, `EsArray`
+
+* 回调类型：`EsPromise`
+
+### Android端代码:
+
+::: details 点击查看源码
+
+``` java
+// 实现IEsModule接口
+public class MyModule implements IEsModule {
+
+    @Override
+    public void init(Context context) {
+
+    }
+
+    // 显示Toast
+    public void showToast(String message) {
+        //ToastUtils.showToastShort(msg);
+        Toast.makeText(mContext, message, Toast.LENGTH_SHORT).show();
+    }
+
+    // ❌ 错误！！！同一个Module中不允许同名方法
+    // 会导致vue调用不成功
+    public void showToast() {}
+
+    // 检测应用是否安装 带promise的回调方式
+    public void isAppInstall(String packageName, EsPromise promise) {
+        try {
+            PackageInfo info = mContext.getPackageManager().getPackageInfo(packageName, 0);
+            if(info != null) {
+                PromiseHolder.create(promise).singleData(true).sendSuccess();
+                return;
+            }
+        } catch (Exception e) {
+        }
+        PromiseHolder.create(promise).singleData(false).sendSuccess();//用内部提供个的工具直接发送
+        //或者通过EsMap调用发送 promise必须要返回 否则vue层会有阻塞
+        EsMap map = new EsMap();
+        map.pushInt(key,value)
+        map.pushString(key,value)
+        try {
+            promise.resolve(map);
+        } catch (Throwable e) {
+            promise.reject("程序异常");
+            e.printStackTrace();
+        }
+    }
+
+    @Override
+    public void destroy() {
+
+    }
+
+    @Override
+    public void destroy() {
+
+    }
+}
+
+// 向指定的IEsComponent或者IEsModule发送事件(全局事件)
+private void sendNativeEvent() {
+    EsMap esMap = new EsMap();
+    esMap.pushInt("status", 1);
+    EsProxy.get().sendNativeEventTraceable(this, "onStatusChanged", esMap);
+}
+```
+
+:::
+
+## 注册
+
+``` java
+InitConfig initConfig = InitConfig.getDefault();
+initConfig.setAppId("注册的APPID")
+   .setSdkInitCallback(new EsKitInitCallback() { //使用EsKitInitCallback监听 注册你需要的自定义模块
+       @Override
+       public void onEsKitInitSuccess() {
+           // 注册到SDK
+           EsManager.get().registerModule(MyModule.class.getName());
+       }
+   });
+```
+
+## Vue调用
+
+::: details Vue3
+
+```text
+import { Native } from "@extscreen/es3-vue";
+// 参数1: module名称  参数2: 方法名称  参数3: 方法参数
+Native.callNative('MyModule', 'showToast', "hello");
+
+// 调用需要返回值的方法
+Native.callNativeWithPromise('MyModule', 'isAppInstall', 'com.extscreen.runtime')
+  .then((isInstall) => {
+    console.log('isAppInstall', isInstall)
+  });
+
+// vue层接收回调信息
+import { EventBus } from "@extscreen/es3-vue";
+
+//注册：
+EventBus.$on('onStatusChanged', this.onStatusChanged);
+
+//取消注册：
+EventBus.$off('onStatusChanged', this.onStatusChanged);
+
+//处理回调
+function onStatusChanged(e) {
+  const status = e.status;
+  console.log(`接收到的状态码:${status}`);
+}
+```
+
+:::
+
+::: details Vue2
+
+```text
+// 参数1: module名称  参数2: 方法名称  参数3: 方法参数
+Vue.Native.callNative('MyModule', 'showToast', "hello");
+
+// 调用需要返回值的方法
+Vue.Native.callNativeWithPromise('MyModule', 'isAppInstall', 'com.extscreen.runtime')
+    .then((isInstall)=>{
+        console.log('isAppInstall', isInstall)
+    });
+
+// vue层接收回调信息
+//注册：
+ESApp.$on('onStatusChanged', this.onStatusChanged);
+
+//取消注册：
+ESApp.$off('onStatusChanged', this.onStatusChanged);
+
+//处理回调
+function onStatusChanged(e) {
+   const status = e.status;
+   console.log(`接收到的状态码:${  status}`);
+}
+```
+
+:::

package/rules/.docs/zh-CN/sdk/cus_splash.md

@@ -0,0 +1,97 @@
+## 如何自定义？
+快应用sdk支持自定义启动页面，需要一下几个改动。
+
+* 1.自定义view 实现IEsCoverView接口
+* 2.创建xml 使用你自定义的view
+* 3.在启动快应用的时候通过EsData().setCoverLayoutId(resId) 设置进去
+
+``` java
+
+//自定义启动图View 需要实现 IEsCoverView 接口
+public class MyCustomCoverView extends ImageView implements IEsCoverView {
+
+    private Context mContext;
+
+    public MyCustomCoverView(Context context) {
+        super(context);
+        mContext = context;
+    }
+
+    public MyCustomCoverView(Context context, @Nullable AttributeSet attrs) {
+        super(context, attrs);
+        mContext = context;
+    }
+
+    public MyCustomCoverView(Context context, @Nullable AttributeSet attrs, int defStyleAttr) {
+        super(context, attrs, defStyleAttr);
+        mContext = context;
+    }
+
+    @RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
+    public MyCustomCoverView(Context context, @Nullable AttributeSet attrs, int defStyleAttr, int defStyleRes) {
+        super(context, attrs, defStyleAttr, defStyleRes);
+        mContext = context;
+    }
+
+    @Override
+    public void onInit(Serializable serializable) {//init时候可以装入自己的图片 没有直接在xml中设置即可 例如下面xml中的  android:src="@drawable/splash_bg_default"
+        if (mContext != null) {
+            Glide.with(mContext)
+                    .asGif()
+                    .load(R.drawable.test)//可以加载自己的图片
+                    .into(this);
+        }
+    }
+
+    @Override
+    public void onEsRenderSuccess() {//渲染快应用成功后可以使用清理图片或者进一步加载后续图片等操作
+        this.postDelayed(() -> {
+            try {
+                ((ViewGroup) getParent()).removeView(this);
+                if (mContext != null) {
+                    Glide.with(mContext).clear(this);
+                }
+                setBackgroundResource(R.drawable.custon_cover_view_bg);
+            } catch (Exception e) {
+                e.printStackTrace();
+            }
+        }, 1800);
+    }
+
+    @Override
+    public void onEsRenderFailed(EsException e) {
+
+    }
+
+    @Override
+    public void suspend(String s) {
+
+    }
+
+    @Override
+    public void unSuspend() {
+
+    }
+}
+
+//xml
+<?xml version="1.0"  encoding="utf-8"?>
+<com.xxx.xxx.coustom.MyCustomCoverView
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
+    android:src="@drawable/splash_bg_default"
+    android:scaleType="fitXY"
+    android:background="@drawable/custon_cover_view_bg"
+     />
+
+ //在需要调用启动快应用的位置
+public void start(){
+    EsData data = new EsData();
+    data.setAppPackage("es.xxx.xxx.xxx");//小程序包名
+    data.setCoverLayoutId(R.layout.my_custom_cover);//自定义的xml
+    //启动快应用
+    EsManager.get().start(data);
+}
+
+```

package/rules/.docs/zh-CN/sdk/first_implementation.md

@@ -0,0 +1,15 @@
+
+1. 配置项目repositories
+``` groovy
+ repositories {
+    maven { url 'https://nexus.extscreen.com/repository/maven-public/' }
+}
+```
+
+2. 引入到项目中
+``` groovy
+dependencies {
+    implementation 'com.extscreen.runtime:official:版本号'
+}
+```
+![](https://img.shields.io/badge/dynamic/xml?url=https://nexus.extscreen.com/repository/maven-releases/com/extscreen/runtime/official/maven-metadata.xml&query=metadata/versioning/latest&label=Latest)

package/rules/.docs/zh-CN/sdk/first_init.md

@@ -0,0 +1,13 @@
+初始化
+
+
+``` java
+public class App extends MultiDexApplication {
+    @Override
+    public void onCreate(){
+        EsKitInitHelper.init(this, InitConfig.getDefault().setAppId("申请的APPID")
+            .setChannel("渠道").addFlags(InitConfig.FLAG_DYNAMIC_SO) // 动态SO
+        ); 
+    }
+}
+```

package/rules/.docs/zh-CN/sdk/first_start_app.md

@@ -0,0 +1,4 @@
+
+* 启动快应用的五种方式  
+
+* 链接到hellotv