@quicktvui/ai 1.0.0

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

@@ -0,0 +1,317 @@
+---
+
+---
+
+# 焦点进阶
+
+在处理`焦点`相关交互时，可通过一些`焦点`相关便利的方法来满足产品需要。
+
+## 焦点属性
+
+### nextFocusName
+通过名称，指定下一个焦点元素
+
+`(up: 'string', left: 'string', right: 'string', down: 'string')`
+ * `up`: string - 按'上'方向的name名称 ；
+ * `left`: string - 按'左'方向的name名称 ；
+ * `right`: string - 按'右'方向的name名称 ；
+ * `down`: string - 按'下'方向的name名称 ；
+
+指定下一个焦点名称，寻焦默认逻辑是顺找最近的焦点，为防止焦点出现在需求以外的地方，可以在标签中指定下个焦点的name;
+ * `nextFocusName`属性可使用于`focusable=true`的标签，和`ul`标签。
+ * 在`focusable=true`的标签中使用`nextFocusName`优先级高于ul中使用的`nextFocusName`
+ * 如果在ul上或者ul列表的子标签上使用`nextFocusName`，会在列表的边界执行，例如横向列表`listA`中设置`right`为`listB`，当焦点在`A3`时按`右`，焦点才会到`listB`中，由于ul列表默认带记忆焦点功能，焦点会落在`listB`中的`上一次焦点`所在，如果是`第一次`默认选中`第一个`。
+
+示例
+
+
+::: details 点击查看源码
+```html
+
+<div class="focus-next">
+    <div>
+        <ul horizontal name="listA" :nextFocusName="{down: 'listC', right: 'listB'}" ref="giftTabs">
+            <li>
+                <div :focusable=true class="button"><p duplicateParentState>A1</p></div>
+            </li>
+            <li>
+                <div :focusable=true class="button"><p duplicateParentState>A2</p></div>
+            </li>
+            <li>
+                <div :focusable=true class="button"><p duplicateParentState>A3</p></div>
+            </li>
+        </ul>
+        <ul horizontal name="listB">
+            <li>
+                <div :focusable=true class="button"><p duplicateParentState>B1</p></div>
+            </li>
+            <li>
+                <div :focusable=true class="button" :nextFocusName="{up: 'btnE'}"><p duplicateParentState>B2</p></div>
+            </li>
+            <li>
+                <div :focusable=true class="button"><p duplicateParentState>B3</p></div>
+            </li>
+        </ul>
+        <ul horizontal name="listC">
+            <li>
+                <div :focusable=true class="button" ref="listC"><p duplicateParentState>C1</p></div>
+            </li>
+            <li>
+                <div :focusable=true class="button"><p duplicateParentState>C2</p></div>
+            </li>
+            <li>
+                <div :focusable=true class="button"><p duplicateParentState>C3</p></div>
+            </li>
+        </ul>
+    </div>
+    <div>
+        <div class="feature-item">
+            <div :focusable=true class="button" name="btnD" :nextFocusName="{down: 'listB'}"><p duplicateParentState>
+                DD</p></div>
+            <div :focusable=true class="button" name="btnE" :nextFocusName="{left: 'listB', down: 'listC'}"><p
+                    duplicateParentState>EE</p></div>
+        </div>
+    </div>
+</div>
+```
+
+:::
+### descendantFocusability
+
+禁用焦点，适用场景如自定义弹出框显示时，主页面需禁用焦点，防止焦点误操作焦点丢失。
+ * `1`: int - 1为不禁用，默认为1 ；
+ * `2`: int - 2为禁用 ；
+
+示例
+
+
+```html
+
+<div :descendantFocusability="modalShow ? 2 : 1">
+    ...
+    <!--主页面内容-->
+</div>
+<div v-show="modalShow">
+    ...
+    <!--自定义弹出框-->
+</div>
+```
+
+### ⁣blockFocusDirections
+
+阻止焦点方向，适用于焦点标签或焦点父标签
+ * `left`: string - 左 ；
+ * `right`: string - 右 ；
+ * `up`: string - 上 ；
+ * `down`: string - 下 ；
+
+示例
+
+
+```html
+
+<div :⁣blockFocusDirections="blockAll" :focusable="true"><p>按钮</p></div>
+<ul ref="list" :⁣blockFocusDirections="blockLeftRight">
+    <li :focusable="true"><p>超清</p></li>
+    <li class="selected" :focusable="true"><p>高清</p></li>
+    <li :focusable="true"><p>超清</p></li>
+</ul>
+```
+
+
+```js
+data()
+{
+    return {
+        blockAll: ['left', 'right', 'up', 'down'],
+        blockLeftRightTop: ['left', 'right', 'up'],
+        blockLeftRight: ['left', 'right'],
+    }
+}
+```
+
+### showOnState
+
+相应焦点状态时显示，三个状态一组使用。`view`根据状态会自动显示或者隐藏。
+ * `normal`: string - 正常 ；
+ * `focused`: string - 焦点 ；
+ * `selected`: string - 选中，在`ul`组件中生效，移出`ul`时触发，如果不需要`selected`状态，`ul`标签中添加`:enableSelectOnFocus="false"` ；
+
+示例
+
+
+::: details 点击查看源码
+```html
+
+<div class="item" :focusable="true">
+    <img class="content" showOnState="normal" src="file://assets/img.png">
+    <img class="content" showOnState="focused" src="file://assets/img_focus.png">
+</div>
+<div class="item" :focusable="true">
+    <div class="content" showOnState="normal"><p>我是初始化显示的内容</p></div>
+    <div class="content" showOnState="focused"><p>我是焦点时显示的内容</p></div>
+</div>
+<div class="list">
+    <ul horizontal>
+        <li>
+            <div class="item" :focusable="true">
+                <div class="content" showOnState="normal"><p>我是初始化显示的内容1</p></div>
+                <div class="content" showOnState="focused"><p>我是焦点时显示的内容1</p></div>
+                <div class="content" showOnState="selected"><p>我是选中时显示的内容1</p></div>
+            </div>
+        </li>
+        <li>
+            <div class="item" :focusable="true">
+                <div class="content" showOnState="normal"><p>我是初始化显示的内容2</p></div>
+                <div class="content" showOnState="focused"><p>我是焦点时显示的内容2</p></div>
+                <div class="content" showOnState="selected"><p>我是选中时显示的内容2</p></div>
+            </div>
+        </li>
+        <li>
+            <div class="item" :focusable="true">
+                <div class="content" showOnState="normal"><p>我是初始化显示的内容3</p></div>
+                <div class="content" showOnState="focused"><p>我是焦点时显示的内容3</p></div>
+                <div class="content" showOnState="selected"><p>我是选中时显示的内容3</p></div>
+            </div>
+        </li>
+    </ul>
+</div>
+```
+
+:::
+
+::: details 点击查看源码
+```css
+.item {
+    width: 200px;
+    height: 100px;
+    background-color: transparent;
+    focus-background-color: antiquewhite;
+}
+
+.content {
+    position: absolute;
+    width: 200px;
+    height: 100px;
+    left: 0;
+    top: 0;
+    background-color: transparent;
+}
+
+.list ul {
+    flex-direction: row;
+}
+```
+
+:::
+注意：
+1.  使用`showOnState`的标签需要使用`position: absolute;`，使3个状态标签处于重叠的位置；
+2. `showOnState`元素层级需格外注意控制，避免层级过多，导致页面加载慢、帧率低等问题。
+
+`showOnState`错误示范：
+```html
+<div>
+    <div showOnState="normal">
+        <img :src="myImg">
+        <div>
+            <qt-text text="我普通状态展示"/>
+        </div>
+    </div>
+    <div showOnState="focused">
+        <img :src="myImg">
+        <div>
+            <qt-text text="我焦点状态展示"/>
+        </div>
+    </div>
+</div>
+```
+正确示范：
+```html
+<div>
+    <div>
+        <img src="myImg">
+        <div>
+            <qt-text showOnState="normal" text="我普通状态展示"/>
+            <qt-text showOnState="focused" text="我焦点状态展示"/>
+        </div>
+    </div>
+</div>
+```
+上述示例中，实现同样效果，但错误示例相对于正确的元素多了近一倍，当页面元素过多时，会导致页面加载慢、帧率低、内存不足等问题。
+## 主动定位焦点
+
+### requestFocus
+
+`($refs: object)`
+ * `$refs`: object - `focusable="true"`的元素的$refs对象，例如：this.$refs.view ；
+
+示例
+
+
+```html
+
+<div :focusable="true" ref="view"></div>
+```
+
+
+```js
+import {ESFocusManager} from "@extscreen/es-core";
+ESFocusManager.requestFocus(this.$refs.view);
+```
+
+或者
+
+
+```js
+Native.callUIFunction(this.$refs.view, 'requestFocus', []);
+```
+
+
+也可通过requestFocus属性来请求焦点，不过此种方法仅在元素`初始化`时生效，如下
+```html
+<div :focusable="true" :requestFocus="true"></div>
+```
+
+## 预设焦点
+
+### setSelectChildPosition
+
+`($refs: object, index: int)`
+
+预设焦点适用于ul列表，ul列表第一次有焦点时默认为第一个子view；
+
+适用场景如下：当前默认清晰度为高清，需求为移动到清晰度区域时焦点在当前使用清晰度上。
+ * `$refs`: object - ul的$refs对象，例如：this.$refs.view ；
+ * `index`: int - 第几个子标签, 从0开始 ；
+
+示例
+
+
+```html
+
+<ul ref="list">
+    <li :focusable="true"><p>超清</p></li>
+    <li class="selected" :focusable="true"><p>高清</p></li>
+    // 默认清晰度
+    <li :focusable="true"><p>超清</p></li>
+</ul>
+```
+
+
+```js
+Native.callUIFunction(this.$refs.list, 'setSelectChildPosition', [1]);
+```
+
+## 清除记忆焦点
+
+### clearFocusMemory
+
+`($refs: object)`
+
+清除记忆焦点适用于ul列表，ul列表默认有记忆焦点功能，使用此方法后下次焦点移动到此ul上焦点到第一个子view上。
+
+ * `$refs`: object - ul的$refs对象，例如：this.$refs.view ；
+
+```js
+Native.callUIFunction(this.$refs.list, 'clearFocusMemory', []);
+```

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

@@ -0,0 +1,94 @@
+---
+
+---
+
+# 列表中的焦点
+
+::: tip sdk >= 2.8
+:::
+
+> sdk>=2.8
+
+`qt-list-view`、`qt-grid-view`列表组件因其特殊实现方式，实现`自动获焦`的方式有所不同。
+
+## 指定初始获焦位置
+通过指定`autofocusPosition`属性，当其值`>=0`时，列表在初始化、可见性变化、重设数据时都会自动另对应`position`的子元素获焦；
+```html
+<!--list-view中第0个元素展现时将自动获焦-->
+<qt-list-view :autofocusPosition="0">
+    <!-- 子无素可直接获焦 -->
+    <div :type="1" :focusable="true"></div>
+    <!-- 也支持元素内部获焦 -->
+    <div :type="2" :focusable="false">
+        <div focusable="true"></div>
+    </div>
+</qt-list-view>
+```
+<img src="/guide/focus/list-auto-focus-1.png" />
+
+## 自动滚动并获焦
+当前列表创建完成时，有可能指定位置的元素不在可视区域内，此时如指定了`autofocusPosition`列表将自动滚动并获焦。
+下例中，页面中只展示三个元素，希望初始时第5个元素获焦：
+
+```html
+<!--list-view中第5个元素展现时将自动获焦-->
+<qt-list-view :autofocusPosition="4"></qt-list-view>
+```
+<img src="/guide/focus/list-auto-focus-2.png" />
+
+
+
+[//]: # (## 自动滚动并获焦)
+
+[//]: # ()
+[//]: # (当前列表创建完成时，有可能指定位置的元素不在可视区域内，此时需要使用`autoscroll`自动滚动到指定位置;)
+
+[//]: # ()
+[//]: # (例如页面中只展示三个元素，如希望初始时第5个元素获焦，此时就需要使用`autoscroll`属性。)
+
+[//]: # ()
+[//]: # ()
+[//]: # (```html)
+
+[//]: # ()
+[//]: # (<!--list-view中第0个元素展现时将自动获焦-->)
+
+[//]: # ()
+[//]: # (<qt-list-view :autofocusPosition="4" :autoscroll="[4,120]"></qt-list-view>)
+
+[//]: # ()
+[//]: # (```)
+
+[//]: # ()
+[//]: # (<img src="/guide/list-autofocus-2.png" />)
+
+[//]: # ()
+[//]: # ()
+[//]: # (`autoscroll`属性为数组，即`autoscroll=[position,offset]`，其中第一个元素为`position`，第二个元素为`滚动偏移量`；)
+
+[//]: # ()
+[//]: # (> 上述例子中`offset`设置120是为了让第五个元素居中,`offset`通常计算方式为：`offset = &#40;list-view高度 - item高度&#41; / 2`；)
+
+
+[//]: # (具体用法请参考`list-view中`的`autoscroll`属性。)
+
+
+## 取消自动获焦
+当列表中的元素不需要自动获焦时，可以通过`autofocusPosition`属性设置为`-1`来取消自动获焦。
+```html
+<qt-list-view :autofocusPosition="autofocusPosition"
+              :autoscroll="[scrollPosition,0]">
+```
+```js
+autofocusPosition = -1;
+//如设置了滚动，也可能通过设成-1取消
+scrollPosition = -1;
+```
+
+更多列表中的自动焦点用法请查看[es-auto-focus-list-demo](https://github.com/quicktvui/quicktvui-api-demo-vue3/blob/main/src/components/es-focus/es-auto-focus-list-demo.vue)
+
+
+
+
+
+

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

@@ -0,0 +1,10 @@
+---
+layout: doc
+outlineTitle: false
+---
+
+<script setup>
+</script>
+
+# 请求焦点
+

package/rules/.docs/zh-CN/guide/interaction/click.md

@@ -0,0 +1,39 @@
+---
+title: 'Click'
+lang: zh-CN
+---
+
+# 点击
+
+::: warning 注意：只有可获得焦点的组件，在焦点状态才可以点击。
+:::
+
+***组件被点击触发点击事件的时候，会发送`click`事件***
+
+* 设置可获得焦点`:focusable="true"`
+* 监听`click`事件`@click="onClick"`
+
+```vue
+
+<template>
+  <div
+:focusable="true"
+       :enableFocusBorder="true"
+       :focusScale="1.1"
+       @click="onClick"/>
+</template>
+
+<script>
+export default {
+  name: 'TextButton'
+}
+</script>
+
+<script setup>
+
+const onClick = (e) => {
+  //处理点击事件
+}
+</script>
+```
+

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

@@ -0,0 +1,44 @@
+---
+title: 'Click'
+lang: zh-CN
+---
+
+# 焦点
+
+::: tip 焦点相关
+
+***[点击查看](/zh-CN/guide/focus/basic)***
+
+:::
+
+* 在组件上设置属性`:focusable="true"`，可使组件可获焦
+* 监听`focus`事件`@focus="onFocus"`
+* 显示焦点边框`:enableFocusBorder="true"`
+* 设置焦点放大倍数`:focusScale="1.1"`
+
+```vue
+
+<template>
+  <div
+:focusable="true"
+       :enableFocusBorder="true"
+       :focusScale="1.1"
+       @focus="onFocus"/>
+</template>
+
+<script>
+export default {
+  name: 'TextButton'
+}
+</script>
+
+<script setup>
+
+const onFocus = (e) => {
+  const focused = e.isFocused;
+  //处理焦点事件
+}
+
+</script>
+```
+

package/rules/.docs/zh-CN/guide/key/back.md

@@ -0,0 +1,65 @@
+---
+title: 返回键
+lang: zh-CN
+---
+
+# 返回键
+
+::: warning 注意
+
+仅在[`Page`](/zh-CN/guide/page/type)中使用生效
+
+:::
+
+## 一、基础用法
+
+在`setup`中编写 `onBackPressed`方法，并在`return`中返回此方法。
+
+```ts
+
+function onBackPressed() {
+  //
+}
+
+return {
+  onBackPressed
+}
+```
+
+:::demo
+
+module/key/es-back
+
+:::
+
+## 二、拦截返回键
+
+`onBackPressed`方法中编写业务逻辑
+
+```ts
+function onBackPressed() {
+//编写业务逻辑
+}
+```
+
+## 三、关闭页面
+
+`onBackPressed`方法中调用`router.back()`方法关闭页面
+
+```js
+const router = useESRouter()
+
+function onBackPressed() {
+  //1.处理业务逻辑
+  //2.调用router关闭页面
+  router.back()
+}
+```
+
+## API
+
+### Exposes
+
+| Name                             | Description                 | Type                                                                              |
+| -------------------------------- | --------------------------- | --------------------------------------------------------------------------------- |
+| onBackPressed                    | 监听返回键事件                 | ^[Function]`onBackPressed(): void`                                                    |

package/rules/.docs/zh-CN/guide/key/dispatch-key-event.md

@@ -0,0 +1,41 @@
+---
+title: DispatchKeyEvent
+lang: zh-CN
+---
+
+# 监听分发按键事件
+
+::: warning 注意
+
+仅在[`Page`](/zh-CN/guide/page/type)中使用生效
+
+:::
+
+## 基础用法
+
+在`setup`中编写`onDispatchKeyEvent`方法，并在`return`中返回此方法。
+
+```ts
+
+function onDispatchKeyEvent(keyEvent: ESKeyEvent) {
+  //
+}
+
+return {
+  onDispatchKeyEvent,
+}
+```
+
+:::demo
+
+module/key/es-dispatch
+
+:::
+
+## API
+
+### Exposes
+
+| Name                             | Description                 | Type                                                                              |
+| -------------------------------- | --------------------------- | --------------------------------------------------------------------------------- |
+| onDispatchKeyEvent               | 监听分发按键事件               | ^[Function]`onDispatchKeyEvent(keyEvent: ESKeyEvent): void`                                                    |

package/rules/.docs/zh-CN/guide/key/key-event.md

@@ -0,0 +1,87 @@
+---
+title: KeyEvent
+lang: zh-CN
+---
+
+# 按键事件
+
+::: warning 注意
+
+仅在[`Page`](/zh-CN/guide/page/type)中使用生效
+
+:::
+
+## 基础用法
+
+在`setup`中编写 `onKeyDown` 和 `onKeyUp` 方法，并在`return`中返回此方法。
+
+```ts
+
+function onKeyDown(keyEvent: ESKeyEvent) {
+  //按键被按下
+  //处理业务逻辑
+}
+
+function onKeyUp(keyEvent: ESKeyEvent) {
+  //按键被抬起
+  //处理业务逻辑
+}
+
+return {
+  onKeyDown,
+  onKeyUp,
+}
+```
+
+:::demo
+
+module/key/es-event
+
+:::
+
+## API
+
+### DataStructure
+
+#### ESKeyEvent
+
+按键事件
+
+| Name                        | Description                   | Type                        | Default |
+| --------------------------- | ------------------------------| ----------------------------|---------|
+| action                      | 按键动作                        | ^[ESKeyAction]              |   -    |
+| keyCode                     | 键值                           | ^[ESKeyCode]                |   -    |
+| keyRepeat                   | 重复按键的次数                   | ^[number]                   |   -    |
+
+#### ESKeyAction
+
+按键动作
+
+| Name                        | Description                   | Type                        |   Default   |
+| --------------------------- | ------------------------------| ----------------------------|---------|
+| ES_KEY_ACTION_DOWN          | 按下                 | ^[ESKeyAction]                     |   -    |
+| ES_KEY_ACTION_UP            | 抬起                 | ^[ESKeyAction]                    |   -    |
+
+#### ESKeyCode
+
+按键值
+
+| Name                        | Description                   | Type                        |   Default   |
+| --------------------------- | ------------------------------| ----------------------------|---------|
+| ES_KEYCODE_ENTER            | 回车键                         | ^[number]                     |   66    |
+| ES_KEYCODE_DPAD_CENTER      | 导航键 确定键                 | ^[number]                    |   23    |
+| ES_KEYCODE_DPAD_UP          | 导航键 向上                 | ^[number]                    |   19    |
+| ES_KEYCODE_DPAD_DOWN        | 导航键 向下                 | ^[number]                    |   20    |
+| ES_KEYCODE_DPAD_LEFT        | 导航键 向左                 | ^[number]                    |   21    |
+| ES_KEYCODE_DPAD_RIGHT       | 导航键 向右                 | ^[number]                    |   22    |
+| ES_KEYCODE_BACK             | 返回键                 | ^[number]                    |   4    |
+| ES_KEYCODE_ESCAPE           | 回退键                 | ^[number]                    |   111    |
+| ES_KEYCODE_MENU             | 菜单键                 | ^[number]                    |   82    |
+| ES_KEYCODE_SEARCH           | 搜索键                 | ^[number]                    |   84    |
+
+### Exposes
+
+| Name                             | Description                 | Type                                           |
+| -------------------------------- | --------------------------- | -----------------------------------------------|
+| onKeyDown                    | 监听按键按下                 | ^[Function]`onKeyDown(keyEvent: ESKeyEvent): void`   |
+| onKeyUp                    | 监听按键抬起                 | ^[Function]`onKeyUp(keyEvent: ESKeyEvent): void`   |