@quicktvui/ai 1.0.0

package/rules/.docs/zh-CN/guide/faq/dev-faq.md

@@ -0,0 +1,100 @@
+---
+title: 'DevFAQ'
+lang: zh-CN
+---
+
+# 调试相关问题
+
+## 一、`npm run dev`相关
+
+::: tip Node 和 Npm 版本管理
+
+* [点击查看 node 版本管理](/zh-CN/guide/node/install)
+* [点击查看 npm  版本管理](/zh-CN/guide/npm/install)
+
+:::
+
+### 错误一、
+
+`Windows`平台报错：
+
+```shell
+HMR websocket error: Error: connect ECONNREFUSED 127.0.0.1:38989
+```
+
+<img src="/guide/faq/npm-run-dev-connect-refused.jpg" />
+
+::: tip 解决方案：
+
+***1、安装`node`版本大于 `v16.20.2` 并小于`v18.18.0`***
+
+* [点击查看 node 版本管理](/zh-CN/guide/node/install)
+* [点击查看 npm 版本管理](/zh-CN/guide/npm/install)
+
+***2、安装`Chrome`浏览器，并设置为默认浏览器***
+
+***3、重启电脑***
+
+***4、重新执行`npm run dev`***
+:::
+
+### 错误二、
+
+`Windows`平台报错：
+
+```shell
+process-handler error unhandledRejection Error: The specified module could not be found.
+```
+
+<img src="/guide/faq/npm-run-dev-dll.jpg" />
+<img src="/guide/faq/npm-run-dev-dll-connect-failed.jpg" />
+
+::: tip 解决方案：
+
+***1、检测`node`可执行程序的完整性***
+
+***2、检测系统中`.dll`的完整性。使用`DLL`错误修复工具修复系统***
+:::
+
+
+## 二、Vue2 项目升级最新 DebugServer
+
+* [点击查看`DebugServer`](/zh-CN/guide/basic/dev-debug)
+
+***最新 DebugServer 支持以下特性：***
+
+* 解决`vue2`项目只能使用`node`以下`18版本`的问题
+* 可以通过`chrome devtools`查看页面元素
+* 支持`chrome 116版本`以上的`chrome devtools`
+* 本地调试项目只需执行`npm run dev`命令，不再需要执行`npm run debug`即可
+* 编译项目只需要执行`npm run build`命令，不再需要执行`npm run vendor`即可
+
+
+### 迁移步骤：
+
+`quicktvui-template-vue2`是`vue2`项目使用`DebugServer`的模版。
+
+#### 第一步、克隆模版项目
+
+克隆`quicktvui-template-vue2`
+
+```shell
+git clone https://github.com/quicktvui/quicktvui-template-vue2.git
+```
+#### 第二步、迁移脚本
+
+使用`quicktvui-template-vue2`项目中的`scripts`替换原项目中的`scripts`目录。
+
+::: tip 注意：根据需要保留自有业务的脚本
+:::
+
+#### 第三步、迁移入口文件
+
+原项目中的`src`目录下的`main-native.js`文件，重命名为`main.js`
+
+#### 第三步、迁移`package.json`
+
+使用`quicktvui-template-vue2`项目中的`package.json`替换原项目中的`package.json`文件。
+
+::: tip 注意：需要保留 package.json 中自有业务的依赖库和相应的版本。
+:::

package/rules/.docs/zh-CN/guide/faq/develop-faq.md

@@ -0,0 +1,39 @@
+---
+title: 'DevelopFAQ'
+lang: zh-CN
+---
+
+# 开发相关问题
+
+## 一、开发语言
+
+`QuikcTVUI`使用`Vue3` + `TypeScript`开发实现。
+
+***建议项目使用`Vue3` +`TypeScript`作为开发语言。***
+
+## 二、支持 setup 语法糖
+
+生命周期使用中，一定要`defineExpose`暴露生命周期方法。
+
+```vue
+
+<template>
+  <s-title-view text="setup语法糖" />
+</template>
+
+<script setup lang="ts">
+function onESCreate() {
+  //
+}
+
+defineExpose({
+  onESCreate,
+})
+
+</script>
+
+```
+
+## 三、图片使用`file-loader`打包，必须使用`import`导入
+
+[点击查看文件资源编译](/zh-CN/guide/compile/resource)

package/rules/.docs/zh-CN/guide/faq/launch-params-faq.md

@@ -0,0 +1,119 @@
+# 启动快应用参数问题
+
+## 一、以模板项目为例
+
+项目中有两个路由页面：`home`和`error`
+
+```js
+const routes = [
+  {
+    path: '/home',
+    name: 'home',
+    component: home
+  },
+  {
+    path: '/error',
+    name: 'error',
+    component: error
+  }
+]
+```
+
+## 二、外部启动快应用传递参数
+
+### 1、`adb shell am start`启动方式
+
+```shell
+am start -d 'esapp://action/start?pkg=com.esapp.demo&from=cmd&args={"url":"home", "params":{"message":"hello vue~"}}'
+```
+
+参数说明：
+
+* `esapp://action/start` 固定协议
+* `pkg`快应用的包名
+* `from`启动来源。从命令行启动，参数值固定为`cmd`
+* `args`启动参数。
+
+::: warning 注意：
+***`args`固定格式如下：***
+
+```json
+{
+  "url": "",
+  "params": {
+  }
+}
+```
+
+* ***`url`: 启动的快应用的页面的名称***
+* ***`params`: 启动的快应用的页面传递的参数***
+  :::
+
+### 2、android程序启动方式
+
+参数格式和`adb shell`启动方式相同
+
+## 三、快应用内部接收参数
+
+1、`App.vue`中`onESCreate`方法用于接受启动应用参数
+
+```js
+function onESCreate(app: ESApp, params: ESAppParams) {
+  //app   :ESApp实例对象
+  //params:接收到的启动参数
+}
+```
+
+2、`home.vue`中`onESCreate`方法用于接受启动页面参数
+
+```js
+function onESCreate(params: ESPageParams) {
+  //params:接收到的启动参数
+}
+```
+
+## 四、示例
+
+1、`adb shell`启动快应用
+
+* 打开快应用中的`home`页面
+* 给`home`页面传递参数`{"message":"hello vue~"}`
+* 给快应用传递额外参数`extra:{"extraMessage":"hello app~"}`
+
+```shell
+am start -d 'esapp://action/start?pkg=com.esapp.demo&from=cmd&args={"url":"home", "params":{"message":"hello vue~"}, "extra":{"extraMessage":"hello app~"}}'
+```
+
+2、
+`App.vue`中`onESCreate`方法接收到的`params`参数如下：
+
+```json
+{
+  "name": "home",
+  "url": "home",
+  "params": {
+    "message": "hello vue~"
+  },
+  "extra": {
+    "extraMessage": "hello app~"
+  },
+  "sourcePath": "/index.android.js",
+  "__instanceName__": "EsApp",
+  "__instanceId__": 20
+}
+
+```
+
+::: warning 注意：adb shell 命令中的 args={"url":"home", "params":{"message":"hello vue~"}} 中的 args 对象等于 App.vue 中 onESCreate 方法的 params 对象。
+:::
+
+3、`home.vue`中`onESCreate`方法接收到的`params`参数如下：
+
+```json
+{
+  "message": "hello vue~"
+}
+```
+
+::: warning 注意：adb shell 命令中的 args={"url":"home", "params":{"message":"hello vue~"}} 中的 params 对象等于 home.vue 中 onESCreate 方法的 params 对象。
+:::

package/rules/.docs/zh-CN/guide/faq/layout-style-faq.md

@@ -0,0 +1,66 @@
+---
+title: 'LayoutStyleFAQ'
+lang: zh-CN
+---
+
+# 布局样式相关问题
+
+## 一、所有的组件都需要指定宽高尺寸
+
+`div`、`qt-text`、`qt-image`、`qt-view`等组件都需要指定宽高尺寸
+
+## 二、仅支持部分 css 样式
+
+* [点击查看支持的css列表](/zh-CN/css/overview)
+* [点击查看不支持的css列表](/zh-CN/guide/layout/style#只支持部分CSS样式)
+
+## 三、背景色
+
+* 支持`background-color: red;`
+* 不支持`background: red;`
+* 建议非`qt`组件，例如：`div`、`span`标签，样式上添加`background-color: transparent;`
+
+## 四、背景图
+
+1、 使用图片当做背景
+
+```vue
+
+<template>
+  <qt-view class='index-css'>
+    <qt-image class='background-img-css' :src='backgroundImg' />
+  </qt-view>
+</template>
+
+<script lang='ts'>
+import { defineComponent } from "@vue/runtime-core";
+import backgroundImg from '../../assets/background-img.png'
+
+export default defineComponent({
+  setup() {
+    return {
+      backgroundImg,
+    }
+  },
+});
+</script>
+
+<style scoped>
+
+.background-img-css {
+  width: 1920px;
+  height: 1080px;
+  position: absolute;
+}
+
+</style>
+```
+
+2、 使用渐变色做背景
+
+[点击查看`gradient`](/zh-CN/css/color/gradient)
+
+```vue
+
+<qt-view :gradientBackground="{ colors: ['#F5F5F5', '#F5F5F5'], cornerRadius: 99, orientation: 6 }" />
+```

package/rules/.docs/zh-CN/guide/focus/auto-focus.md

@@ -0,0 +1,94 @@
+---
+title: 'AutoFocus'
+lang: zh-CN
+---
+
+# 自动获焦
+
+::: tip sdk >= 2.8
+:::
+
+当需要一个元素请求焦点时，使用`requestFocus`等`主动`请求焦点的方法存在延迟等问题，体验不佳。
+更好的方式是通过指定`autofocus`属性，在一些`时机`下底层会`自动`的获取焦点。`autofocus`不仅方便使用，而且提升焦点体验、推荐使用。
+
+## 使用方法
+* 在div、qt-view组件上指定`autofocus`属性，如
+```html
+<div :autofocus="true"></div>
+```
+详情用法请查看[es-auto-focus](https://github.com/quicktvui/quicktvui-api-demo-vue3/blob/main/src/components/es-focus/es-auto-focus.vue)
+
+* 在qt-list-view、qt-grid-view等`列表`型组件上使用`autofocusPosition`属性，如
+```html
+<!--list-view中position为5的元素展现时将自动获焦-->
+<qt-list-view :autofocusPosition="5"></qt-list-view>
+```
+`列表`自动获焦的具体用法，请参考[列表中自动获焦](/zh-CN/guide/focus/list-auto-focus)
+
+::: tip ul 暂不支持
+:::
+
+
+## 自动时机
+不同组件会根据自身状态触发自动获焦，以下是一些触发时机：
+###  元素初始化时
+元素首次创建并展示出来时
+```html
+<!--root-->
+<div>
+    <div :autofocus="true">
+        <p>我进入页面后自动获焦</p>
+    </div>
+</div>
+```
+使用v-if标签由不可见变为可见时
+```html
+<div  v-if="created">
+    <div  :autofocus="true">
+        <!--支持嵌套的-->
+        <div>
+            <p>我会在created为true时自动获焦</p>
+        </div>
+    </div>
+</div>
+```
+
+### 由不可见变为可见时
+使用v-show或者visible属性由不可见变为可见时
+```html
+<!--v-show时-->
+<div :autofocus="true" v-show="visible">
+    <p>visible为true时我会获焦</p>
+</div>
+<!--visible时-->
+<div :autofocus="true" :visible="visible">
+    <p>visible为true时我会获焦</p>
+</div>
+```
+
+### list-view等列表组件，重新设置数据时
+list-view、grid-view等列表组件除了在可见性变化时会自动获焦，
+在重新设置数据时，也会根据`autofocusPosition`属性自动获焦；
+```vue
+<qt-list-view :autofocusPosition="5"  ref="list"></qt-list-view>
+this.$refs.list.init(data);
+<!--只要重新设置数据，position为5的子元素就会自动获焦-->
+```
+
+::: warning 注意: 这里只是init方法为伪代码
+重新设置数据方法请查看[qt-list-view组件](/zh-CN/component/list-view)文档
+:::
+>
+
+### 取消自动获焦
+将`autofocus`设为`false`即可
+```html
+<div :autofocus="isAutofocus"></div>
+```
+```js
+isAutofocus = false;
+```
+
+
+
+

package/rules/.docs/zh-CN/guide/focus/basic.md

@@ -0,0 +1,133 @@
+---
+title: 'FocusBasic'
+lang: zh-CN
+---
+
+# 焦点
+
+与手机、PC等触控交互不同，目前用户通过遥控器控制`焦点`移动、点击确定的方式来达到与智能电视交互的目的。 所以在智能电视应用开发时，焦点是一个重点也是难点，应当特别关注。
+
+::: tip 焦点（focus）一般在一个窗口（例如页面或者弹窗）中是唯一存在的，即当一个元素获得焦点时，其它元素将失去焦点。
+:::
+
+## focusable属性
+
+一个页面中元素，需要通过
+`focusable`属性来表示其是否可以获焦，当用户操作摇控器移动时，不可获焦的元素，在寻焦时将被忽略。例如：
+
+```vue
+<!-- 此div可获得焦点-->
+<div :focusable="true"></div>
+
+<!-- 此div不可获得焦点-->
+<div :focusable="false">
+<!-- 此img标签可获得焦点-->
+<img :focusable="true" />
+</div>
+```
+
+::: warning 注意：这里 div 也可替换成 qt-view。一般情况下，除确定的可聚焦元素外，应尽量将focusable属性设置为false，以防止焦点丢失等问题。
+:::
+
+## 焦点指示
+
+当一个元素获得焦点时，应改变其与普通状态的样式来指示焦点位置。
+
+通过改变以下属性来区别焦点状态：
+
+* 缩放 - 更改聚焦元素的大小
+* 边框 - 在元素周围绘制轮廓
+* 颜色 - 更新元素背景和文本颜色
+
+<img src="/guide/focus/focus-style.png" />
+
+以下是一个典型示例及实现代码：
+
+```vue
+
+<div class="box" :focusable="true" :focusScale="1.1" :enableFocusBorder="true">
+<qt-text class="text" text="Text"></qt-text>
+</div>
+```
+
+<img src="/guide/focus/list-auto-focus-2.png" />
+
+::: tip
+
+* `focusScale`属性表示焦点时放大倍数
+* `enableFocusBorder`表示焦点时是否显示边框。
+  :::
+
+css:
+
+```css
+.box {
+  width: 200px;
+  height: 100px;
+  background-color: grey; /*默认背景色*/
+  focus-background-color: black; /*焦点变为黑色*/
+  focus-scale: 1.1; /*css中也可以指定缩放倍数*/
+}
+
+.text {
+  width: 50px;
+  height: 20px;
+  color: black;
+  /*焦点状态文字变色*/
+  focus-color: white;
+}
+```
+
+通过以上代码，可实现一个div在焦点状态时背景变为黑色、文字变为白色、放大1.1倍并且展示默认的焦点边框。
+
+::: warning 注意: 当`enableFocusBorder`开启时，焦点框默认白色圆角边框，如需修改，可以通过`css`来设置:
+
+```css
+.box {
+  focus-border-radius: 5px; /*焦点边框圆角*/
+  focus-border-width: 3px; /*焦点边框宽度*/
+  focus-border-color: red; /*焦点边框颜色*/
+  enable-black-border: true; /*焦点内部黑色边框开关*/
+}
+
+```
+
+:::
+
+## 全局设置
+
+另外使用全局模块`FocusModule`可以在应用初始化时设置默认焦点样式。
+
+示例：
+
+```javascript
+//设置默认焦点颜色
+Native.callNative('FocusModule', 'setDefaultFocusBorderColor', '#ffffff');
+//设置焦点框是否有内里黑色边框
+Native.callNative('FocusModule', 'setDefaultFocusInnerBorderEnable', true);
+//设置默认焦点边框圆角
+Native.callNative('FocusModule', 'setDefaultFocusBorderCorner', 5);
+//设置默认焦点边框是否开启
+Native.callNative('FocusModule', 'setDefaultFocusBorderEnable', true);
+//设置默认焦点放大倍数
+Native.callNative('FocusModule', 'setDefaultFocusScale', 1.1);
+```
+
+## 状态变化
+
+当`div`设置`focusable`为`true`时，内部的元素可通过将`duplicateParentState`属性设置为`true`，跟随`div`的状态改变。
+
+示例：
+
+```vue
+
+<div class="divBoxClass" :focusable="true">
+<div class="divBoxTest" :duplicateParentState="true">
+  <p :duplicateParentState="true">焦点时变色</p>
+  <p :duplicateParentState="false">焦点时不变</p>
+</div>
+</div>
+
+```
+
+上述代码可实现`p`标签随着焦点状态改变颜色

package/rules/.docs/zh-CN/guide/focus/debug-tool.md

@@ -0,0 +1,40 @@
+---
+title: 'FocusDebug'
+lang: zh-CN
+---
+
+# 焦点调试
+
+## UI调试
+
+::: tip sdk >= 2.8
+:::
+
+可在任意版本`>=2.8`的 [Runtime](/zh-CN/resource/runtime) 打开焦点UI调试工具 可以通过些工具查看以下信息：
+
+* 当前焦点元素信息
+  * 元素`id、sid、name`
+  * 元素`尺寸、alpha、visibility、hashcode`
+  * `nextFocusName`信息
+  * `nextFocusSID`信息
+* 焦点关键日志
+
+开启命令：
+
+```shell
+qui debug -f true
+```
+
+<img src="/guide/focus/debug-focus.png">
+
+
+::: tip qui debug
+
+***[点击查看 qui debug 命令](/zh-CN/tool/cli/debug)***
+
+:::
+
+
+
+
+