style: add code comments

kailong321200875 · May 20, 2022 · d980f43 · d980f43
1 parent bd1946f
commit d980f43
Show file tree

Hide file tree

Showing 6 changed files with 102 additions and 36 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -79,5 +79,5 @@ jobs:
       - name: Build
         run: pnpm run build
 
-      # - name: Test
-      #   run: pnpm run test
+      - name: Test
+        run: pnpm run test
diff --git a/examples/index.html b/examples/index.html
@@ -5,32 +5,18 @@
 		<title>tool-helper-example</title>
 	</head>
 	<body>
-		<div id="div"></div>
+		<div id="div" style="width: 100px;height: 100px;overflow: auto;background-color: red;">
+			<div id="div2" style="width: 100px;height: 200px;"></div>
+		</div>
 	</body>
   <script type="module">
     // es module 引入
     import * as tool from '../dist/index.mjs'
-		const div = document.createElement('div')
-		const div1 = document.getElementById('div')
-		console.log(div1.nodeType)
-		console.log(tool.isElement(div))
-		console.log(tool.calculateBestTextColor('#cccccc'))
-		console.log(tool.calculateBestTextColor('#141414'))
+		console.log(tool.getScrollContainer(document.getElementById('div2')))
 
-		const SPECIAL_CHARS_REGEXP = /([\:\-\_]+(.))/g
-		const MOZ_HACK_REGEXP = /^moz([A-Z])/
-		const camelCase = function (name) {
-			return name
-				.replace(SPECIAL_CHARS_REGEXP, function (_, __, letter, offset) {
-					return offset ? letter.toUpperCase() : letter
-				})
-				.replace(MOZ_HACK_REGEXP, 'Moz$1')
-		}
-
-		console.log(camelCase('testTest'))
-		console.log(camelCase('test-test'))
-		console.log(camelCase('test_test'))
-		console.log(camelCase('Test_Test'))
-		console.log(camelCase('TestTest'))
+		const arr = [{value: 1, id: 1}, {value: 2, pid: 1, id: 2}]
+		const tree = [{value: 1, id: 1, children: [{value: 2, pid: 1, id: 2}]}]
+		console.log(tool.listToTree(arr))
+		console.log(tool.treeToList(tree))
   </script>
 </html>
diff --git a/src/dom/index.ts b/src/dom/index.ts
@@ -228,9 +228,19 @@ export const once = (el: HTMLElement, event: string, fn: EventListener): void =>
   on(el, event, listener)
 }
 
+/**
+ * 获取元素的某个样式
+ * @category Dom
+ * @param element 元素
+ * @param styleName 属性名
+ * @example
+ * ``` typescript
+ * getStyle(document.getElementById('test'), 'height')
+ * ```
+ */
 export const getStyle =
   ieVersion < 9
-    ? function (element: Element | any, styleName: string) {
+    ? (element: Element | any, styleName: string) => {
         if (isServer()) return
         if (!element || !styleName) return null
         styleName = camelCase(styleName)
@@ -254,7 +264,7 @@ export const getStyle =
           return element.style[styleName]
         }
       }
-    : function (element: Element | any, styleName: string) {
+    : (element: Element | any, styleName: string) => {
         if (isServer()) return
         if (!element || !styleName) return null
         styleName = camelCase(styleName)
@@ -269,8 +279,18 @@ export const getStyle =
         }
       }
 
-/* istanbul ignore next */
-export function setStyle(element: Element | any, styleName: any, value: any) {
+/**
+ * 设置元素的某个样式
+ * @category Dom
+ * @param element 元素
+ * @param styleName 属性名
+ * @param value 属性值
+ * @example
+ * ``` typescript
+ * setStyle(document.getElementById('test'), 'height', '100px')
+ * ```
+ */
+export const setStyle = (element: Element | any, styleName: any, value: any) => {
   if (!element || !styleName) return
 
   if (typeof styleName === 'object') {
@@ -289,8 +309,17 @@ export function setStyle(element: Element | any, styleName: any, value: any) {
   }
 }
 
-/* istanbul ignore next */
-export const isScroll = (el: Element, vertical: any) => {
+/**
+ * 判断元素overflow
+ * @category Dom
+ * @param el 元素
+ * @param vertical 滚动条方向，'overflow-y' | 'overflow-x'
+ * @example
+ * ``` typescript
+ * isScroll(document.getElementById('test'), 'overflow-y')
+ * ```
+ */
+export const isScroll = (el: Element, vertical?: 'overflow-y' | 'overflow-x') => {
   if (isServer()) return
 
   const determinedDirection = vertical !== null || vertical !== undefined
@@ -303,8 +332,17 @@ export const isScroll = (el: Element, vertical: any) => {
   return overflow.match(/(scroll|auto)/)
 }
 
-/* istanbul ignore next */
-export const getScrollContainer = (el: Element, vertical?: any) => {
+/**
+ * 判断元素的滚动容器
+ * @category Dom
+ * @param el 元素
+ * @param vertical 滚动条方向，'overflow-y' | 'overflow-x'
+ * @example
+ * ``` typescript
+ * getScrollContainer(document.getElementById('test'))
+ * ```
+ */
+export const getScrollContainer = (el: Element, vertical?: 'overflow-y' | 'overflow-x') => {
   if (isServer()) return
 
   let parent: any = el
@@ -321,7 +359,16 @@ export const getScrollContainer = (el: Element, vertical?: any) => {
   return parent
 }
 
-/* istanbul ignore next */
+/**
+ * 判断元素是否在某个容器内
+ * @category Dom
+ * @param el 元素
+ * @param container 父容器元素
+ * @example
+ * ``` typescript
+ * isInContainer(document.getElementById('test'), document.body)
+ * ```
+ */
 export const isInContainer = (el: Element, container: any) => {
   if (isServer() || !el || !container) return false
 

diff --git a/src/dom/index.window.test.ts b/src/dom/index.window.test.ts
@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 import { expect, it } from 'vitest'
-import { hasClass, addClass, removeClass, getBoundingClientRect } from './index'
+import { hasClass, addClass, removeClass, getBoundingClientRect, getStyle, setStyle } from './index'
 
 it('hasClass', () => {
   const div = document.createElement('div')
@@ -57,3 +57,17 @@ it('getBoundingClientRect', () => {
     y: 0
   })
 })
+
+it('getStyle', () => {
+  const div = document.createElement('div')
+  div.innerText = 'test'
+  div.style.color = 'red'
+  expect(getStyle(div, 'color')).toBe('red')
+})
+
+it('setStyle', () => {
+  const div = document.createElement('div')
+  div.innerText = 'test'
+  setStyle(div, 'color', 'red')
+  expect(getStyle(div, 'color')).toBe('red')
+})
diff --git a/src/public/index.ts b/src/public/index.ts
@@ -36,7 +36,7 @@ export const trim = (s: string): string => {
  * @param name 需要转换的字符串
  * @example
  * ``` typescript
- * camelCase(test-test)
+ * camelCase('test-test')
  * ```
  */
  export const camelCase = (name: string): string => {

diff --git a/src/tree/index.ts b/src/tree/index.ts
@@ -17,7 +17,16 @@ const DEFAULT_CONFIG: TreeHelperConfig = {
 
 const getConfig = (config: Partial<TreeHelperConfig>) => Object.assign({}, DEFAULT_CONFIG, config)
 
-// tree from list
+/**
+ * 一维数组转树形数据
+ * @param list 需要转换的数组
+ * @param config 树形的配置项
+ * @category Tree
+ * @example
+ * ``` typescript
+ * listToTree([{value: 1, id: 1}, {value: 2, pid: 1, id: 2}])
+ * ```
+ */
 export const listToTree = <T = any>(list: any[], config: Partial<TreeHelperConfig> = {}): T[] => {
   const conf = getConfig(config) as TreeHelperConfig
   const nodeMap = new Map()
@@ -35,6 +44,16 @@ export const listToTree = <T = any>(list: any[], config: Partial<TreeHelperConfi
   return result
 }
 
+/**
+ * 树形数据转一维数组
+ * @param tree 需要转换的树形数据
+ * @param config 树形的配置项
+ * @category Tree
+ * @example
+ * ``` typescript
+ * treeToList([{value: 1, id: 1, children: [{value: 2, pid: 1, id: 2}]}])
+ * ```
+ */
 export const treeToList = <T = any>(tree: any, config: Partial<TreeHelperConfig> = {}): T => {
   config = getConfig(config)
   const { children } = config