doc: classList

Author: yuanzm

demos/noengine/engine.js

@@ -94,6 +94,7 @@ export default defineConfig({
         link: '/tutorial/cocos2.x',
         items: [
           { text: '模板引擎使用', link: '/tutorial/templateengine'},
+          { text: '动态修改样式', link: '/tutorial/style'},
           { text: 'cocos2.x版本适配', link: '/tutorial/cocos2.x'},
           { text: '使用字体', link: '/tutorial/font'},
           { text: '加载中效果实现', link: '/tutorial/loading'},

demos/noengine/sub/engine.js

@@ -1,5 +1,9 @@
+#### 2024.11.22
+1. `A` 新增 classList 特性支持；
+3. `U` 小游戏插件发布1.0.14版本；
+
 #### 2024.11.11
-1. `A` 新增insertElement;
+1. `A` 新增insertElement；
 2. `U` 优化ts声明协议；
 3. `U` 小游戏插件发布1.0.13版本；
 
@@ -75,16 +79,20 @@
 #### 2022.1.13
 1. `U` 支持 dataset 特性
 2. `U` 小游戏插件发布 0.0.10 版本
+
 #### 2022.1.9
 1. `U` BitMapText 支持 letterSpacing样式，支持解析配置里面的kerning
 2. `U` 小游戏插件发布 0.0.9 版本
+
 #### 2021.12.6
 1. `F` 修复点击层级的问题；
 2. `U` 小游戏插件发布 0.0.8 版本
+
 #### 2021.9.19
 1. `F` 修复文档拼写错误；
 2. `U` npm 发布1.0.6版本；
 3. `F` 修复点击事件不准确[问题](https://github.com/wechat-miniprogram/minigame-canvas-engine/issues/6);
+
 #### 2021.9.2
 1. `U` 重写Scrollview，引用[scroller](https://github.com/pbakaus/scroller)，支持横向滚动和纵向滚动，体验更好；
 2. `A` Scrollview 新增scrollX和scrollY配置，用于标识是否需要横向滚动和纵向滚动；

dist/index.js

@@ -0,0 +1,22 @@
+# ClassList
+
+返回一个元素 class 属性的集合，通过 ClassList 可以动态操作元素的 class 集合。
+
+## 属性
+
+### length
+一个整数，元素的 class 个数。
+
+### value
+以字符串的形式返回 class 列表的值。
+
+## 方法
+
+### add(className: string)
+新增一个 className
+
+### contains(className: string)
+检查是否包含给定的 className
+
+### remove(className: string)
+删除给定的 className

docs/.vitepress/config.mts

@@ -1,5 +1,3 @@
-[[toc]]
-
 # Element
 
 Element 是所有组件的基类，Element 描述了所有组件所普遍具有的方法和属性。一些组件继承自 Element 并且增加了一些额外功能的接口描述了具体的行为。
@@ -27,6 +25,34 @@ Element 是所有组件的基类，Element 描述了所有组件所普遍具有
 | top | Number | 以父节点左上角为坐标系原点的 Y 坐标值 | -->
 
 
+## 属性
+
+### dataset
+标签上通过 **data-\*** 设置的属性会存到 dataset 字段，方便记录一些节点信息。
+
+### classList: [ClassList](./classList.md)
+返回一个元素 class 属性的集合，通过 ClassList 可以动态操作元素的 class 集合，需要特别注意的是，id 会默认添加到 class 集合
+
+```js
+// <view id="container" class="info"></view>
+const container = Layout.getElementById('container');
+
+console.log(container.classList.value); // `container info`
+
+container.classList.add('test');
+
+container.classList.remove('test');
+
+```
+
+### style
+元素的样式集合，可以通过 style 属性动态修改样式。
+``` js
+let testText = Layout.getElementById('testText');
+
+testText.style.backgroundColor = '#f3f3f3'
+```
+
 ## 方法
 
 ### getElementsById(elementId: string): Element[]
@@ -49,7 +75,6 @@ Layout.getElementById(String elementId)
 const container = Layout.getElementById('container');
 ```
 
-
 ### getElementsByClassName(className: string): Element[]
 
 获取包含class为**className**的一组元素。

docs/CHANGELOG.md

@@ -0,0 +1,61 @@
+# 动态修改样式
+
+动态修改样式是很常见的需求，Layout 支持了一些场景的动态修改样式的能力。
+
+## style 属性
+初始化 Layout 的时候，会传入模板和样式，针对于每个节点，Layout 会根据 id 和 class 属性，从样式表中找出应该生效的样式，最终样式会挂载在 style 属性上。
+
+通过 style 属性，可以动态修改元素的样式，Layout 会判定当前的修改是触发重新布局还是重新渲染，无需其他操作，样式会自动生效。
+``` js
+let testText = Layout.getElementById('testText');
+
+testText.style.backgroundColor = '#f3f3f3'
+```
+
+动态修改 style 很常见的使用场景是缓动系统，详情可见[教程](../api/tween.md)。
+
+## classList 属性
+通过 style 动态修改样式一般作用于样式修改比较少的场景，如果需要批量修改样式，更好的方式是通过操作 class 的方式，通过 [classList](../components/classList.md) 可以动态操作元素的 class 集合，需要特别注意的是，id 会默认添加到 class 集合。
+
+```js
+// <view id="container" class="info"></view>
+const container = Layout.getElementById('container');
+
+console.log(container.classList.value); // `container info`
+
+container.classList.add('test');
+
+container.classList.remove('test');
+```
+
+## 伪类能力
+
+用来添加一些选择器的特殊效果，目前仅支持最场景的 `:active` 场景，伪类本质上是快捷的修改 style 操作，避免通过 js 反复操作元素样式。
+
+| 属性名 | 支持的值或类型 | 说明 |
+| --------------- | ------------------- | ----------- |
+| ':active' | Object | **(v1.0.9开始支持)**，当节点触发 'touchstart' 事件的时候触发 |
+
+如下所示，当元素被点击的时候，元素会放大，当点击结束，元素又会重置会原样，这对实现按钮特性的时候尤为有用，不需要单独给按钮绑定点击事件手动对元素进行缩放和重置。
+``` json
+{
+  color: '#ffffff',
+  backgroundColor: '#34a123',
+  borderRadius: 10,
+  width: 400,
+  height: 120,
+  lineHeight: 120,
+  fontSize: 50,
+  textAlign: 'center',
+  marginTop: 20,
+  ':active': {
+    transform: 'scale(1.05, 1.05)',
+  },
+}
+```
+
+<iframe height="439.15838623046875" style="width: 100%;" scrolling="no" title="Layout Text Button" src="https://codepen.io/yuanzm/embed/MWRoexw?default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/yuanzm/pen/MWRoexw">
+  Layout Text Button</a> by yuanzm (<a href="https://codepen.io/yuanzm">@yuanzm</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>

docs/components/classList.md

@@ -3,7 +3,7 @@ import { defineComponent } from "vue";
 
 let template = `
   <view id="container">
-    <text id="testText" class="" value="Hello World"></text>
+    <text id="testText" class="redText" value="Hello World"></text>
   </view>
 `;
 

docs/components/element.md

@@ -51,7 +51,7 @@ export default defineComponent({
     return {
       isDev: true,
 
-      tabindex: 4,
+      tabindex: 5,
     };
   },
   mounted() {