[ { "path": ".editorconfig", "content": "root = true\n\n[*]\ncharset = utf-8\nindent_style = space\nindent_size = 2\nend_of_line = lf\ninsert_final_newline = true\ntrim_trailing_whitespace = true" }, { "path": ".github/dependabot.yml", "content": "version: 2\nupdates:\n - package-ecosystem: \"github-actions\"\n directory: \"/\"\n schedule:\n interval: weekly\n day: sunday\n time: \"01:00\"\n labels:\n - scope:dependency\n target-branch: \"main\"\n" }, { "path": ".github/workflows/ci.yml", "content": "name: CI\non:\n pull_request:\n branches: [main]\n paths:\n - \"packages/**\"\n push:\n branches: [main]\n paths:\n - \"packages/**\"\n\npermissions:\n contents: read\n pull-requests: read\n\njobs:\n lint:\n if: github.repository == 'chaxus/ran'\n timeout-minutes: 30\n runs-on: ${{ matrix.os }}\n strategy:\n matrix:\n os: [ubuntu-latest]\n node_version: [20, 22]\n include:\n # Active LTS + other OS\n - os: macos-latest\n node_version: 22\n - os: windows-latest\n node_version: 22\n fail-fast: false\n name: \"Build&Test: node-${{ matrix.node_version }}, ${{ matrix.os }}\"\n steps:\n - uses: actions/checkout@v6\n with:\n fetch-depth: 0\n - uses: actions/setup-python@v6\n with:\n python-version: \"3.10\"\n\n - uses: pnpm/action-setup@v6\n name: Install pnpm\n id: pnpm-install\n with:\n version: 7\n run_install: false\n\n - name: Get pnpm store directory\n id: pnpm-cache\n shell: bash\n run: |\n echo \"STORE_PATH=$(pnpm store path)\" >> $GITHUB_OUTPUT\n\n - name: prepare\n run: pnpm pre\n\n - name: Install deps\n run: pnpm install\n\n - name: build\n run: pnpm run build\n\n - name: format\n run: pnpm run format\n\n - name: Lint\n run: pnpm run lint\n\n - name: Test\n run: pnpm run test\n" }, { "path": ".github/workflows/pages-build-site.yml", "content": "name: pages-build-site\non:\n push:\n branches:\n - main\n\npermissions:\n contents: write\n pages: write\n id-token: write\n\njobs:\n deploy:\n runs-on: ubuntu-latest\n steps:\n - name: Checkout\n uses: actions/checkout@v6\n\n - name: Install Node.js\n uses: actions/setup-node@v6\n with:\n node-version: 20\n\n - uses: pnpm/action-setup@v6\n name: Install pnpm\n id: pnpm-install\n with:\n version: 7\n run_install: false\n\n - name: Get pnpm store directory\n id: pnpm-cache\n shell: bash\n run: |\n echo \"STORE_PATH=$(pnpm store path)\" >> $GITHUB_OUTPUT\n\n - uses: actions/cache@v5\n name: Setup pnpm cache\n with:\n path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}\n key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}\n restore-keys: |\n ${{ runner.os }}-pnpm-store-\n\n - name: Install dependencies\n run: pnpm install\n\n - name: Build ranuts\n run: pnpm -F ranuts build\n\n - name: Build ranui\n run: pnpm -F ranui build\n\n - name: Build docs\n run: pnpm -F docs build\n\n - name: Deploy\n uses: peaceiris/actions-gh-pages@v4\n with:\n github_token: ${{ secrets.RAN_ACTIONS_TOKEN }}\n exclude_assets: \"\"\n publish_dir: packages/docs/.vitepress/dist\n" }, { "path": ".github/workflows/semantic-pull-request.yml", "content": "name: Semantic Pull Request\n\non:\n pull_request_target:\n types:\n - opened\n - edited\n - synchronize\n\npermissions:\n pull-requests: write\n contents: read\n\njobs:\n main:\n if: github.repository == 'chaxus/ran'\n runs-on: ubuntu-latest\n name: Semantic Pull Request\n steps:\n - name: Validate PR title\n uses: amannn/action-semantic-pull-request@v6\n env:\n GITHUB_TOKEN: ${{ secrets.RAN_ACTIONS_TOKEN }}\n" }, { "path": ".gitignore", "content": "# npm\nnode_modules\npackage-lock.json\nnpminstall-debug.log\n# common\n.temp\ncache\n# mac\n.DS_Store\n# eslint\n.eslintcache\n# vite\nvite.config.ts.timestamp*\nconfig.ts.timestamp*\ndist\n# ranui\n/test-results/\n/playwright-report/\n/playwright/.cache/\n# jscpd\nreport\n# tesseract\n*.traineddata\n" }, { "path": ".jscpd.json", "content": "{\n \"threshold\": 10,\n \"reporters\": [\"html\", \"console\"],\n \"ignore\": [\n \"**/__snapshots__/**\",\n \"**.config.ts\",\n \"**.md\",\n \"**.html\",\n \"tsconfig.json\",\n \"node_modules\",\n \"CMakeFiles\",\n \"**.txt\"\n ],\n \"absolute\": true,\n \"gitignore\": true\n}\n" }, { "path": ".prettierignore", "content": "dist/\nLICENSE.md\npnpm-lock.yaml\npnpm-workspace.yaml\nreport\npublic\nassets" }, { "path": ".prettierrc.json", "content": "{\n \"semi\": true,\n \"tabWidth\": 2,\n \"singleQuote\": true,\n \"printWidth\": 120,\n \"trailingComma\": \"all\",\n \"overrides\": [\n {\n \"files\": [\"*.json5\"],\n \"options\": {\n \"singleQuote\": false,\n \"quoteProps\": \"preserve\"\n }\n },\n {\n \"files\": [\"*.yml\"],\n \"options\": {\n \"singleQuote\": false\n }\n }\n ]\n}\n" }, { "path": ".vscode/c_cpp_properties.json", "content": "{\n \"configurations\": [\n {\n \"name\": \"Mac\",\n \"includePath\": [\n \"${workspaceFolder}/**\",\n // 需要设置环境变量 .conan2 的路径，一般是在当前用户目录下，比如 /Users/chaxus/.conan2\n // conan install 会将依赖库安装到这个目录下\n // 其中 echo $chaxus 可以查看环境变量 chaxus 的值\n // export chaxus=/path/to/chaxus 可以设置环境变量 chaxus 的值\n \"${env:chaxus}/.conan2/**\",\n \"/usr/local/include/**\",\n // 将 Emscripten 的头文件路径添加到 includePath 中\n \"/opt/homebrew/Cellar/emscripten/3.1.74/libexec/system/include/**\",\n \"/opt/homebrew/include/**\"\n ],\n \"defines\": [],\n \"macFrameworkPath\": [\"/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/System/Library/Frameworks\"],\n \"compilerPath\": \"/usr/bin/clang\",\n \"cStandard\": \"c17\",\n \"cppStandard\": \"c++17\",\n \"intelliSenseMode\": \"macos-clang-x64\",\n \"configurationProvider\": \"ms-vscode.makefile-tools\"\n }\n ],\n \"version\": 4\n}\n" }, { "path": ".vscode/launch.json", "content": "{\n // 使用 IntelliSense 了解相关属性。\n // 悬停以查看现有属性的描述。\n // 欲了解更多信息，请访问：https://go.microsoft.com/fwlink/?linkid=830387\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"type\": \"node\",\n \"request\": \"launch\",\n \"name\": \"Launch Program\",\n \"skipFiles\": [\"/**\"],\n \"program\": \"${workspaceFolder}/packages/ranuts/test/write-file.spec.ts\",\n \"outFiles\": [\"${workspaceFolder}/**/*.js\"]\n }\n ]\n}\n" }, { "path": ".vscode/markdown.code-snippets", "content": "{\n // Place your ran 工作区 snippets here. Each snippet is defined under a snippet name and has a scope, prefix, body and\n // description. Add comma separated ids of the languages where the snippet is applicable in the scope field. If scope\n // is left empty or omitted, the snippet gets applied to all languages. The prefix is what is\n // used to trigger the snippet and the body will be expanded and inserted. Possible variables are:\n // $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders.\n // Placeholders with the same ids are connected.\n // Example:\n // \"Print to console\": {\n // \t\"scope\": \"javascript,typescript\",\n // \t\"prefix\": \"log\",\n // \t\"body\": [\n // \t\t\"console.log('$1');\",\n // \t\t\"$2\"\n // \t],\n // \t\"description\": \"Log output to console\"\n // }\n \"生成参考文献的角标\": {\n \"scope\": \"markdown\",\n \"prefix\": \"sup\",\n \"body\": [\"[[$2]]($1)。\"],\n \"description\": \"生成参考文献的角标\",\n },\n \"生成链接\": {\n \"scope\": \"markdown\",\n \"prefix\": \"[]\",\n \"body\": [\"[$2]($1)。\"],\n \"description\": \"生成链接\",\n },\n \"生成图片引用\": {\n \"scope\": \"markdown\",\n \"prefix\": \"[]\",\n \"body\": [\"![$2]($1)。\"],\n \"description\": \"生成图片引用\",\n },\n}\n" }, { "path": ".vscode/ranui-components.code-snippets", "content": "{\n // Place your ran 工作区 snippets here. Each snippet is defined under a snippet name and has a scope, prefix, body and\n // description. Add comma separated ids of the languages where the snippet is applicable in the scope field. If scope\n // is left empty or omitted, the snippet gets applied to all languages. The prefix is what is\n // used to trigger the snippet and the body will be expanded and inserted. Possible variables are:\n // $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders.\n // Placeholders with the same ids are connected.\n // Example:\n // \"Print to console\": {\n // \t\"scope\": \"javascript,typescript\",\n // \t\"prefix\": \"log\",\n // \t\"body\": [\n // \t\t\"console.log('$1');\",\n // \t\t\"$2\"\n // \t],\n // \t\"description\": \"Log output to console\"\n // }\n \"print component\": {\n \"scope\": \"javascript,typescript\",\n \"prefix\": \"tfc\",\n \"body\": [\n \"function Component() {\",\n \" const template = document.createElement('template');\",\n \" const slot = document.createElement('slot');\",\n \" const div = document.createElement('div');\",\n \" div.setAttribute('class', 'class');\",\n \" slot.setAttribute('name', 'name');\",\n \" div.appendChild(slot);\",\n \" template.appendChild(div);\",\n \" class CustomElement extends HTMLElement {\",\n \" static get observedAttributes() { return ['disabled'] }\",\n \" _div: HTMLElement;\",\n \" constructor() {\",\n \" super();\",\n \" this._div = div.cloneNode(true) as HTMLElement\",\n \" const shadowRoot = this.attachShadow({ mode: 'closed' });\",\n \" shadowRoot.appendChild(this._div);\",\n \" }\",\n \" connectedCallback() {\",\n \"\",\n \" }\",\n \" disconnectCallback() {\",\n \"\",\n \" }\",\n \" attributeChangedCallback (name:string, oldValue:string, newValue:string) {\",\n \"\",\n \" }\",\n \" }\",\n \"window.customElements.define('r-$1', CustomElement)\",\n \"}\",\n \"export default Component()\",\n // $通过tab切换\n ],\n \"description\": \"ranui component template\",\n },\n \"Print sort function\": {\n \"scope\": \"javascript,typescript\",\n \"prefix\": \"sf\",\n \"body\": [\"const $1 = ($2) => {\", \"\", \"}\", \"\", \"export default $1\"],\n \"description\": \"Log output to console\",\n },\n \"Print to return\": {\n \"scope\": \"javascript,typescript\",\n \"prefix\": \"rt\",\n \"body\": [\"return\"],\n \"description\": \"Log output to console\",\n },\n \"Print to for\": {\n \"scope\": \"javascript,typescript\",\n \"prefix\": \"for\",\n \"body\": [\"for(let i = 0; i < $1; i++) {\", \"\", \"}\"],\n \"description\": \"Log output to console\",\n },\n}\n" }, { "path": ".vscode/settings.json", "content": "{\n \"cSpell.words\": [\n \"abilitys\",\n \"Alloc\",\n \"allowclear\",\n \"ANALYSE\",\n \"analysed\",\n \"binarystring\",\n \"bottombar\",\n \"brotli\",\n \"ccall\",\n \"chaxus\",\n \"classname\",\n \"colorpicker\",\n \"componentization\",\n \"cond\",\n \"cout\",\n \"Crossentropy\",\n \"cstring\",\n \"cwrap\",\n \"dataavailable\",\n \"denormalise\",\n \"Deoptimization\",\n \"DOMAPI\",\n \"dropdownclass\",\n \"embin\",\n \"Embind\",\n \"emcc\",\n \"Emscripten\",\n \"endl\",\n \"esbuild\",\n \"exceljs\",\n \"GLSL\",\n \"HEAPF\",\n \"HEAPU\",\n \"IIFE\",\n \"iostream\",\n \"katex\",\n \"KEEPALIVE\",\n \"keyof\",\n \"lembind\",\n \"lerp\",\n \"localstorage\",\n \"malloc\",\n \"maxlength\",\n \"maxrows\",\n \"memset\",\n \"Metiral\",\n \"minrows\",\n \"normalise\",\n \"normalised\",\n \"nullptr\",\n \"nums\",\n \"originjs\",\n \"Ovride\",\n \"pacman\",\n \"pagefind\",\n \"picocolors\",\n \"playsinline\",\n \"preinstall\",\n \"progressbar\",\n \"pthread\",\n \"PTHREADS\",\n \"RAII\",\n \"ranite\",\n \"rankey\",\n \"ranloadedmetadata\",\n \"ranlog\",\n \"ranml\",\n \"ranpack\",\n \"ranui\",\n \"ranuireact\",\n \"ranuts\",\n \"Reactified\",\n \"Sankey\",\n \"scatterplot\",\n \"showcount\",\n \"simplefy\",\n \"skipsvgo\",\n \"slotchange\",\n \"sqft\",\n \"struct\",\n \"tabpane\",\n \"tailwindcss\",\n \"tesseract\",\n \"tfjs\",\n \"tfvis\",\n \"TOTP\",\n \"treeshake\",\n \"Treeshaking\",\n \"TTFB\",\n \"typeof\",\n \"vitepress\",\n \"vnode\",\n \"vnodes\",\n \"wasmjieba\",\n \"xlabels\"\n ],\n \"liveServer.settings.port\": 5556,\n \"files.associations\": {\n \"*.cjson\": \"jsonc\",\n \"*.wxss\": \"css\",\n \"*.wxs\": \"javascript\",\n \"vips.h\": \"c\",\n \"stdio.h\": \"c\",\n \"gmodule.h\": \"c\",\n \"glib.h\": \"c\",\n \"image_processing.h\": \"c\"\n },\n \"cmake.ignoreCMakeListsMissing\": true\n}\n" }, { "path": ".vscode/ts.json.code-snippets", "content": "{\n // Place your ran 工作区 snippets here. Each snippet is defined under a snippet name and has a scope, prefix, body and\n // description. Add comma separated ids of the languages where the snippet is applicable in the scope field. If scope\n // is left empty or omitted, the snippet gets applied to all languages. The prefix is what is\n // used to trigger the snippet and the body will be expanded and inserted. Possible variables are:\n // $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders.\n // Placeholders with the same ids are connected.\n // Example:\n // \"Print to console\": {\n // \t\"scope\": \"javascript,typescript\",\n // \t\"prefix\": \"log\",\n // \t\"body\": [\n // \t\t\"console.log('$1');\",\n // \t\t\"$2\"\n // \t],\n // \t\"description\": \"Log output to console\"\n // }\n \"Print to console\": {\n \"scope\": \"javascript,typescript\",\n \"prefix\": \"clg\",\n \"body\": [\"console.log('$1');\"],\n \"description\": \"Log output to console\",\n },\n \"web components class\": {\n \"scope\": \"typescript\",\n \"prefix\": \"wc\",\n \"body\": [\n \"import { isDisabled } from '@/utils/index';\",\n \"\",\n \"class Option extends HTMLElement {\",\n \" _option: HTMLDivElement;\",\n \" _optionContent: HTMLDivElement;\",\n \" _shadowDom: ShadowRoot;\",\n \" _slot: HTMLSlotElement;\",\n \" static get observedAttributes() {\",\n \" return ['disabled', 'sheet', 'value'];\",\n \" }\",\n \" constructor() {\",\n \" super();\",\n \" this._slot = document.createElement('slot');\",\n \" this._option = document.createElement('div');\",\n \" this._optionContent = document.createElement('div');\",\n \" this._optionContent.appendChild(this._slot);\",\n \" this._option.appendChild(this._optionContent);\",\n \" const shadowRoot = this.attachShadow({ mode: 'closed' });\",\n \" this._shadowDom = shadowRoot;\",\n \" shadowRoot.appendChild(this._option);\",\n \" }\",\n \" get sheet() {\",\n \" return this.getAttribute('sheet');\",\n \" }\",\n \" set sheet(value) {\",\n \" this.setAttribute('sheet', value || '');\",\n \" }\",\n \" get disabled() {\",\n \" return isDisabled(this);\",\n \" }\",\n \" set disabled(value: boolean | string | undefined | null) {\",\n \" if (!value || value === 'false') {\",\n \" this.removeAttribute('disabled');\",\n \" } else {\",\n \" this.setAttribute('disabled', '');\",\n \" }\",\n \" }\",\n \" handlerExternalCss() {\",\n \" if (this.sheet) {\",\n \" try {\",\n \" const sheet = new CSSStyleSheet();\",\n \" sheet.insertRule(this.sheet);\",\n \" this._shadowDom.adoptedStyleSheets = [sheet];\",\n \" } catch (error) {\",\n \" console.error(\",\n \" `Failed to parse the rule in CSSStyleSheet: ${this.sheet}`\",\n \" );\",\n \" }\",\n \" }\",\n \" }\",\n \" connectedCallback() {}\",\n \" disconnectCallback() {}\",\n \" attributeChangedCallback(name: string, oldValue: string, newValue: string) {\",\n \" if (name === 'disabled' && this._option) {\",\n \" if (!newValue || newValue === 'false') {\",\n \" this._option.setAttribute('disabled', '');\",\n \" } else {\",\n \" this._option.removeAttribute('disabled');\",\n \" }\",\n \" }\",\n \" if (name === 'sheet' && this._shadowDom && oldValue !== newValue)\",\n \" this.handlerExternalCss();\",\n \" }\",\n \"}\",\n ],\n \"description\": \"generate web components ts code\",\n },\n}\n" }, { "path": "LICENSE", "content": "MIT License\n\nCopyright (c) 2023 chaxus\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" }, { "path": "SECURITY.md", "content": "# Security Policy\n\n## Supported Versions\n\nUse this section to tell people about which versions of your project are\ncurrently being supported with security updates.\n\n| Version | Supported |\n| ------- | ------------------ |\n| 5.1.x | :white_check_mark: |\n| 5.0.x | :x: |\n| 4.0.x | :white_check_mark: |\n| < 4.0 | :x: |\n\n## Reporting a Vulnerability\n\nUse this section to tell people how to report a vulnerability.\n\nTell them where to go, how often they can expect to get an update on a\nreported vulnerability, what to expect if the vulnerability is accepted or\ndeclined, etc.\n" }, { "path": "bin/build.sh", "content": "npx pnpm -F ranuts build && pnpm -F ranui build && pnpm -F docs build" }, { "path": "bin/clean.sh", "content": "\nrm -rf $(pnpm store path)\nrm -rf node_modules\nrm -rf packages/ranui/node_modules/\nrm -rf packages/ranuts/node_modules/\nrm -rf packages/docs/node_modules/\nrm -rf packages/ranite/node_modules/\nrm -rf packages/ml/node_modules/\nnpm cache clean --force\nrm -rf pnpm-lock.yaml" }, { "path": "bin/install.sh", "content": "# 子package安装\npnpm i [package] -r --filter smarty-ui-vite\n# 或者 直接在 ranui 目录下\npnpm i [package]\n# 安装 workspace 中\npnpm i [package] -w\n# 检查只能用pnpm安装，用于workspace\n`\"preinstall\": \"npx only-allow pnpm\"`\n# Monorepo\n" }, { "path": "bin/lint.sh", "content": "\nbin=./node_modules/.bin\n$bin/prettier --check --cache .\n$bin/eslint --cache . && $bin/prettier --check --cache .\n# before lint, make sure all packages are built\n# pnpm build\npnpm -F docs tsc\npnpm -F image-process tsc\npnpm -F ml tsc\npnpm -F ranui tsc\npnpm -F ranuts tsc\npnpm -F solidity tsc\n# pnpm -F read tsc\n# $bin/tsc --noEmit\n# npm run lint:es && npm run lint:prettier\n" }, { "path": "bin/nvm.sh", "content": "nvm alias default node\nnvm use node\n" }, { "path": "bin/preinstall.sh", "content": "# @tensorflow/tfjs-node in github actions\npython3 --version\nnode --version " }, { "path": "bin/test.sh", "content": "pnpm -F docs tsc\npnpm -F image-process tsc\npnpm -F ml tsc\npnpm -F ranui tsc\npnpm -F ranuts tsc\npnpm -F solidity tsc\npnpm -F ranuts test\npnpm -F ranuts build\n# pnpm -F ranui test\n" }, { "path": "eslint.config.js", "content": "// @ts-check\nimport { builtinModules } from 'node:module';\nimport eslint from '@eslint/js';\nimport pluginN from 'eslint-plugin-n';\nimport pluginImportX from 'eslint-plugin-import-x';\nimport pluginRegExp from 'eslint-plugin-regexp';\nimport tseslint from 'typescript-eslint';\nimport globals from 'globals';\n\n// Some rules work better with typechecking enabled, but as enabling it is slow,\n// we only do so when linting in IDEs for now. If you want to lint with typechecking\n// explicitly, set this to `true` manually.\nconst shouldTypeCheck = typeof process.env.VSCODE_PID === 'string';\n\nexport default tseslint.config(\n {\n ignores: [\n 'packages/solidity/**',\n '**/dist/**',\n '**/report/**',\n '**/assets/**',\n '**/temp/**',\n '**/public/**',\n '**/cache/**',\n '**/*.snap',\n ],\n },\n eslint.configs.recommended,\n ...tseslint.configs.recommended,\n ...tseslint.configs.stylistic,\n pluginRegExp.configs['flat/recommended'],\n {\n name: 'main',\n languageOptions: {\n parser: tseslint.parser,\n parserOptions: {\n sourceType: 'module',\n ecmaVersion: 2022,\n project: shouldTypeCheck ? ['./packages/*/tsconfig.json', './packages/vite/src/*/tsconfig.json'] : undefined,\n },\n globals: {\n ...globals.es2021,\n ...globals.node,\n },\n },\n plugins: {\n n: pluginN,\n 'import-x': pluginImportX,\n },\n rules: {\n 'n/no-exports-assign': 'error',\n 'n/no-unpublished-bin': 'error',\n 'n/no-unsupported-features/es-builtins': 'error',\n 'n/no-unsupported-features/node-builtins': 'error',\n 'n/process-exit-as-throw': 'error',\n '@typescript-eslint/no-unused-expressions': 'off',\n '@typescript-eslint/no-namespace': 'off',\n 'n/hashbang': 'error',\n\n eqeqeq: 'off',\n 'no-debugger': ['error'],\n 'no-empty': ['warn', { allowEmptyCatch: true }],\n 'no-process-exit': 'off',\n 'prefer-const': [\n 'warn',\n {\n destructuring: 'all',\n },\n ],\n\n 'n/no-missing-require': [\n 'error',\n {\n // for try-catching yarn pnp\n allowModules: ['pnpapi', 'vite'],\n tryExtensions: ['.ts', '.js', '.jsx', '.tsx', '.d.ts'],\n },\n ],\n 'n/no-extraneous-import': [\n 'error',\n {\n allowModules: ['vite', 'less', 'sass', 'sass-embedded', 'lightningcss', 'vitest', 'unbuild'],\n },\n ],\n 'n/no-extraneous-require': [\n 'error',\n {\n allowModules: ['vite'],\n },\n ],\n\n '@typescript-eslint/ban-ts-comment': 'error',\n '@typescript-eslint/no-unsafe-function-type': 'off',\n '@typescript-eslint/explicit-module-boundary-types': ['error', { allowArgumentsExplicitlyTypedAsAny: true }],\n '@typescript-eslint/no-empty-function': ['error', { allow: ['arrowFunctions'] }],\n '@typescript-eslint/no-empty-object-type': ['error', { allowInterfaces: 'with-single-extends' }],\n '@typescript-eslint/no-empty-interface': 'off',\n '@typescript-eslint/no-explicit-any': 'off',\n 'no-extra-semi': 'off',\n '@typescript-eslint/no-extra-semi': 'off', // conflicts with prettier\n '@typescript-eslint/no-inferrable-types': 'off',\n '@typescript-eslint/no-unused-vars': [\n 'error',\n {\n args: 'all',\n argsIgnorePattern: '^_',\n caughtErrors: 'all',\n caughtErrorsIgnorePattern: '^_',\n destructuredArrayIgnorePattern: '^_',\n varsIgnorePattern: '^_',\n ignoreRestSiblings: true,\n },\n ],\n '@typescript-eslint/no-require-imports': 'off',\n '@typescript-eslint/consistent-type-imports': [\n 'error',\n { prefer: 'type-imports', disallowTypeAnnotations: false },\n ],\n // disable rules set in @typescript-eslint/stylistic which conflict with current code\n // we should discuss if we want to enable these as they encourage consistent code\n '@typescript-eslint/array-type': 'off',\n '@typescript-eslint/consistent-type-definitions': 'off',\n '@typescript-eslint/prefer-for-of': 'off',\n '@typescript-eslint/prefer-function-type': 'off',\n\n 'import-x/no-nodejs-modules': ['error', { allow: builtinModules.map((mod) => `node:${mod}`) }],\n 'import-x/no-duplicates': 'error',\n 'import-x/order': 'error',\n 'sort-imports': [\n 'error',\n {\n ignoreCase: false,\n ignoreDeclarationSort: true,\n ignoreMemberSort: false,\n memberSyntaxSortOrder: ['none', 'all', 'multiple', 'single'],\n allowSeparatedGroups: false,\n },\n ],\n\n 'regexp/prefer-regexp-exec': 'error',\n 'regexp/prefer-regexp-test': 'error',\n // in some cases using explicit letter-casing is more performant than the `i` flag\n 'regexp/use-ignore-case': 'off',\n },\n },\n {\n name: 'disables/playground',\n files: ['playground/**/*.?([cm])[jt]s?(x)', 'docs/**/*.?([cm])[jt]s?(x)'],\n rules: {\n 'n/no-extraneous-import': 'off',\n 'n/no-extraneous-require': 'off',\n 'n/no-missing-import': 'off',\n 'n/no-missing-require': 'off',\n 'n/no-unsupported-features/es-builtins': 'off',\n 'n/no-unsupported-features/node-builtins': 'off',\n '@typescript-eslint/explicit-module-boundary-types': 'off',\n '@typescript-eslint/no-unused-expressions': 'off',\n '@typescript-eslint/no-unused-vars': 'off',\n 'no-undef': 'off',\n 'no-empty': 'off',\n 'no-constant-condition': 'off',\n '@typescript-eslint/no-empty-function': 'off',\n },\n },\n {\n name: 'disables/playground/tsconfig-json',\n files: [\n 'playground/tsconfig-json/**/*.?([cm])[jt]s?(x)',\n 'playground/tsconfig-json-load-error/**/*.?([cm])[jt]s?(x)',\n ],\n ignores: ['**/__tests__/**'],\n rules: {\n '@typescript-eslint/ban-ts-comment': 'off',\n },\n },\n {\n name: 'disables/js',\n files: ['**/*.js', '**/*.mjs', '**/*.cjs'],\n rules: {\n '@typescript-eslint/explicit-module-boundary-types': 'off',\n },\n },\n {\n name: 'disables/dts',\n files: ['**/*.d.ts'],\n rules: {\n '@typescript-eslint/consistent-indexed-object-style': 'off',\n '@typescript-eslint/triple-slash-reference': 'off',\n },\n },\n {\n name: 'disables/test',\n files: ['**/__tests__/**/*.?([cm])[jt]s?(x)'],\n rules: {\n 'no-console': 'off',\n '@typescript-eslint/ban-ts-comment': 'off',\n },\n },\n {\n name: 'disables/typechecking',\n files: [\n '**/*.js',\n '**/*.mjs',\n '**/*.cjs',\n '**/*.d.ts',\n '**/*.d.cts',\n '**/__tests__/**',\n 'docs/**',\n 'playground/**',\n 'scripts/**',\n 'vitest.config.ts',\n ],\n languageOptions: {\n parserOptions: {\n project: false,\n },\n },\n },\n);\n" }, { "path": "index.html", "content": "\n\n \n \n \n Sankey Diagram with Canvas\n \n \n\n \n \n\n \n \n\n" }, { "path": "package.json", "content": "{\n \"name\": \"@ran/monorepo\",\n \"version\": \"1.0.0\",\n \"description\": \"Monorepo\",\n \"type\": \"module\",\n \"engines\": {\n \"node\": \">=23.10.0\"\n },\n \"scripts\": {\n \"pre\": \"sh ./bin/preinstall.sh\",\n \"preinstall\": \"npx only-allow pnpm\",\n \"clean\": \"sh ./bin/clean.sh\",\n \"build\": \"sh ./bin/build.sh\",\n \"test\": \"sh ./bin/test.sh\",\n \"lint\": \"sh ./bin/lint.sh\",\n \"lint:es\": \"eslint --cache .\",\n \"lint:fix\": \"eslint --cache --fix\",\n \"lint:prettier\": \"prettier --check --cache .\",\n \"format\": \"prettier --write --cache .\",\n \"cpd\": \"jscpd ./packages\"\n },\n \"homepage\": \"https://chaxus.github.io/ran/\",\n \"keywords\": [],\n \"author\": \"\",\n \"license\": \"MIT\",\n \"devDependencies\": {\n \"@eslint/js\": \"^9.39.1\",\n \"@types/node\": \"^24.10.1\",\n \"@typescript-eslint/parser\": \"^8.46.4\",\n \"eslint\": \"^9.39.1\",\n \"eslint-plugin-import-x\": \"^4.16.1\",\n \"eslint-plugin-n\": \"^17.23.1\",\n \"eslint-plugin-regexp\": \"^2.10.0\",\n \"jscpd\": \"^4.0.5\",\n \"prettier\": \"^3.6.2\",\n \"terser\": \"^5.44.1\",\n \"typescript\": \"^5.9.3\",\n \"typescript-eslint\": \"^8.46.4\",\n \"vite\": \"^6.4.1\",\n \"vite-plugin-dts\": \"^4.5.4\",\n \"vitest\": \"^4.0.9\",\n \"vue\": \"^3.5.24\",\n \"vue-tsc\": \"^3.1.3\"\n },\n \"dependencies\": {\n \"globals\": \"^16.5.0\",\n \"ranui\": \"0.1.10-alpha-27\"\n },\n \"pnpm\": {\n \"ignoredBuiltDependencies\": [\n \"fsevents\",\n \"keccak\",\n \"secp256k1\"\n ]\n }\n}\n" }, { "path": "packages/cpro/package.json", "content": "{\n \"name\": \"cpro\",\n \"version\": \"1.0.0\",\n \"description\": \"\",\n \"main\": \"index.js\",\n \"scripts\": {\n \"test\": \"echo \\\"Error: no test specified\\\" && exit 1\"\n },\n \"keywords\": [],\n \"author\": \"\",\n \"license\": \"ISC\"\n}\n" }, { "path": "packages/cpro/readme.md", "content": "# C++\n\n如果要为 macOS 进行 C++ 开发，建议安装 Clang 编译器。只需在“终端”窗口中运行以下命令即可安装命令行开发人员工具：\n\n```sh\nxcode-select --install\n```\n\n然后，要验证已安装 clang，请在“终端”窗口中运行以下命令。你应该会看到一条消息，其中包含有关所使用的 Clang 版本的信息。\n\n```sh\nclang --version\n```\n\n```c++\n\n#include\n\nusing namespace std;\n\nint main(){\n cout << \"Hello~\" << endl;\n return 0;\n}\n\n```\n\n命令行执行：\n\n```sh\nclang++ main.cpp\n# if meet some error like this: error: non-aggregate type 'vector' cannot be initialized with an initializer list\n# g++ -std=c++11\n./a.out\n```\n\n# WebAssembly\n\n官网：\n\nMac 安装 `Emscripten`\n\n```sh\nbrew install emscripten\n```\n\n安装完成后测试是否存在\n\n```sh\nemcc -v\n```\n\n编译 `C++` 代码\n\n```sh\nemcc main.cpp\n```\n\n命令成功执行后，你会发现 `main.cpp` 同级目录下会生成两个文件：`a.out.wasm` 和 `a.out.js`。其中，`a.out.wasm` 就是我们想要的 `Wasm` 模块。\n\n```sh\nnode a.out.js\n```\n\n`Node.js` 是支持 `Wasm` 模块的（自 `Node.js 8` 开始）。\n\n如果你希望到浏览器环境下测试文件，那么你可以在命令行下使用如下指令编译我们的 `C++` 代码：\n\n```sh\nemcc main.cpp -o main.html\n```\n\n命令成功执行后，`main.cpp` 同级目录下会再多出三个文件：`main.wasm`、`main.js` 和 `main.html`。你可以用`Live Server`打开 `main.html` 文件，就能看到结果了：\n\n![](./assets//images/emsc-web-preview.jpg)\n\n## 调试 WebAssembly\n\n我们可以在编译 `WebAssembly` 的时候加入 `-v` 参数来让 `Emscripten` 为我们输出更多编译信息，以辅助我们发现 `C++` 代码中的问题。\n\n如果你想在运行期调试 `WebAssembly` 的代码，那么你需要使用如下指令重新编译 `WebAssembly` 模块以让你的 `.wasm` 文件包含调试信息：\n\n```sh\nemcc -g main.cpp -o main.html\n```\n\n参数解释：\n\n- `-g`: 编译 + 链接，同时保留调试信息。当编译为目标文件时，这与 Clang 和 gcc 中的相同，它将 DWARF 调试信息添加到目标文件中。\n- `-o`: 链接可执行文件时，目标文件扩展名定义要生成的输出类型，默认是 `JavaScript`。如果指定是`html`,会生成一个`html`加`JavaScript`的可运行文件。\n\n接着你需要为你的谷歌浏览器安装一个插件 [`C/C++ DevTools Support (DWARF)`](https://chrome.google.com/webstore/detail/cc%20%20-devtools-support-dwa/pdcpmagijalfljmkmjngeonclgbbannb) ，这是 `Chrome DevTools` 开发团队为开发者提供的专门用于调试 `WebAssembly` 的浏览器插件，注意安装过程中要保持良好的网络环境。\n\n![](./assets/images/emsc-chrome-tools.jpg)\n\n安装完成后，打开 `Chrome` 浏览器的调试工具 `DevTools`，点击设置按钮（⚙），打开调试工具的设置面板，勾选实验选项卡下的 `WebAssembly Debugging: Enable DWARF support` 选项。\n\n![](./assets/images/emsc-chrome-setting.jpg)\n\n接着退回到 `DevTools` 主面板，把你的源码路径添加到 `DevTools` 的文件系统中，然后在 `main.cpp` 中下一个断点，刷新 `main.html` 页面，你会发现刚刚下的断点已经命中了，而且调用堆栈也会显示在 `DevTools` 右侧的面板中，如下图所示：\n\n![](./assets/images/emsc-chrome-debug.jpg)\n\n## C++ 与 JS 的交互\n\n### ccall\n\n如果需要调用一个在 C 语言自定义的函数，你可以使用 Emscripten 中的 ccall() 函数，以及 EMSCRIPTEN_KEEPALIVE 声明\n\n> Emscripten 会消除未从编译代码中调用的函数的死代码。虽然这确实最大限度地减少了代码大小，但它可以删除您计划自己调用的函数（在已编译的代码之外）。比如通过 EMSCRIPTEN_KEEPALIVE 和 EXPORTED_FUNCTIONS 去指定需要导出的函数。EMSCRIPTEN_KEEPALIVE 的作用是告诉编译器和链接器保留符号并将其导出，就像将其添加到 EXPORTED_FUNCTIONS 中一样。\n\n默认情况下，Emscripten 生成的代码只会调用 main() 函数，其他的函数将被视为无用代码。在一个函数名之前添加 EMSCRIPTEN_KEEPALIVE 能够防止这样的事情发生。你需要导入 emscripten.h 库来使用 EMSCRIPTEN_KEEPALIVE。\n\nEMSCRIPTEN_KEEPALIVE:\n\n```c++\n\n// EMSCRIPTEN_KEEPALIVE\n\nvoid EMSCRIPTEN_KEEPALIVE my_function() { printf(\"I am being kept alive\\n\"); }\n\n```\n\nEXPORTED_FUNCTIONS:\n\n```sh\n# EXPORTED_FUNCTIONS\n\nemcc -sEXPORTED_FUNCTIONS=_main,_my_func ...\n```\n\n> 如果您有 main() 函数，则\\_main 应该位于导出列表中，如该示例所示。否则，它将作为死代码被删除；默认情况下没有特殊的逻辑来保持 main() 的活动。\n\n```html\n\n\n\n```\n\n[](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.html)\n\n```sh\nemcc -v main.cpp -o main.html -sEXPORTED_FUNCTIONS=_quick_sort,_main -sEXPORTED_RUNTIME_METHODS=ccall,cwrap\n```\n\nEXPORTED_RUNTIME_METHODS 是 Emscripten 中一个用于指定哪些运行时方法可以在生成的 JavaScript 文件中被访问的选项。\n\n通过设置 EXPORTED_RUNTIME_METHODS，你可以控制哪些 Emscripten 运行时的 API 函数被导出，使其可以从生成的 JavaScript 文件中访问和调用。这对于需要在 JavaScript 中调用特定 Emscripten 提供的功能非常有用。\n\n假设你有一个简单的 C 文件 hello.c：\n\n```c++\n#include \n\nvoid say_hello() {\n printf(\"Hello, World!\\n\");\n}\n```\n\n你可以使用以下命令编译这个文件，同时导出 cwrap 和 ccall 方法：\n\n```c++\nemcc hello.c -o hello.js -s EXPORTED_RUNTIME_METHODS=['cwrap','ccall']\n```\n\n在这个例子中，我们导出了 cwrap 和 ccall 方法，这两个方法在 Emscripten 中常用于从 JavaScript 调用 C 函数。生成的 hello.js 文件可以在浏览器中使用。\n\n接下来，你可以在 JavaScript 中这样使用这些导出的方法：\n\n```html\n\n\n \n Hello Emscripten\n \n \n \n \n \n\n```\n\n在这个例子中，我们通过 Module.cwrap 方法创建了一个 JavaScript 包装函数 sayHello，并调用了它。由于 say_hello 是一个无返回值且无参数的 C 函数，因此我们在 cwrap 中传入了 null 和一个空数组 []。\n\n使用 EXPORTED_RUNTIME_METHODS 可以确保 cwrap 和 ccall 方法在生成的 JavaScript 文件中被导出，并且可以在 JavaScript 中访问和使用这些方法。\n\n### Emscripten 运行时的 API 函数\n\nEmscripten 运行时的 API 函数是指在生成的 JavaScript 文件中提供的用于与编译后的 WebAssembly 或 asm.js 代码交互的函数。Emscripten 提供了多种运行时 API 函数，方便开发者在 JavaScript 中调用 C/C++ 代码，处理内存，进行文件系统操作等。\n\n下面是一些常用的 Emscripten 运行时 API 函数及其用途：\n\n#### 1. cwrap:\n\n- 用于创建一个 JavaScript 函数，该函数可以调用编译后的 WebAssembly 函数。\n- 语法：\n\n```js\nModule.cwrap('function_name', 'return_type', ['arg_type1', 'arg_type2', ...])\n```\n\n#### 2. ccall:\n\n- 用于直接调用编译后的 WebAssembly 函数。\n 语法：\n\n```js\nModule.ccall('function_name', 'return_type', ['arg_type1', 'arg_type2', ...], [arg1, arg2, ...])\n```\n\n#### 3. UTF8ToString:\n\n- 将指向 UTF-8 编码字符串的指针转换为 JavaScript 字符串。\n 语法：\n\n```js\nUTF8ToString(ptr);\n```\n\n#### 4. allocate:\n\n- 在 Emscripten 堆中分配内存。\n 语法：\n\n```js\nModule._malloc(size);\n```\n\n#### 5. HEAP8 / HEAP16 / HEAP32 / HEAPU8 / HEAPU16 / HEAPU32 / HEAPF32 / HEAPF64:\n\n- 直接访问 Emscripten 堆内存的视图，允许读取和写入不同类型的数据。\n 例如：Module.HEAP32[ptr >> 2] 读取 ptr 位置的 32 位整数。\n\nEmscripten 提供了一系列 API 函数和视图，用于直接访问和操作 WebAssembly 内存。这些 API 和视图在处理复杂的数据结构、字符串、数组等方面非常有用。下面是 allocate 和各种 HEAP 视图的用法。\n\nallocate 函数用于在 Emscripten 堆中分配内存。该函数在较新的 Emscripten 版本中已经不推荐使用，通常推荐使用 \\_malloc 代替。\n\n```js\n// 分配 1024 字节的内存\nvar ptr = Module._malloc(1024);\n\n// 使用完毕后释放内存\nModule._free(ptr);\n```\n\nHEAP 视图\nEmscripten 提供了多个 HEAP 视图，用于访问 WebAssembly 内存中的数据。这些视图本质上是 TypedArray，它们允许你读取和写入不同类型的数据。\n\n- HEAP8: 8-bit signed integer (Int8Array)\n- HEAPU8: 8-bit unsigned integer (Uint8Array)\n- HEAP16: 16-bit signed integer (Int16Array)\n- HEAPU16: 16-bit unsigned integer (Uint16Array)\n- HEAP32: 32-bit signed integer (Int32Array)\n- HEAPU32: 32-bit unsigned integer (Uint32Array)\n- HEAPF32: 32-bit floating point (Float32Array)\n- HEAPF64: 64-bit floating point (Float64Array)\n\n以下是一个完整的示例，展示如何使用 \\_malloc 分配内存，并使用 HEAPU8 视图操作数据：\n\n```c++\n#include \n#include \n\nEMSCRIPTEN_KEEPALIVE\nvoid set_memory(char* ptr, int size) {\n memset(ptr, 42, size); // 将内存区域设置为 42 (即 '*')\n}\n```\n\n编译：\n\n```sh\nemcc memory.c -o memory.js -s EXPORTED_RUNTIME_METHODS=['_malloc', '_free', 'ccall']\n```\n\nJavaScript 代码\n\n```html\n\n\n \n Emscripten Memory Example\n \n \n \n \n \n\n```\n\n更复杂的示例\n假设你需要传递一个数组到 C 函数，并且函数会修改这个数组。\n\nC 代码 (假设文件名为 array.c)\n\n```c++\n\n#include \n\nEMSCRIPTEN_KEEPALIVE\nvoid double_values(int* array, int size) {\n for (int i = 0; i < size; i++) {\n array[i] *= 2;\n }\n}\n\n```\n\n编译\n\n```sh\nemcc array.c -o array.js -s EXPORTED_RUNTIME_METHODS=['_malloc', '_free', 'ccall']\n```\n\nJavaScript 代码\n\n```html\n\n\n \n Emscripten Array Example\n \n \n \n \n \n\n```\n\n在这个示例中，我们分配了一块足够大的内存以存储一个整数数组，并使用 HEAP32 视图将 JavaScript 数组复制到 Emscripten 堆中。然后，我们调用 C 函数修改数组，并使用 HEAP32 视图读取修改后的数组。\n\n#### 6. addFunction:\n\n将 JavaScript 函数指针添加到 WebAssembly 表中，使其可以从 WebAssembly 代码中调用。\n\n语法：\n\n```js\nModule.addFunction(func, 'sig');\n```\n\n#### 7. removeFunction:\n\n- 从 WebAssembly 表中移除函数指针。\n 语法：\n\n```js\nModule.removeFunction(func_ptr);\n```\n\n下面是一个完整的示例，演示如何使用 addFunction 和 removeFunction：\n\n假设你有一个简单的 C 文件 call_js.c：\n\n```c++\n#include \n\n// 声明一个外部函数指针\ntypedef int (*func_ptr)(int, int);\n\nEM_JS(int, call_js_function, (func_ptr f, int a, int b), {\n return f(a, b);\n});\n\nint main() {\n return 0;\n}\n\n```\n\n编译这个文件：\n\n```sh\nemcc call_js.c -o call_js.js -s EXPORTED_RUNTIME_METHODS=['addFunction','removeFunction']\n```\n\n在 JavaScript 中调用这个函数：\n\n```html\n\n\n \n Emscripten addFunction Example\n \n \n \n \n \n\n```\n\n在这个示例中，我们首先定义了一个 JavaScript 函数 add，并使用 Module.addFunction 将其添加到 WebAssembly 表中。然后，我们调用 WebAssembly 函数 \\_call_js_function，传入函数指针和参数。最后，我们使用 Module.removeFunction 从 WebAssembly 表中移除了函数指针。\n\n#### 8. getValue 和 setValue:\n\n- 用于读取和写入 Emscripten 堆内存中的值。\n 语法：\n\n```js\nModule.getValue(ptr, type) 和 Module.setValue(ptr, value, type)\n```\n\ngetValue 和 setValue 是 Emscripten 提供的两个 API，用于读取和写入 WebAssembly 内存中的值。这些函数可以处理不同类型的数据，如整数、浮点数和指针。\n\ngetValue 用于从指定内存地址读取值。其语法如下：\n\n```js\nvar value = Module.getValue(ptr, type);\n```\n\nptr 是内存地址（指针）。\ntype 是值的类型，可以是 'i8', 'i16', 'i32', 'i64', 'float', 'double', 'i8*', 'i16*', 'i32\\*' 等。\n\nsetValue 用于向指定内存地址写入值。其语法如下：\n\nModule.setValue(ptr, value, type);\n\nptr 是内存地址（指针）。\nvalue 是要写入的值。\ntype 是值的类型，可以是 'i8', 'i16', 'i32', 'i64', 'float', 'double', 'i8*', 'i16*', 'i32\\*' 等。\n\n下面是一个示例，展示如何使用 getValue 和 setValue 读取和写入内存中的值。\n\n```c++\n#include \n\nEMSCRIPTEN_KEEPALIVE\nint get_value_from_memory(int* ptr) {\n return *ptr;\n}\n\nEMSCRIPTEN_KEEPALIVE\nvoid set_value_in_memory(int* ptr, int value) {\n *ptr = value;\n}\n```\n\n编译\n\n```sh\nemcc values.c -o values.js -s EXPORTED_RUNTIME_METHODS=['getValue', 'setValue', '_malloc', '_free']\n```\n\nJavaScript 代码\n\n```js\n\n\n\n Emscripten getValue and setValue Example\n\n\n \n \n\n\n```\n\n在这个示例中，我们分配了一块 4 字节的内存（用于存储一个 32 位整数），并使用 setValue 写入值 42，然后使用 getValue 读取这个值。接着，我们调用 C 函数 get_value_from_memory 来读取内存中的值，并调用 C 函数 set_value_in_memory 来修改内存中的值。最后，我们使用 getValue 再次读取修改后的值。\n\n假设你需要在 WebAssembly 中处理更复杂的数据结构，如结构体。你可以使用 getValue 和 setValue 来操作结构体的成员。\n\n```c++\n#include \n\ntypedef struct {\n int x;\n float y;\n} Point;\n\nEMSCRIPTEN_KEEPALIVE\nvoid set_point(Point* p, int x, float y) {\n p->x = x;\n p->y = y;\n}\n\nEMSCRIPTEN_KEEPALIVE\nvoid get_point(Point* p, int* x, float* y) {\n *x = p->x;\n *y = p->y;\n}\n```\n\n编译\n\n```sh\nemcc struct.c -o struct.js -s EXPORTED_RUNTIME_METHODS=['getValue', 'setValue', '_malloc', '_free', 'ccall']\n```\n\nJavaScript 代码\n\n```html\n\n\n \n Emscripten Struct Example\n \n \n \n \n \n\n```\n\n在这个示例中，我们使用 set_point 函数设置结构体 Point 的值，并使用 get_point 函数读取结构体的值。我们还展示了如何使用 getValue 和 setValue 操作结构体的成员。\n\n#### 9. FS (File System API):\n\n- 用于在 Emscripten 虚拟文件系统中操作文件。\n 常用方法包括：FS.createDataFile, FS.readFile, FS.writeFile, FS.unlink 等。\n\n#### 10. stackSave, stackRestore, stackAlloc:\n\n用于管理 Emscripten 堆栈指针，帮助分配和释放堆栈空间。\n语法：stackSave(), stackRestore(ptr), stackAlloc(size)\n\n以下是一个使用 ccall 和 UTF8ToString 的示例：\n\n```c++\n#include \n\nEMSCRIPTEN_KEEPALIVE\nconst char* get_hello() {\n return \"Hello from C!\";\n}\n```\n\n编译这个文件：\n\n```sh\nemcc hello.c -o hello.js -s EXPORTED_RUNTIME_METHODS=['ccall','UTF8ToString']\n```\n\n在 JavaScript 中调用这个函数：\n\n```html\n\n\n \n Hello Emscripten\n \n \n \n \n \n\n```\n\n这个例子展示了如何使用 Emscripten 运行时 API 函数 ccall 调用 C 函数，并使用 UTF8ToString 将返回的指针转换为 JavaScript 字符串。\n\n### cwrap\n\n`cwrap`的方式会更加简单\n\n```html\n\n\n\n```\n\n### Embind\n\nhttps://emscripten.org/docs/porting/connecting_cpp_and_javascript/embind.html?highlight=emscripten_bindings\n\n以下代码使用 EMSCRIPTEN_BINDINGS() 块将简单 C++ lerp() function() 公开给 JavaScript。\n\n```cpp\n// quick_example.cpp\n#include \n\nusing namespace emscripten;\n\nfloat lerp(float a, float b, float t) {\n return (1 - t) * a + t * b;\n}\n\nEMSCRIPTEN_BINDINGS(my_module) {\n function(\"lerp\", &lerp);\n}\n```\n\n为了使用 `embin` 编译上面的示例，我们使用 `bind` 选项调用 `emcc：`\n\n```sh\nemcc -lembind -o main.js main.cpp\n```\n\n生成的`main.js`文件可以作为节点模块或通过 `\n \n\n```\n\n绑定代码作为静态构造函数运行，并且仅当链接中包含对象文件时，静态构造函数才会运行，因此在为库文件生成绑定时，必须显式指示编译器包含对象文件。\n\n例如，要为一个假设的库生成绑定.a 编译 Emscripten 运行带有编译器标志的 --whole-archive emcc：\n\n```sh\nemcc -lembind -o library.js -Wl,--whole-archive library.a -Wl,--no-whole-archive\n```\n\n向 JavaScript 公开类需要更复杂的绑定语句。例如：\n\n```cpp\nclass MyClass {\n\npublic:\n MyClass(int x, std::string y)\n : x(x)\n , y(y)\n {}\n\n void incrementX() {\n ++x;\n }\n\n int getX() const { return x; }\n void setX(int x_) { x = x_; }\n\n static std::string getStringFromInstance(const MyClass& instance) {\n return instance.y;\n }\n\nprivate:\n int x;\n std::string y;\n};\n\n// Binding code\nEMSCRIPTEN_BINDINGS(my_class_example) {\n class_(\"MyClass\")\n .constructor()\n .function(\"incrementX\", &MyClass::incrementX)\n .property(\"x\", &MyClass::getX, &MyClass::setX)\n .class_function(\"getStringFromInstance\", &MyClass::getStringFromInstance)\n ;\n}\n```\n\n绑定块定义了临时 class\\_ 对象上的成员函数调用链（在 Boost.Python 中使用了相同的样式）。这些函数注册类、其 constructor() 、成员 function() 、class_function() （静态）和 property() .\n\n然后可以在 JavaScript 中创建和使用 的 MyClass 实例，如下所示：\n\n```js\nvar instance = new Module.MyClass(10, 'hello');\ninstance.incrementX();\ninstance.x; // 11\ninstance.x = 20; // 20\nModule.MyClass.getStringFromInstance(instance); // \"hello\"\ninstance.delete();\n```\n\n为了防止闭包编译器重命名上述示例代码中的符号，需要按如下方式重写：\n\n```js\nvar instance = new Module['MyClass'](10, 'hello');\ninstance['incrementX']();\ninstance['x']; // 11\ninstance['x'] = 20; // 20\nModule['MyClass']['getStringFromInstance'](instance); // \"hello\"\ninstance.delete();\n```\n\n请注意，只有优化程序看到的代码才需要这样做，例如，如 in --pre-js 或 上所述，或在 EM_ASM 或 EM_JS --post-js .对于未通过闭包编译器优化的其他代码，您无需进行此类更改。如果您在构建时没有 --closure 1 启用闭包编译器，则也不需要它。\n\n### clone\n\n在某些情况下，JavaScript 代码库的多个长期部分需要将同一 C++ 对象保留不同的时间。\n\n为了适应该用例，Emscripten 提供了一种引用计数机制，在该机制中，可以为同一底层 C++ 对象生成多个句柄。仅当删除所有句柄时，才会销毁对象。\n\nclone() JavaScript 方法返回一个新的句柄。它最终还必须与 delete() ：\n\n```js\nasync function myLongRunningProcess(x, milliseconds) {\n // sleep for the specified number of milliseconds\n await new Promise((resolve) => setTimeout(resolve, milliseconds));\n x.method();\n x.delete();\n}\n\nconst y = new Module.MyClass(); // refCount = 1\nmyLongRunningProcess(y.clone(), 5000); // refCount = 2\nmyLongRunningProcess(y.clone(), 3000); // refCount = 3\ny.delete(); // refCount = 2\n\n// (after 3000ms) refCount = 1\n// (after 5000ms) refCount = 0 -> object is deleted\n```\n\n基本类型的手动内存管理很繁重，因此 embind 提供了对值类型的支持。Value arrays 与 JavaScript 数组相互转换，并 value objects 相互转换和从 JavaScript 对象转换。\n\n### 总结\n\n```sh\nemcc -lembind -o main.js main.cpp -sEXPORTED_FUNCTIONS=_quick_sort,_main -sEXPORTED_RUNTIME_METHODS=ccall,cwrap\n```\n\n### 基于内存的方式\n\n1. 声明和分配内存\n 在 WebAssembly 中，内存是通过 WebAssembly.Memory 对象管理的。Emscripten 通常会自动处理内存分配，但你也可以手动管理。\n\n2. 在 C/C++ 中访问内存\n 在 C/C++ 代码中，你可以通过指针直接访问和操作内存。\n\n```c++\n#include \n#include \n\n// 简单的函数来设置内存中的数据\nextern \"C\" {\n EMSCRIPTEN_KEEPALIVE\n void set_memory(int offset, int value) {\n int *ptr = reinterpret_cast(offset);\n *ptr = value;\n }\n\n EMSCRIPTEN_KEEPALIVE\n int get_memory(int offset) {\n int *ptr = reinterpret_cast(offset);\n return *ptr;\n }\n}\n```\n\n3. 编译 C++ 代码\n\n使用 Emscripten 将上述代码编译为 WebAssembly 模块。\n\n```sh\nemcc memory_example.cpp -o memory_example.js -s EXPORTED_FUNCTIONS='[\"_set_memory\", \"_get_memory\"]' -s ALLOW_MEMORY_GROWTH=1\n```\n\n4. 在 JavaScript 中访问和操作内存\n\nEmscripten 会为你提供一个 HEAP 对象，可以用来直接访问 WebAssembly 模块的内存。常用的内存视图包括：\n\n- HEAP8: 8-bit signed integer array\n- HEAPU8: 8-bit unsigned integer array\n- HEAP16: 16-bit signed integer array\n- HEAPU16: 16-bit unsigned integer array\n- HEAP32: 32-bit signed integer array\n- HEAPU32: 32-bit unsigned integer array\n- HEAPF32: 32-bit floating-point array\n- HEAPF64: 64-bit floating-point array\n\n```html\n\n\n \n Memory Access Example\n \n \n \n \n \n\n```\n\n5. 更复杂的数据类型\n\n你可以使用 HEAP 对象来访问和操作更复杂的数据类型，例如结构体或数组。\n\n```c++\n#include \n#include \n\nstruct MyStruct {\n int a;\n float b;\n};\n\nextern \"C\" {\n EMSCRIPTEN_KEEPALIVE\n void set_struct(int offset, int a, float b) {\n MyStruct *ptr = reinterpret_cast(offset);\n ptr->a = a;\n ptr->b = b;\n }\n\n EMSCRIPTEN_KEEPALIVE\n void get_struct(int offset, int *a, float *b) {\n MyStruct *ptr = reinterpret_cast(offset);\n *a = ptr->a;\n *b = ptr->b;\n }\n}\n```\n\n编译命令\n\n```sh\nemcc struct_example.cpp -o struct_example.js -s EXPORTED_FUNCTIONS='[\"_set_struct\", \"_get_struct\"]' -s ALLOW_MEMORY_GROWTH=1\n```\n\nJS 代码：\n\n```html\n\n\n \n Struct Memory Access Example\n \n \n \n \n \n\n```\n\n通过这些步骤，你可以在 JavaScript 和 C/C++ 之间通过共享内存进行高效的通信。这种方法特别适合需要频繁交互或传递大量数据的场景。\n\n但也有一些限制和注意事项：\n\n1. 内存安全\n\n- 缓冲区溢出：在直接操作内存时，需要小心避免缓冲区溢出。错误的内存访问可能导致崩溃或不可预测的行为。\n- 类型安全：JavaScript 和 C/C++ 之间的数据类型可能不匹配。确保正确地处理和转换数据类型以避免错误。\n\n2. 内存对齐\n\n- 对齐要求：在操作内存时，确保数据对齐。例如，32 位整数需要 4 字节对齐，64 位浮点数需要 8 字节对齐。未对齐的内存访问可能导致性能下降或错误。\n\n3. 性能问题\n\n- 频繁的内存访问：尽管共享内存访问比函数调用更快，但频繁的内存读写仍可能带来性能开销。应尽量减少不必要的内存操作。\n\n- 内存分配和释放：频繁的内存分配和释放可能导致内存碎片，从而影响性能。\n\n4. 内存管理\n\n- 手动内存管理：需要手动管理内存的分配和释放。忘记释放分配的内存可能导致内存泄漏。\n- 固定内存大小：默认情况下，WebAssembly 内存大小是固定的，尽管可以配置增长，但需要额外的设置。\n\n5. 内存视图限制\n\n- 视图限制：WebAssembly 内存视图 (HEAP8, HEAP16, HEAP32, 等) 是基于 ArrayBuffer 的，需要注意视图的边界和大小。\n\n6. 数据转换\n\n- 字符串处理：C/C++ 中的字符串和 JavaScript 中的字符串处理方式不同。需要进行适当的转换。\n 从 C/C++ 到 JavaScript：使用 UTF8ToString。\n 从 JavaScript 到 C/C++：使用 stringToUTF8。\n\n7. 并发和线程\n\n- 线程安全：WebAssembly 目前支持共享内存和线程（使用 WebAssembly Threads），但需要小心处理并发和同步问题，以避免竞争条件和死锁。\n\n8. 调试和开发\n\n- 调试困难：直接操作内存可能使调试变得更加困难。需要仔细检查内存地址和数据，以确保正确性。\n- 可维护性：直接内存访问的代码可能比使用更高级别接口的代码更难维护和理解。\n\n示例代码中的改进建议\n\n- 内存对齐：确保在使用 malloc 分配内存时，对齐地址。例如，对于 32 位整数使用 HEAP32 视图时，确保地址是 4 的倍数。\n- 字符串转换：如果需要传递字符串，请使用 Emscripten 提供的工具函数。\n\n改进后的示例\n\n以下是一些改进建议：\n\nC++ 代码（改进内存对齐）\n\n```c++\n#include \n#include \n\n// 简单的函数来设置内存中的数据\nextern \"C\" {\n EMSCRIPTEN_KEEPALIVE\n void set_memory(int offset, int value) {\n if (offset % 4 != 0) return; // 检查对齐\n int *ptr = reinterpret_cast(offset);\n *ptr = value;\n }\n\n EMSCRIPTEN_KEEPALIVE\n int get_memory(int offset) {\n if (offset % 4 != 0) return 0; // 检查对齐\n int *ptr = reinterpret_cast(offset);\n return *ptr;\n }\n}\n\n```\n\nJavaScript 代码（改进内存对齐和字符串处理）\n\n```html\n\n\n \n Memory Access Example\n \n \n \n \n \n\n```\n\n通过注意上述限制和改进建议，你可以更高效和安全地在 JavaScript 和 WebAssembly（C/C++）之间通过共享内存进行通信。\n\n## 多线程\n\nWebAssembly 目前支持多线程，通过 SharedArrayBuffer 和 Web Workers 实现。Emscripten 提供了一些工具和支持来使多线程编程更加容易。以下是使用 Emscripten 和 WebAssembly 实现多线程的方法。\n\n前提条件\n\n确保在你的浏览器环境中启用了 SharedArrayBuffer，因为它是实现多线程的关键。\n\n设置 Emscripten 项目以支持多线程：\n\n- 编译时启用线程支持\n- 使用 Web Workers\n- 使用 pthread 库\n\n示例项目\n\n1. 创建一个 C++ 文件\n 假设你的 C++ 文件名为 threads_example.cpp。\n\n```c++\n#include \n#include \n#include \n\nvoid* thread_main(void* arg) {\n int* num = static_cast(arg);\n std::cout << \"Hello from thread! Argument: \" << *num << std::endl;\n return 0;\n}\n\nextern \"C\" {\n EMSCRIPTEN_KEEPALIVE\n void create_thread(int num) {\n pthread_t thread;\n int* arg = new int(num);\n pthread_create(&thread, nullptr, thread_main, arg);\n pthread_detach(thread);\n }\n}\n\n```\n\n2. 编译 C++ 文件\n 使用 Emscripten 编译文件，并启用线程支持。\n\n```sh\nemcc threads_example.cpp -o threads_example.js -s USE_PTHREADS=1 -s PTHREAD_POOL_SIZE=4 -s EXPORTED_FUNCTIONS='[\"_create_thread\"]' -s ALLOW_MEMORY_GROWTH=1\n```\n\n3. 创建 HTML 文件\n 创建一个 HTML 文件以加载和运行编译后的 WebAssembly 模块。\n\n```html\n\n\n \n WebAssembly Multithreading Example\n \n \n \n \n \n\n```\n\n说明：\n\nC++ 代码\n\n- pthread_create：用于创建新线程。\n- pthread_detach：分离线程，使其在完成后自动释放资源。\n- EMSCRIPTEN_KEEPALIVE：确保函数不会被编译器优化掉，使其在 JavaScript 中可用。\n\nJavaScript 代码\n\n- Module.onRuntimeInitialized：等待 WebAssembly 模块初始化完成。\n- Module.\\_create_thread：调用导出的 create_thread 函数创建新线程。\n\n多线程注意事项\n\n1. 线程安全：确保在多线程环境中正确处理数据竞争和同步问题。\n2. 共享内存：使用 SharedArrayBuffer 在线程之间共享内存。\n3. 性能开销：线程的创建和管理会带来一些性能开销，尽量避免频繁创建和销毁线程。\n4. 浏览器兼容性：确保你的浏览器支持 SharedArrayBuffer 和多线程 WebAssembly。\n\n示例代码扩展\n\n你可以扩展上述示例，使多个线程协作完成更复杂的任务。例如，实现一个简单的并行计算。\n\n扩展 C++ 代码\n\n```c++\n#include \n#include \n#include \n#include \n\nconst int num_threads = 4;\nint results[num_threads];\n\nvoid* thread_compute(void* arg) {\n int index = *static_cast(arg);\n results[index] = index * index; // 简单的计算任务\n return 0;\n}\n\nextern \"C\" {\n EMSCRIPTEN_KEEPALIVE\n void parallel_compute() {\n pthread_t threads[num_threads];\n std::vector args(num_threads);\n\n for (int i = 0; i < num_threads; ++i) {\n args[i] = i;\n pthread_create(&threads[i], nullptr, thread_compute, &args[i]);\n }\n\n for (int i = 0; i < num_threads; ++i) {\n pthread_join(threads[i], nullptr);\n }\n\n for (int i = 0; i < num_threads; ++i) {\n std::cout << \"Result from thread \" << i << \": \" << results[i] << std::endl;\n }\n }\n}\n\n```\n\n扩展 JavaScript 代码\n\n```js\n\n\n\n WebAssembly Multithreading Example\n \n\n\n \n\n\n\n```\n\n通过 Emscripten 和 WebAssembly，你可以利用多线程来提高性能和响应能力。确保处理好线程安全和同步问题，以避免数据竞争和其他多线程相关的问题。\n\n以下是一些关键点：\n\n1. 数据竞争和同步\n\n- 数据竞争：当多个线程同时访问和修改共享数据时，可能会出现数据竞争问题。这会导致不可预测的行为和错误。\n- 避免数据竞争：使用线程同步机制，例如互斥锁（mutex）、信号量（semaphore）和条件变量（condition variable）来保护共享数据。\n\n示例：使用互斥锁\n\n```c++\n#include \n#include \n#include \n\npthread_mutex_t mutex;\n\nvoid* thread_safe_increment(void* arg) {\n pthread_mutex_lock(&mutex);\n int* counter = static_cast(arg);\n (*counter)++;\n pthread_mutex_unlock(&mutex);\n return 0;\n}\n\nextern \"C\" {\n EMSCRIPTEN_KEEPALIVE\n void create_threads(int num_threads, int* counter) {\n pthread_t threads[num_threads];\n pthread_mutex_init(&mutex, nullptr);\n\n for (int i = 0; i < num_threads; ++i) {\n pthread_create(&threads[i], nullptr, thread_safe_increment, counter);\n }\n\n for (int i = 0; i < num_threads; ++i) {\n pthread_join(threads[i], nullptr);\n }\n\n pthread_mutex_destroy(&mutex);\n }\n}\n\n```\n\n2. 死锁\n\n- 死锁：当两个或多个线程相互等待对方释放资源时，会发生死锁，导致所有相关线程都被无限期阻塞。\n- 避免死锁：小心设计锁的获取顺序，避免嵌套锁定。尽量使用尝试锁（try-lock）而不是阻塞锁。\n\n3. 线程池\n\n- 线程池：创建和销毁线程开销较大，使用线程池可以重复利用线程，减少开销。\n- 实现线程池：通过预先创建一组线程，并将任务分配给这些线程执行。\n\n示例：简单线程池\n\n```c++\n#include \n#include \n#include \n#include \n\nconst int num_threads = 4;\npthread_t threads[num_threads];\nstd::queue task_queue;\npthread_mutex_t queue_mutex;\npthread_cond_t queue_cond;\n\nvoid* thread_main(void* arg) {\n while (true) {\n pthread_mutex_lock(&queue_mutex);\n while (task_queue.empty()) {\n pthread_cond_wait(&queue_cond, &queue_mutex);\n }\n auto task = task_queue.front();\n task_queue.pop();\n pthread_mutex_unlock(&queue_mutex);\n task();\n }\n return 0;\n}\n\nextern \"C\" {\n EMSCRIPTEN_KEEPALIVE\n void initialize_thread_pool() {\n pthread_mutex_init(&queue_mutex, nullptr);\n pthread_cond_init(&queue_cond, nullptr);\n\n for (int i = 0; i < num_threads; ++i) {\n pthread_create(&threads[i], nullptr, thread_main, nullptr);\n }\n }\n\n EMSCRIPTEN_KEEPALIVE\n void add_task(void (*task)()) {\n pthread_mutex_lock(&queue_mutex);\n task_queue.push(task);\n pthread_cond_signal(&queue_cond);\n pthread_mutex_unlock(&queue_mutex);\n }\n}\n\n```\n\n4. 资源管理\n\n- 资源泄漏：确保所有动态分配的资源在使用完毕后正确释放，包括内存、文件描述符和锁等。\n- 自动管理资源：使用智能指针（如 C++ 的 std::unique_ptr 和 std::shared_ptr）或 RAII（资源获取即初始化）模式。\n\n5. 性能开销\n\n- 线程切换：频繁的线程切换会导致性能下降。尽量减少不必要的线程创建和销毁。\n- 批量处理：将多个任务批量处理，以减少线程切换开销。\n\n6. 浏览器兼容性\n\n- 浏览器支持：确保目标浏览器支持 WebAssembly 多线程和 SharedArrayBuffer。一些旧版浏览器可能不支持这些特性。\n- 特性检测：在代码中检测浏览器是否支持 SharedArrayBuffer，并在不支持的情况下提供替代方案。\n\n7. 调试和测试\n\n- 调试工具：使用调试工具和日志记录来跟踪线程行为和问题。\n- 并发测试：进行并发测试以确保代码在多线程环境下的正确性和稳定性。\n\n8. 内存对齐\n\n- 内存对齐：确保内存对齐以提高性能和避免潜在的错误，特别是在访问共享内存时。\n\n示例总结\n\n通过以下 JavaScript 代码来初始化线程池并添加任务：\n\n```html\n\n\n \n WebAssembly Multithreading Example\n \n \n \n \n \n\n```\n\n通过注意上述多线程编程中的注意事项，可以有效地利用 WebAssembly 和 Emscripten 提供的多线程功能，实现高性能和高效的并发处理。确保正确处理数据竞争、同步和资源管理，以避免常见的多线程问题。\n\n[emcc 指令参考](https://emscripten.org/docs/tools_reference/settings_reference.html)\n" }, { "path": "packages/cpro/sum.cpp", "content": "#include \n\nusing namespace emscripten;\n\n//接收两个浮点型参数，返回一个字符串\nstd::string sum(double a,double b) {\n return std::to_string(a*b);\n}\n\n//公开一个方法给 JavaScript 访问\nEMSCRIPTEN_BINDINGS(myModule) {\n function(\"sum\", &sum);\n}\n" }, { "path": "packages/debug/koaStatic/index.ts", "content": "import path from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport Koa from 'koa';\nimport serve from 'koa-static';\nimport mount from 'koa-mount';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\nconst app = new Koa();\n\nconst PORT = 5555;\n\nconst STATIC_DIR = 'dist';\n\n// 设置正确的 MIME 类型\napp.use(async (ctx, next) => {\n if (ctx.path.endsWith('.js')) {\n ctx.type = 'application/javascript';\n } else if (ctx.path.endsWith('.mjs')) {\n ctx.type = 'application/javascript';\n } else if (ctx.path.endsWith('.json')) {\n ctx.type = 'application/json';\n } else if (ctx.path.endsWith('.css')) {\n ctx.type = 'text/css';\n }\n await next();\n});\n\napp.use(async (ctx, next) => {\n ctx.set('Cross-Origin-Opener-Policy', 'same-origin');\n ctx.set('Cross-Origin-Embedder-Policy', 'require-corp');\n await next();\n});\n\n// Serve static files from the 'dist' directory with /weread prefix\napp.use(mount('/weread', serve(path.join(__dirname, STATIC_DIR))));\n\n// 启动服务器\napp.listen(PORT, () => {\n console.log(`Server is running on http://localhost:${PORT}`);\n});\n\nexport default app;\n" }, { "path": "packages/debug/koaStatic/readme.md", "content": "# 静态服务\n\n用于排查一些本地启动没有问题，但是部署到线上环境就无法运行的问题\n\n有时候需要搭配 nginx 做反向代理域名映射，用于完整并彻底的模拟线上环境\n" }, { "path": "packages/debug/nginxconf/agency.conf", "content": "\nevents {\n worker_connections 1024;\n}\n\nhttp {\n server {\n listen 80;\n server_name trade-app.longbridge.xyz;\n\n location / {\n proxy_pass http://localhost:5555;\n proxy_http_version 1.1;\n proxy_set_header Upgrade $http_upgrade;\n proxy_set_header Connection 'upgrade';\n proxy_set_header Host $host;\n proxy_cache_bypass $http_upgrade;\n }\n }\n}\n\n" }, { "path": "packages/debug/nginxconf/readme.md", "content": "1. 使用命令行参数指定配置文件路径\n\n```sh\nnginx -c /path/to/your/nginx.conf\n```\n\n请注意，当您使用 -c 参数时，Nginx 将仅加载您指定的配置文件，而不会加载任何其他通过 include 指令包含的文件（除非这些 include 指令位于您指定的配置文件中）。因此，请确保您的自定义配置文件中包含了所有必要的设置和 include 指令。\n\n在启动之前，可以先通过`-t`测试一下：\n\n```sh\nnginx -t -c /path/to/your/nginx.conf\n```\n\n重启\n\n```sh\nnginx -s reload\n```\n\n另外，如果您已经运行了 Nginx 实例，并且想要更改其配置而无需完全停止并重新启动服务，您可以使用 nginx -s reload 命令，但前提是您的主配置文件（或您通过 -c 参数指定的配置文件）已经更改，并且 Nginx 能够重新加载这些更改。不过，请注意，nginx -s reload 命令不会直接接受 -c 参数来指定一个新的配置文件；它只会重新加载当前正在使用的配置文件（或您通过 Nginx 的启动脚本/服务管理器指定的配置文件）的更改。\n\n2. 配置本地 DNS 解析\n\n由于 nginx 配置的 server_name 往往是一个真实的域名，你的本地机器默认会尝试通过互联网解析它。为了让你在本地开发环境中测试反向代理，你需要确保当在本地机器上访问这个域名时，它会被解析到 127.0.0.1（即 localhost）。\n\n有几种方法可以实现这一点，包括修改 /etc/hosts 文件或在你的 DNS 服务器中设置条目（如果你正在使用本地 DNS 服务器）。\n\n```sh\ncat /etc/hosts\n```\n\n在文件末尾添加一行，将域名映射到 localhost：\n\n```sh\n127.0.0.1 server_name\n```\n\n保存并关闭文件。现在，当你尝试在浏览器中访问 server_name 域名时，请求应该会被转发到你的本地 localhost:5555。\n\n注意：确保 localhost:5555 上有一个正在运行的服务器，以便 Nginx 可以成功转发请求。\n\n3. 启动\n\n进入 Nginx 安装目录的 sbin 文件夹：通常 Nginx 的可执行文件位于/usr/local/nginx/sbin（具体路径可能因安装方式和操作系统而异）。\n执行重启命令：在 sbin 目录下，执行./nginx -s reload 命令。这条命令会优雅地重启 Nginx 服务，即不会立即关闭已经建立的连接，而是等待现有请求处理完成后，重新加载配置文件并启动新的工作进程。\n\n使用 brew 服务命令：\n\n```sh\nbrew services restart nginx\n```\n\n直接使用 Nginx 命令：\n\n你也可以直接使用 Nginx 的-s 参数来停止服务。有两种停止方式：\n\n快速停止（不等待处理完当前请求）：\n\n```sh\nsudo nginx -s stop\n```\n\n优雅停止（等待处理完当前请求后再停止）：\n\n```sh\nsudo nginx -s quit\n```\n\n4. 关闭\n\n进入 Nginx 安装目录的 sbin 文件夹（如果尚未进入）。\n执行关闭命令：可以使用./nginx -s stop 命令来快速停止 Nginx 服务，这将立即关闭所有连接。另外，./nginx -s quit 命令会等待所有请求处理完成后才停止服务，这是一种更优雅的关闭方式。\n\n在某些情况下，你可能需要手动停止 Nginx 服务。这通常涉及到找到 Nginx 的主进程号（PID），并使用 kill 命令发送相应的信号来停止进程。\n\n查找 Nginx 主进程的 PID：可以使用 ps 命令结合 grep 来查找，如：\n\n```sh\nps -ef | grep nginx\n```\n\n发送停止信号：根据找到的 PID，使用 kill 命令发送 TERM（快速停止）或 INT（优雅停止）信号。例如，kill -TERM 或 kill -INT 。此外，kill -HUP 也可以用于平滑重启 Nginx，但这实际上是发送了一个挂起信号，而不是停止信号。\n\n使用 brew 服务命令：\n\n关闭 Nginx 服务的最简单方式同样是使用 brew 提供的服务管理命令。在终端中输入以下命令：\n\n```sh\nbrew services stop nginx\n```\n\nNginx 的配置文件通常遵循以下结构：\n\n```sh\n# 全局块\n\nevents {\n # events 块\n}\n\nhttp {\n # http 块\n\n server {\n # server 块\n\n location / {\n # location 块\n }\n\n # 更多的 location 块\n }\n\n # 更多的 server 块\n}\n\n# 注意：server 指令必须嵌套在 http 块中\n```\n\n查看状态：\n\n```sh\nps aux | grep nginx\n```\n" }, { "path": "packages/debug/package.json", "content": "{\n \"name\": \"debug\",\n \"version\": \"1.0.0\",\n \"description\": \"\",\n \"main\": \"index.js\",\n \"scripts\": {\n \"test\": \"echo \\\"Error: no test specified\\\" && exit 1\"\n },\n \"keywords\": [],\n \"author\": \"\",\n \"license\": \"ISC\",\n \"dependencies\": {\n \"koa\": \"^3.0.3\",\n \"koa-mount\": \"^4.2.0\",\n \"koa-send\": \"^5.0.1\",\n \"koa-static\": \"^5.0.0\"\n },\n \"devDependencies\": {\n \"@types/koa\": \"^2.15.0\",\n \"@types/koa-mount\": \"^4.0.5\",\n \"@types/koa-send\": \"^4.1.6\",\n \"@types/koa-static\": \"^4.0.4\"\n }\n}\n" }, { "path": "packages/debug/tsconfig.json", "content": "{\n \"exclude\": [\"node_modules/**\", \"dist/**\", \"public\"],\n \"include\": [\"**/*.ts\", \"**/*.d.ts\", \"**/*.tsx\", \"tailwind.config.ts\"],\n \"compilerOptions\": {\n \"module\": \"ESNext\",\n \"moduleResolution\": \"bundler\",\n \"esModuleInterop\": true,\n \"target\": \"ESNext\",\n \"declaration\": true,\n \"outDir\": \"dist\",\n \"forceConsistentCasingInFileNames\": true,\n \"noFallthroughCasesInSwitch\": true,\n \"isolatedModules\": false,\n \"strict\": true,\n \"skipLibCheck\": true,\n \"noImplicitAny\": true,\n \"useUnknownInCatchVariables\": false,\n \"inlineSourceMap\": true,\n \"baseUrl\": \".\",\n \"experimentalDecorators\": true\n }\n}\n" }, { "path": "packages/docs/.vitepress/common/index.ts", "content": "import { SERVICE_WORK_VERSION } from '../../variable/SERVICE_WORK_VERSION';\n\nexport const GTAG = 'https://www.googletagmanager.com/gtag/js?id=G-0MPS5WH1C0';\n\nexport const GOOGLE_ANALYSE = `;window.dataLayer = window.dataLayer || [];function gtag(){dataLayer.push(arguments);};gtag('js', new Date());gtag('config', 'G-0MPS5WH1C0');`;\n\nexport const BD_ANALYSE = `\n;var _hmt = _hmt || [];\n(function() {\n var hm = document.createElement(\"script\");\n hm.src = \"https://hm.baidu.com/hm.js?3bc20bd8070ce614078a36c686209456\";\n var s = document.getElementsByTagName(\"script\")[0]; \n s.parentNode.insertBefore(hm, s);\n})();\n`;\n\nexport const PREVIEW_CODE = `\n window.uploadFile = (name) => {\n const preview = document.getElementById(name)\n const uploadFile = document.createElement('input')\n uploadFile.setAttribute('type', 'file')\n uploadFile.click()\n uploadFile.onchange = (e) => {\n const { files = [] } = uploadFile\n if (preview) {\n if (files && files.length > 0) {\n preview.setAttribute('src', '')\n const file = files[0]\n const url = URL.createObjectURL(file)\n preview.setAttribute('src', url)\n }\n }\n }\n }\n`;\n\nexport const DESCRIPTION =\n 'Based on web component library, common function library utils, personal article record and so on';\n\nexport const HOME = 'https://chaxus.github.io/ran/';\n\nexport const BASE_PATH = '/ran/';\n\nexport const HOME_ICON = `${HOME}home.svg`;\n\nexport const UTILS_PATH = `${HOME}src/ranuts/utils/`;\n\nexport const RANUI_PATH = `${HOME}src/ranui/`;\n\nexport const ARTICLE_PATH = `${HOME}src/article/designMode.html`;\n\nexport const KEY_WORDS = 'ran,component,components,ui,design,ranui,web-components,javascript,typescript,js';\n\nexport const GITHUB = 'https://github.com/chaxus/ran';\n\nexport const SERVICE_WORK = `\n// 注册 Service worker\nconst registerServiceWorker = async () => {\n if ('serviceWorker' in window.navigator) {\n try {\n const registration = await navigator.serviceWorker.register('/ran/sw${SERVICE_WORK_VERSION}.js', {\n scope: '/ran/',\n });\n if (registration.installing) {\n console.log('installing Service worker');\n } else if (registration.waiting) {\n console.log('Service worker installed');\n } else if (registration.active) {\n console.log('Service worker active');\n }\n } catch (error) {\n console.error('service worker register error:', error);\n }\n }\n};\n\nregisterServiceWorker();\n`;\n\nexport const SET_FONT_SIZE = `\nfunction initFontSize() {\n let base = 375;\n const { documentElement } = document;\n const mediaQuery = window.matchMedia('(orientation: portrait)');\n let timer;\n let standardRatio = 667 / 375;\n const ua = navigator.userAgent.toLowerCase();\n const ipad = /ipad|ipod/.test(ua)\n if (ipad) {\n standardRatio = 1024 / 768;\n base = 768;\n }\n function setFontSize() {\n const ua = navigator.userAgent.toLowerCase();\n const ipad = /ipad|ipod/.test(ua)\n const android = /android/.test(ua)\n const iphone = /iphone/.test(ua)\n if(!ipad && !android && !iphone) {\n documentElement.style.fontSize = '';\n return \n } \n const isLandscape = !mediaQuery.matches;\n let screenWidth = window.screen.width;\n let screenHeight = window.screen.height;\n\n if (screenWidth < screenHeight) {\n [ screenWidth, screenHeight ] = [ screenHeight, screenWidth ];\n }\n\n let width = documentElement.clientWidth;\n let height = screenHeight;\n\n const realRatio = width / height;\n\n if (realRatio >= standardRatio) {\n width = height * standardRatio;\n documentElement.classList.remove('adjustHeight');\n documentElement.classList.add('adjustWidth');\n } else {\n height = width / standardRatio;\n documentElement.classList.remove('adjustWidth');\n documentElement.classList.add('adjustHeight');\n }\n\n window.adjustWidth = width;\n window.adjustHeight = height;\n let target = width / base * 16;\n if (isLandscape) {\n target /= standardRatio;\n }\n documentElement.style.fontSize = target + 'px';\n const currentSize = window.getComputedStyle(documentElement).fontSize.replace('px', '');\n if (target !== currentSize) {\n documentElement.style.fontSize = target / currentSize * target + 'px';\n }\n }\n window.addEventListener('resize', function() {\n clearTimeout(timer);\n timer = setTimeout(setFontSize, 300);\n }, !1);\n window.addEventListener('pageshow', function(e) {\n e.persisted && (clearTimeout(timer), timer = setTimeout(setFontSize, 300));\n }, !1);\n\n window.addEventListener('orientationchange', function() {\n console.log('改变了手机方向');\n setFontSize();\n }, false);\n setFontSize();\n};\ninitFontSize();\n`;\n" }, { "path": "packages/docs/.vitepress/common/sw.ts", "content": "// 注册 Service worker\nconst registerServiceWorker = async () => {\n if ('serviceWorker' in window.navigator) {\n try {\n // eslint-disable-next-line n/no-unsupported-features/node-builtins\n const registration = await navigator.serviceWorker.register('/ran/sw.js', {\n scope: '/ran/',\n });\n if (registration.installing) {\n console.log('installing Service worker');\n } else if (registration.waiting) {\n console.log('Service worker installed');\n } else if (registration.active) {\n console.log('Service worker active');\n }\n } catch (error) {\n console.error('service worker register error:', error);\n }\n }\n};\n\nregisterServiceWorker();\n" }, { "path": "packages/docs/.vitepress/components/Layout.vue", "content": "\n\n" }, { "path": "packages/docs/.vitepress/components/TOTP.vue", "content": "\n\n" }, { "path": "packages/docs/.vitepress/composition/useBasic.ts", "content": "import { inject } from 'vue';\nimport { useI18n } from 'vue-i18n';\nimport type { Env } from '../plugins/env';\n\nexport default (): any => {\n const $env: Env = inject('$env')!;\n const { t, locale } = useI18n();\n return { locale, $env, t };\n};\n" }, { "path": "packages/docs/.vitepress/config.ts", "content": "import { defineConfig } from 'vitepress';\nimport { themeEnConfig } from './langs/en';\nimport { themeCnConfig } from './langs/cn';\nimport {\n ARTICLE_PATH,\n BASE_PATH,\n BD_ANALYSE,\n DESCRIPTION,\n GOOGLE_ANALYSE,\n GTAG,\n HOME,\n HOME_ICON,\n // KEY_WORDS,\n PREVIEW_CODE,\n RANUI_PATH,\n SERVICE_WORK,\n SET_FONT_SIZE,\n UTILS_PATH,\n} from './common/index';\nimport { LANGS_DICT } from './lib/constant';\n\nexport default defineConfig({\n title: 'ran',\n description: DESCRIPTION,\n base: BASE_PATH,\n lastUpdated: true,\n locales: {\n // root: { label: '简体中文', lang: 'zh-CN' },\n // en: {\n // label: 'English',\n // lang: 'en',\n // themeConfig: themeEnConfig,\n // },\n root: { label: 'English', lang: LANGS_DICT.EN },\n cn: {\n label: '简体中文',\n lang: LANGS_DICT.ZH_CN,\n themeConfig: themeCnConfig,\n },\n },\n vue: {\n template: {\n compilerOptions: {\n isCustomElement: (tag: string) => {\n return tag.startsWith('r-');\n },\n },\n },\n },\n head: [\n // base\n ['link', { rel: 'icon', href: `${BASE_PATH}favicon.ico` }],\n ['link', { rel: 'manifest', href: `${BASE_PATH}manifest.json` }],\n ['meta', { name: 'theme-color', content: '#646cff' }],\n // author\n ['meta', { name: 'author', content: '81380@163.com' }],\n // 表示爬虫对此页面的处理行为 或 应当遵守的规则，是用来做搜索引擎抓取的\n // all：搜索引擎将索引此网页，并继续通过此 网页的链接索引文件 将被检索\n // none：搜索引擎将 忽略 此网页\n // index：搜索引擎 索引 此网页\n // follow：搜索引擎继续通过此网页的链接索引搜索 其它的网页\n ['meta', { name: 'robots', content: 'all' }],\n // 用来指定支持双核浏览器要采用哪种的渲染方式\n ['meta', { name: 'renderer', content: 'webkit' }],\n // 已经有国际化，禁止谷歌自动翻译\n ['meta', { name: 'google', content: 'notranslate' }],\n // og\n ['meta', { property: 'og:title', content: 'ran' }],\n [\n 'meta',\n {\n property: 'og:description',\n content: DESCRIPTION,\n },\n ],\n ['meta', { property: 'og:url', content: HOME }],\n ['meta', { property: 'og:image', content: HOME_ICON }],\n ['meta', { property: 'og:type', content: 'article' }],\n [\n 'meta',\n {\n property: 'article:home',\n content: HOME,\n },\n ],\n ['meta', { property: 'article:ranui', content: RANUI_PATH }],\n ['meta', { property: 'article:ranuts', content: UTILS_PATH }],\n ['meta', { property: 'article:section', content: ARTICLE_PATH }],\n // keywords\n // ['meta', { name: 'keywords', content: KEY_WORDS }],\n // chrome\n ['meta', { httpEquiv: 'Permissions-Policy', content: 'interest-cohort=()' }],\n // set font size\n ['script', {}, SET_FONT_SIZE],\n // report\n ['script', { defer: 'true', src: GTAG }],\n ['script', {}, GOOGLE_ANALYSE],\n ['script', {}, BD_ANALYSE],\n // preview component script\n ['script', {}, PREVIEW_CODE],\n // service worker and pwa\n ['script', {}, SERVICE_WORK],\n ],\n themeConfig: themeEnConfig,\n});\n" }, { "path": "packages/docs/.vitepress/lang/en.json", "content": "{\n \"lang\": \"English\",\n \"components_totp_1\": \"Generate\",\n \"components_totp_2\": \"Please enter the key of 2FA\",\n \"components_totp_3\": \"You haven't entered the key for 2FA\",\n \"components_totp_4\": \"expires\",\n \"components_totp_5\": \"The entered key value is invalid\",\n \"components_totp_6\": \"2FA Verification\"\n}\n" }, { "path": "packages/docs/.vitepress/lang/index.ts", "content": "import { createI18n } from 'vue-i18n';\nimport { $env } from '../plugins/env';\nimport { I18N_MODE, LANGS_DICT, LANG_MESSAGES, LOADED_LOCALES } from '../lib/constant';\n\nconst locale = $env.locale;\n\nconst i18n = createI18n({\n legacy: false,\n locale,\n fallbackLocale: LANGS_DICT.EN,\n messages: LANG_MESSAGES,\n devtools: false,\n});\n\nexport const setI18nLanguage = (lang: string): string => {\n if (i18n.mode === I18N_MODE.LEGACY) {\n i18n.global.locale.value = lang as 'zh-CN' | 'en';\n } else {\n i18n.global.locale.value = lang as 'zh-CN' | 'en';\n }\n return lang;\n};\n\n// 合并公共语言词条\nexport const mergeCommonMessage = (message: string, lang = locale): void => {\n i18n.global.mergeLocaleMessage(lang, message);\n};\n\n// 异步加载语言词条\nexport const loadLanguageAsync = (lang: string): Promise => {\n if (!lang) return Promise.reject('lang is undefined');\n // 如果语言相同\n if (i18n.global.locale.value === lang) {\n return Promise.resolve(setI18nLanguage(lang));\n }\n\n // 如果语言已经加载\n if (LOADED_LOCALES.includes(lang)) {\n return Promise.resolve(setI18nLanguage(lang));\n }\n return import(`../lang/${lang}.json`).then((messages) => {\n mergeCommonMessage(messages.default, lang);\n LOADED_LOCALES.push(lang);\n return setI18nLanguage(lang);\n });\n};\n\nexport default i18n;\n" }, { "path": "packages/docs/.vitepress/lang/zh-CN.json", "content": "{\n \"lang\": \"简体中文\",\n \"components_totp_1\": \"生成结果\",\n \"components_totp_2\": \"请输入 2FA 的 key\",\n \"components_totp_3\": \"你还没有输入 2FA 的 key\",\n \"components_totp_4\": \"有效期\",\n \"components_totp_5\": \"输入的 key 值无效\",\n \"components_totp_6\": \"2FA 验证\"\n}\n" }, { "path": "packages/docs/.vitepress/langs/cn/index.ts", "content": "import type { DefaultTheme } from 'vitepress';\nimport { GITHUB } from '../../common/index';\n\nconst themeCnConfig: DefaultTheme.Config = {\n logo: '/home.svg',\n search: {\n provider: 'local',\n },\n nav: [\n { text: '首页', link: '/cn/' },\n { text: '函数', link: '/cn/src/ranuts/' },\n { text: '组件', link: '/cn/src/ranui/' },\n { text: '璀璨', link: '/cn/src/article/design_mode.md' },\n ],\n socialLinks: [{ icon: 'github', link: GITHUB }],\n footer: {\n message: 'Released under the MIT License.',\n copyright: 'Copyright © 2022-11-11',\n },\n // algolia: {\n // appId: 'RDX0Y4AQW1',\n // apiKey: 'c7b6e28f95335eddc66c5a1b54ad9834',\n // indexName: 'chaxus_ran',\n // placeholder: 'search',\n // },\n sidebar: {\n '/cn/src/ranuts/': [\n {\n text: '总览',\n link: '/cn/src/ranuts/',\n },\n {\n text: '工具函数',\n link: '/cn/src/ranuts/utils/',\n collapsed: false,\n items: [\n {\n text: '函数式编程',\n collapsed: true,\n items: [\n { text: 'debounce - 防抖函数', link: '/cn/src/ranuts/utils/debounce.md' },\n { text: 'throttle - 节流函数', link: '/cn/src/ranuts/utils/throttle.md' },\n { text: 'memoize - 记忆化函数', link: '/cn/src/ranuts/utils/memoize.md' },\n { text: 'noop - 空函数', link: '/cn/src/ranuts/utils/noop.md' },\n { text: 'compose - 组合中间件函数', link: '/cn/src/ranuts/utils/compose.md' },\n ],\n },\n {\n text: '字符串处理',\n collapsed: true,\n items: [\n { text: 'md5 - MD5 哈希函数', link: '/cn/src/ranuts/utils/md5.md' },\n { text: 'randomString - 生成随机字符串', link: '/cn/src/ranuts/utils/random_string.md' },\n { text: 'clearBr - 清除空格和换行', link: '/cn/src/ranuts/utils/clear_br.md' },\n { text: 'clearStr - 去除首尾空格和引号', link: '/cn/src/ranuts/utils/clear_str.md' },\n { text: 'strParse - 字符串解析为对象', link: '/cn/src/ranuts/utils/str_parse.md' },\n { text: 'toString - 转换为字符串', link: '/cn/src/ranuts/utils/to_string.md' },\n { text: 'transformText - ArrayBuffer 转文本', link: '/cn/src/ranuts/utils/transform_text.md' },\n { text: 'checkEncoding - 检测字符编码', link: '/cn/src/ranuts/utils/check_encoding.md' },\n {\n text: 'changeHumpToLowerCase - 驼峰转下划线',\n link: '/cn/src/ranuts/utils/change_hump_to_lower_case.md',\n },\n { text: 'getMatchingSentences - 提取匹配句子', link: '/cn/src/ranuts/utils/get_matching_sentences.md' },\n { text: 'isString - 判断是否为字符串', link: '/cn/src/ranuts/utils/is_string.md' },\n { text: 'str2Xml - 字符串转 XML', link: '/cn/src/ranuts/utils/str2xml.md' },\n ],\n },\n {\n text: '对象处理',\n collapsed: true,\n items: [\n { text: 'merge - 合并对象', link: '/cn/src/ranuts/utils/merge.md' },\n { text: 'isEqual - 深度比较', link: '/cn/src/ranuts/utils/is_equal.md' },\n { text: 'cloneDeep - 深度克隆', link: '/cn/src/ranuts/utils/clone_deep.md' },\n { text: 'querystring - 对象转查询字符串', link: '/cn/src/ranuts/utils/querystring.md' },\n { text: 'filterObj - 过滤对象', link: '/cn/src/ranuts/utils/filter_obj.md' },\n { text: 'formatJson - 格式化 JSON', link: '/cn/src/ranuts/utils/format_json.md' },\n ],\n },\n {\n text: '数字处理',\n collapsed: true,\n items: [\n { text: 'range - 限制数字范围', link: '/cn/src/ranuts/utils/range.md' },\n { text: 'mathjs - 精确数字运算', link: '/cn/src/ranuts/utils/mathjs.md' },\n { text: 'perToNum - 百分比转数字', link: '/cn/src/ranuts/utils/per_to_num.md' },\n { text: 'transformNumber - 数字格式化', link: '/cn/src/ranuts/utils/transform_number.md' },\n { text: 'addNumSym - 添加正负号', link: '/cn/src/ranuts/utils/add_num_sym.md' },\n ],\n },\n {\n text: '颜色处理',\n collapsed: true,\n items: [\n { text: 'hexToRgb - 十六进制转 RGB', link: '/cn/src/ranuts/utils/hex_to_rgb.md' },\n { text: 'rgbToHex - RGB 转十六进制', link: '/cn/src/ranuts/utils/rgb_to_hex.md' },\n { text: 'randomColor - 生成随机颜色', link: '/cn/src/ranuts/utils/random_color.md' },\n ],\n },\n {\n text: '时间处理',\n collapsed: true,\n items: [\n { text: 'timeFormat - 时间格式化', link: '/cn/src/ranuts/utils/time_format.md' },\n { text: 'timestampToTime - 时间戳转 Date', link: '/cn/src/ranuts/utils/timestamp_to_time.md' },\n { text: 'performanceTime - 高精度时间戳', link: '/cn/src/ranuts/utils/performance_time.md' },\n ],\n },\n {\n text: '设备检测',\n collapsed: true,\n items: [\n { text: 'isMobile - 判断移动端', link: '/cn/src/ranuts/utils/is_mobile.md' },\n { text: 'isWeiXin - 判断微信浏览器', link: '/cn/src/ranuts/utils/is_weixin.md' },\n { text: 'isClient - 判断客户端环境', link: '/cn/src/ranuts/utils/is_client.md' },\n { text: 'isSafari - 判断 Safari', link: '/cn/src/ranuts/utils/is_safari.md' },\n { text: 'isBangDevice - 判断刘海屏', link: '/cn/src/ranuts/utils/is_bang_device.md' },\n { text: 'currentDevice - 获取设备类型', link: '/cn/src/ranuts/utils/current_device.md' },\n ],\n },\n {\n text: 'DOM 操作',\n collapsed: true,\n items: [\n { text: 'addClassToElement - 添加类名', link: '/cn/src/ranuts/utils/add_class_to_element.md' },\n { text: 'removeClassToElement - 移除类名', link: '/cn/src/ranuts/utils/remove_class_to_element.md' },\n {\n text: 'createDocumentFragment - 创建文档片段',\n link: '/cn/src/ranuts/utils/create_document_fragment.md',\n },\n { text: 'escapeHtml - 转义 HTML', link: '/cn/src/ranuts/utils/escape_html.md' },\n { text: 'Chain - 链式 DOM 操作', link: '/cn/src/ranuts/utils/chain.md' },\n { text: 'create - 创建 DOM 元素', link: '/cn/src/ranuts/utils/create.md' },\n ],\n },\n {\n text: '存储',\n collapsed: true,\n items: [\n { text: 'localStorageGetItem - 获取存储值', link: '/cn/src/ranuts/utils/local_storage.md' },\n { text: 'localStorageSetItem - 设置存储值', link: '/cn/src/ranuts/utils/local_storage.md' },\n ],\n },\n {\n text: 'URL/Query',\n collapsed: true,\n items: [\n { text: 'getAllQueryString - 提取查询参数', link: '/cn/src/ranuts/utils/get_all_query_string.md' },\n { text: 'getQuery - 提取查询参数', link: '/cn/src/ranuts/utils/get_query.md' },\n { text: 'encodeUrl - 安全编码 URL', link: '/cn/src/ranuts/utils/encode_url.md' },\n { text: 'appendUrl - 拼接查询参数', link: '/cn/src/ranuts/utils/append_url.md' },\n ],\n },\n {\n text: 'Cookie',\n collapsed: true,\n items: [\n { text: 'getCookie - 获取 Cookie', link: '/cn/src/ranuts/utils/get_cookie.md' },\n { text: 'getCookieByName - 正则获取 Cookie', link: '/cn/src/ranuts/utils/get_cookie_by_name.md' },\n ],\n },\n {\n text: '图片处理',\n collapsed: true,\n items: [\n { text: 'convertImageToBase64 - 图片转 Base64', link: '/cn/src/ranuts/utils/convert_image_to_base64.md' },\n { text: 'isImageSize - 校验图片尺寸', link: '/cn/src/ranuts/utils/is_image_size.md' },\n ],\n },\n {\n text: '性能',\n collapsed: true,\n items: [\n { text: 'getPerformance - 获取性能指标', link: '/cn/src/ranuts/utils/get_performance.md' },\n { text: 'getFrame - 计算帧率', link: '/cn/src/ranuts/utils/get_frame.md' },\n { text: 'getPixelRatio - 获取分辨率比例', link: '/cn/src/ranuts/utils/get_pixel_ratio.md' },\n ],\n },\n {\n text: '网络',\n collapsed: true,\n items: [\n { text: 'imageRequest - 测试网络延迟', link: '/cn/src/ranuts/utils/image_request.md' },\n { text: 'networkSpeed - 测试网络速度', link: '/cn/src/ranuts/utils/network_speed.md' },\n { text: 'connection - 获取网络连接信息', link: '/cn/src/ranuts/utils/connection.md' },\n ],\n },\n {\n text: '浏览器',\n collapsed: true,\n items: [\n { text: 'getWindow - 获取窗口大小', link: '/cn/src/ranuts/utils/get_window.md' },\n { text: 'getHost - 获取主机地址', link: '/cn/src/ranuts/utils/get_host.md' },\n { text: 'createObjectURL - 创建对象 URL', link: '/cn/src/ranuts/utils/create_object_url.md' },\n { text: 'removeGhosting - 移除拖拽阴影', link: '/cn/src/ranuts/utils/remove_ghosting.md' },\n { text: 'retain - 覆盖后退事件', link: '/cn/src/ranuts/utils/retain.md' },\n ],\n },\n {\n text: '脚本加载',\n collapsed: true,\n items: [{ text: 'scriptOnLoad - 动态加载脚本', link: '/cn/src/ranuts/utils/script_on_load.md' }],\n },\n {\n text: '错误处理',\n collapsed: true,\n items: [\n { text: 'handleConsole - 拦截 console', link: '/cn/src/ranuts/utils/handle_console.md' },\n { text: 'handleError - 全局错误处理', link: '/cn/src/ranuts/utils/handle_error.md' },\n { text: 'handleFetchHook - 拦截 fetch', link: '/cn/src/ranuts/utils/handle_fetch_hook.md' },\n ],\n },\n {\n text: '其他',\n collapsed: true,\n items: [\n { text: 'TOTP - 一次性密码生成器', link: '/cn/src/ranuts/utils/totp.md' },\n { text: 'OCR - 文字识别', link: '/cn/src/ranuts/utils/ocr.md' },\n { text: 'createSignal - 创建响应式信号', link: '/cn/src/ranuts/utils/create_signal.md' },\n { text: 'setMime - 设置 MIME 类型', link: '/cn/src/ranuts/utils/set_mime.md' },\n { text: 'getExtensions - 获取扩展名', link: '/cn/src/ranuts/utils/get_extensions.md' },\n { text: 'setAttributeByGlobal - 全局属性', link: '/cn/src/ranuts/utils/set_attribute_by_global.md' },\n { text: 'SyncHook - 同步事件钩子', link: '/cn/src/ranuts/utils/sync_hook.md' },\n { text: 'durationHandler - 延迟执行', link: '/cn/src/ranuts/utils/duration_handler.md' },\n { text: 'task - 统计执行时间', link: '/cn/src/ranuts/utils/task.md' },\n ],\n },\n ],\n },\n {\n text: '文件操作',\n collapsed: true,\n items: [\n { text: 'writeFile - 写入文件', link: '/cn/src/ranuts/file/write_file.md' },\n { text: 'readFile - 读取文件', link: '/cn/src/ranuts/file/read_file.md' },\n { text: 'readDir - 读取目录', link: '/cn/src/ranuts/file/read_dir.md' },\n { text: 'watchFile - 监听文件变化', link: '/cn/src/ranuts/file/watch_file.md' },\n { text: 'queryFileInfo - 查询文件信息', link: '/cn/src/ranuts/file/file_info.md' },\n { text: 'appendFile - 追加文件内容', link: '/cn/src/ranuts/file/append_file.md' },\n ],\n },\n {\n text: '事件系统',\n collapsed: true,\n items: [{ text: 'EventEmitter - 发布订阅模式', link: '/cn/src/ranuts/mode/subscribe.md' }],\n },\n {\n text: 'MIME 类型',\n collapsed: true,\n items: [{ text: 'getMime - 获取 MIME 类型', link: '/cn/src/ranuts/mime_type/mime_type.md' }],\n },\n {\n text: '其他',\n collapsed: true,\n items: [\n { text: '二叉树', link: '/cn/src/ranuts/binary_tree/index.md' },\n { text: '打包器', link: '/cn/src/ranuts/bundler/index.md' },\n ],\n },\n ],\n '/cn/src/ranui/': [\n {\n text: 'Overview 总览',\n link: '/cn/src/ranui/',\n },\n {\n text: '通用',\n items: [\n { text: 'Button 按钮', link: '/cn/src/ranui/button/' },\n { text: 'Icon 图标', link: '/cn/src/ranui/icon/' },\n { text: 'Loading 加载中', link: '/cn/src/ranui/loading/' },\n ],\n },\n {\n text: '数据展示',\n items: [\n { text: 'Image 图片', link: '/cn/src/ranui/image/' },\n { text: 'Math 数学公式', link: '/cn/src/ranui/math/' },\n { text: 'CheckBox 多选框', link: '/cn/src/ranui/checkbox/' },\n { text: 'Tabs 标签页', link: '/cn/src/ranui/tabs/' },\n { text: 'Preview 预览', link: '/cn/src/ranui/preview/' },\n { text: 'Radar 雷达图', link: '/cn/src/ranui/radar/' },\n { text: 'Select 选择框', link: '/cn/src/ranui/select/' },\n { text: 'Player 视频播放器', link: '/cn/src/ranui/player/' },\n { text: 'Progress 进度条', link: '/cn/src/ranui/progress/' },\n { text: 'Popover 气泡卡片', link: '/cn/src/ranui/popover/' },\n ],\n },\n {\n text: '数据录入',\n items: [{ text: 'Input 输入框', link: '/cn/src/ranui/input/' }],\n },\n {\n text: '反馈',\n items: [\n { text: 'Message 全局提示', link: '/cn/src/ranui/message/' },\n { text: 'Skeleton 骨架屏', link: '/cn/src/ranui/skeleton/' },\n // { text: 'Modal 对话框', link: '/src/ranui/modal/' },\n ],\n },\n ],\n '/cn/src/article/': [\n {\n items: [\n { text: '23 种经典设计模式', link: '/cn/src/article/design_mode.md' },\n {\n text: '函数式编程',\n link: '/cn/src/article/functional_programming.md',\n },\n {\n text: 'web 文档预览方案',\n link: '/cn/src/article/doc_preview.md',\n },\n {\n text: 'Web 视频加密动态方案',\n link: '/cn/src/article/video.md',\n },\n {\n text: '可视化渲染引擎',\n link: '/cn/src/article/visual.md',\n },\n {\n text: '排序算法',\n link: '/cn/src/article/sort/index.md',\n collapsed: true,\n items: [\n { text: '冒泡排序', link: '/cn/src/article/sort/bubble/' },\n { text: '选择排序', link: '/cn/src/article/sort/select/' },\n { text: '插入排序', link: '/cn/src/article/sort/insert/' },\n { text: '希尔排序', link: '/cn/src/article/sort/shell/' },\n { text: '归并排序', link: '/cn/src/article/sort/merge/' },\n { text: '快速排序', link: '/cn/src/article/sort/quick/' },\n { text: '堆排序', link: '/cn/src/article/sort/heap/' },\n { text: '计数排序', link: '/cn/src/article/sort/count/' },\n { text: '桶排序', link: '/cn/src/article/sort/bucket/' },\n { text: '基数排序', link: '/cn/src/article/sort/radix/' },\n ],\n },\n {\n text: '数学',\n collapsed: true,\n items: [{ text: '线性代数', link: '/cn/src/article/math/linear_algebra.md' }],\n },\n ],\n },\n ],\n },\n};\n\nexport { themeCnConfig };\n" }, { "path": "packages/docs/.vitepress/langs/en/index.ts", "content": "import type { DefaultTheme } from 'vitepress';\nimport { GITHUB } from '../../common/index';\n\nconst themeEnConfig: DefaultTheme.Config = {\n logo: '/home.svg',\n search: {\n provider: 'local',\n },\n nav: [\n { text: 'Home', link: '/' },\n { text: 'Function', link: '/src/ranuts/' },\n { text: 'Component', link: '/src/ranui/' },\n { text: 'Article', link: '/src/article/design_mode.md' },\n ],\n socialLinks: [{ icon: 'github', link: GITHUB }],\n footer: {\n message: 'Released under the MIT License.',\n copyright: 'Copyright © 2022-11-11',\n },\n // algolia: {\n // appId: 'RDX0Y4AQW1',\n // apiKey: 'c7b6e28f95335eddc66c5a1b54ad9834',\n // indexName: 'chaxus_ran',\n // placeholder: 'search',\n // },\n sidebar: {\n '/src/ranuts/': [\n {\n text: 'Overview',\n link: '/src/ranuts/',\n },\n {\n text: 'Utility Functions',\n link: '/src/ranuts/utils/',\n collapsed: false,\n items: [\n {\n text: 'Functional Programming',\n collapsed: true,\n items: [\n { text: 'debounce - Debounce function', link: '/src/ranuts/utils/debounce.md' },\n { text: 'throttle - Throttle function', link: '/src/ranuts/utils/throttle.md' },\n { text: 'memoize - Memoization function', link: '/src/ranuts/utils/memoize.md' },\n { text: 'noop - No-op function', link: '/src/ranuts/utils/noop.md' },\n { text: 'compose - Compose middleware', link: '/src/ranuts/utils/compose.md' },\n ],\n },\n {\n text: 'String Processing',\n collapsed: true,\n items: [\n { text: 'md5 - MD5 hash function', link: '/src/ranuts/utils/md5.md' },\n { text: 'randomString - Generate random string', link: '/src/ranuts/utils/random_string.md' },\n { text: 'clearBr - Remove spaces and line breaks', link: '/src/ranuts/utils/clear_br.md' },\n { text: 'clearStr - Remove leading/trailing spaces', link: '/src/ranuts/utils/clear_str.md' },\n { text: 'strParse - Parse string to object', link: '/src/ranuts/utils/str_parse.md' },\n { text: 'toString - Convert to string', link: '/src/ranuts/utils/to_string.md' },\n { text: 'transformText - ArrayBuffer to text', link: '/src/ranuts/utils/transform_text.md' },\n { text: 'checkEncoding - Detect encoding', link: '/src/ranuts/utils/check_encoding.md' },\n {\n text: 'changeHumpToLowerCase - Camel to snake',\n link: '/src/ranuts/utils/change_hump_to_lower_case.md',\n },\n { text: 'getMatchingSentences - Extract sentences', link: '/src/ranuts/utils/get_matching_sentences.md' },\n { text: 'isString - Check if string', link: '/src/ranuts/utils/is_string.md' },\n { text: 'str2Xml - String to XML', link: '/src/ranuts/utils/str2xml.md' },\n ],\n },\n {\n text: 'Object Processing',\n collapsed: true,\n items: [\n { text: 'merge - Merge objects', link: '/src/ranuts/utils/merge.md' },\n { text: 'isEqual - Deep comparison', link: '/src/ranuts/utils/is_equal.md' },\n { text: 'cloneDeep - Deep clone', link: '/src/ranuts/utils/clone_deep.md' },\n { text: 'querystring - Object to query string', link: '/src/ranuts/utils/querystring.md' },\n { text: 'filterObj - Filter object', link: '/src/ranuts/utils/filter_obj.md' },\n { text: 'formatJson - Format JSON', link: '/src/ranuts/utils/format_json.md' },\n ],\n },\n {\n text: 'Number Processing',\n collapsed: true,\n items: [\n { text: 'range - Clamp number range', link: '/src/ranuts/utils/range.md' },\n { text: 'mathjs - Precise calculation', link: '/src/ranuts/utils/mathjs.md' },\n { text: 'perToNum - Percentage to number', link: '/src/ranuts/utils/per_to_num.md' },\n { text: 'transformNumber - Format number', link: '/src/ranuts/utils/transform_number.md' },\n { text: 'addNumSym - Add sign to number', link: '/src/ranuts/utils/add_num_sym.md' },\n ],\n },\n {\n text: 'Color Processing',\n collapsed: true,\n items: [\n { text: 'hexToRgb - Hex to RGB', link: '/src/ranuts/utils/hex_to_rgb.md' },\n { text: 'rgbToHex - RGB to hex', link: '/src/ranuts/utils/rgb_to_hex.md' },\n { text: 'randomColor - Generate random color', link: '/src/ranuts/utils/random_color.md' },\n ],\n },\n {\n text: 'Time Processing',\n collapsed: true,\n items: [\n { text: 'timeFormat - Format time', link: '/src/ranuts/utils/time_format.md' },\n { text: 'timestampToTime - Timestamp to Date', link: '/src/ranuts/utils/timestamp_to_time.md' },\n { text: 'performanceTime - High precision timestamp', link: '/src/ranuts/utils/performance_time.md' },\n ],\n },\n {\n text: 'Device Detection',\n collapsed: true,\n items: [\n { text: 'isMobile - Check mobile device', link: '/src/ranuts/utils/is_mobile.md' },\n { text: 'isWeiXin - Check WeChat browser', link: '/src/ranuts/utils/is_weixin.md' },\n { text: 'isClient - Check client environment', link: '/src/ranuts/utils/is_client.md' },\n { text: 'isSafari - Check Safari browser', link: '/src/ranuts/utils/is_safari.md' },\n { text: 'isBangDevice - Check notch device', link: '/src/ranuts/utils/is_bang_device.md' },\n { text: 'currentDevice - Get device type', link: '/src/ranuts/utils/current_device.md' },\n ],\n },\n {\n text: 'DOM Manipulation',\n collapsed: true,\n items: [\n { text: 'addClassToElement - Add class', link: '/src/ranuts/utils/add_class_to_element.md' },\n { text: 'removeClassToElement - Remove class', link: '/src/ranuts/utils/remove_class_to_element.md' },\n {\n text: 'createDocumentFragment - Create fragment',\n link: '/src/ranuts/utils/create_document_fragment.md',\n },\n { text: 'escapeHtml - Escape HTML', link: '/src/ranuts/utils/escape_html.md' },\n { text: 'Chain - Chainable DOM', link: '/src/ranuts/utils/chain.md' },\n { text: 'create - Create DOM element', link: '/src/ranuts/utils/create.md' },\n ],\n },\n {\n text: 'Storage',\n collapsed: true,\n items: [\n { text: 'localStorageGetItem - Get storage', link: '/src/ranuts/utils/local_storage.md' },\n { text: 'localStorageSetItem - Set storage', link: '/src/ranuts/utils/local_storage.md' },\n ],\n },\n {\n text: 'URL/Query',\n collapsed: true,\n items: [\n { text: 'getAllQueryString - Extract query', link: '/src/ranuts/utils/get_all_query_string.md' },\n { text: 'getQuery - Extract query', link: '/src/ranuts/utils/get_query.md' },\n { text: 'encodeUrl - Encode URL safely', link: '/src/ranuts/utils/encode_url.md' },\n { text: 'appendUrl - Append query params', link: '/src/ranuts/utils/append_url.md' },\n ],\n },\n {\n text: 'Cookie',\n collapsed: true,\n items: [\n { text: 'getCookie - Get cookie', link: '/src/ranuts/utils/get_cookie.md' },\n { text: 'getCookieByName - Get cookie by regex', link: '/src/ranuts/utils/get_cookie_by_name.md' },\n ],\n },\n {\n text: 'Image Processing',\n collapsed: true,\n items: [\n { text: 'convertImageToBase64 - Image to Base64', link: '/src/ranuts/utils/convert_image_to_base64.md' },\n { text: 'isImageSize - Validate image size', link: '/src/ranuts/utils/is_image_size.md' },\n ],\n },\n {\n text: 'Performance',\n collapsed: true,\n items: [\n { text: 'getPerformance - Get performance metrics', link: '/src/ranuts/utils/get_performance.md' },\n { text: 'getFrame - Calculate frame rate', link: '/src/ranuts/utils/get_frame.md' },\n { text: 'getPixelRatio - Get resolution ratio', link: '/src/ranuts/utils/get_pixel_ratio.md' },\n ],\n },\n {\n text: 'Network',\n collapsed: true,\n items: [\n { text: 'imageRequest - Test network latency', link: '/src/ranuts/utils/image_request.md' },\n { text: 'networkSpeed - Test network speed', link: '/src/ranuts/utils/network_speed.md' },\n { text: 'connection - Get network info', link: '/src/ranuts/utils/connection.md' },\n ],\n },\n {\n text: 'Browser',\n collapsed: true,\n items: [\n { text: 'getWindow - Get window size', link: '/src/ranuts/utils/get_window.md' },\n { text: 'getHost - Get host address', link: '/src/ranuts/utils/get_host.md' },\n { text: 'createObjectURL - Create object URL', link: '/src/ranuts/utils/create_object_url.md' },\n { text: 'removeGhosting - Remove drag shadow', link: '/src/ranuts/utils/remove_ghosting.md' },\n { text: 'retain - Override back event', link: '/src/ranuts/utils/retain.md' },\n ],\n },\n {\n text: 'Script Loading',\n collapsed: true,\n items: [{ text: 'scriptOnLoad - Dynamic script loading', link: '/src/ranuts/utils/script_on_load.md' }],\n },\n {\n text: 'Error Handling',\n collapsed: true,\n items: [\n { text: 'handleConsole - Intercept console', link: '/src/ranuts/utils/handle_console.md' },\n { text: 'handleError - Global error handling', link: '/src/ranuts/utils/handle_error.md' },\n { text: 'handleFetchHook - Intercept fetch', link: '/src/ranuts/utils/handle_fetch_hook.md' },\n ],\n },\n {\n text: 'Others',\n collapsed: true,\n items: [\n { text: 'TOTP - One-time password generator', link: '/src/ranuts/utils/totp.md' },\n { text: 'OCR - Text recognition', link: '/src/ranuts/utils/ocr.md' },\n { text: 'createSignal - Create reactive signal', link: '/src/ranuts/utils/create_signal.md' },\n { text: 'setMime - Set MIME type', link: '/src/ranuts/utils/set_mime.md' },\n { text: 'getExtensions - Get extensions', link: '/src/ranuts/utils/get_extensions.md' },\n { text: 'setAttributeByGlobal - Global attribute', link: '/src/ranuts/utils/set_attribute_by_global.md' },\n { text: 'SyncHook - Sync event hook', link: '/src/ranuts/utils/sync_hook.md' },\n { text: 'durationHandler - Delayed execution', link: '/src/ranuts/utils/duration_handler.md' },\n { text: 'task - Statistical execution time', link: '/src/ranuts/utils/task.md' },\n ],\n },\n ],\n },\n {\n text: 'File Operations',\n collapsed: true,\n items: [\n { text: 'writeFile - Write to file', link: '/src/ranuts/file/write_file.md' },\n { text: 'readFile - Read file', link: '/src/ranuts/file/read_file.md' },\n { text: 'readDir - Read directory', link: '/src/ranuts/file/read_dir.md' },\n { text: 'watchFile - Watch file changes', link: '/src/ranuts/file/watch_file.md' },\n { text: 'queryFileInfo - Query file info', link: '/src/ranuts/file/file_info.md' },\n { text: 'appendFile - Append to file', link: '/src/ranuts/file/append_file.md' },\n ],\n },\n {\n text: 'Event System',\n collapsed: true,\n items: [{ text: 'EventEmitter - Publish-subscribe', link: '/src/ranuts/mode/subscribe.md' }],\n },\n {\n text: 'MIME Type',\n collapsed: true,\n items: [{ text: 'getMime - Get MIME type', link: '/src/ranuts/mime_type/mime_type.md' }],\n },\n {\n text: 'Others',\n collapsed: true,\n items: [\n { text: 'Binary Tree', link: '/src/ranuts/binary_tree/index.md' },\n { text: 'Bundler', link: '/src/ranuts/bundler/index.md' },\n ],\n },\n ],\n '/src/ranui/': [\n {\n text: 'Overview ',\n link: '/src/ranui/',\n },\n {\n text: 'Common',\n items: [\n { text: 'Button', link: '/src/ranui/button/' },\n { text: 'Icon', link: '/src/ranui/icon/' },\n { text: 'Loading', link: '/src/ranui/loading/' },\n ],\n },\n {\n text: 'Data Presentation',\n items: [\n { text: 'Image', link: '/src/ranui/image/' },\n { text: 'Math', link: '/src/ranui/math' },\n { text: 'CheckBox', link: '/src/ranui/checkbox/' },\n { text: 'Tabs', link: '/src/ranui/tabs/' },\n { text: 'Preview', link: '/src/ranui/preview/' },\n { text: 'Radar', link: '/src/ranui/radar/' },\n { text: 'Select', link: '/src/ranui/select/' },\n { text: 'Player', link: '/src/ranui/player/' },\n { text: 'Progress', link: '/src/ranui/progress/' },\n { text: 'Popover', link: '/src/ranui/popover/' },\n ],\n },\n {\n text: 'Data Entry',\n items: [{ text: 'Input', link: '/src/ranui/input/' }],\n },\n {\n text: 'Feedback',\n items: [\n { text: 'Message', link: '/src/ranui/message/' },\n { text: 'Skeleton', link: '/src/ranui/skeleton/' },\n // { text: 'Modal 对话框', link: '/src/ranui/modal/' },\n ],\n },\n ],\n '/src/article/': [\n {\n items: [\n {\n text: '23 classic design patterns',\n link: '/src/article/design_mode.md',\n },\n {\n text: 'Functional programming',\n link: '/src/article/functional_programming.md',\n },\n {\n text: 'Sorting algorithm',\n link: '/src/article/sort/index.md',\n collapsed: true,\n items: [\n { text: 'bubble sort', link: '/src/article/sort/bubble/' },\n { text: 'selection sort', link: '/src/article/sort/select/' },\n { text: 'insertion sort', link: '/src/article/sort/insert/' },\n { text: 'shell sort', link: '/src/article/sort/shell/' },\n { text: 'Merge sort', link: '/src/article/sort/merge/' },\n { text: 'Quick sort', link: '/src/article/sort/quick/' },\n { text: 'Heap Sort', link: '/src/article/sort/heap/' },\n { text: 'Counting sort', link: '/src/article/sort/count/' },\n { text: 'Bucket sort', link: '/src/article/sort/bucket/' },\n { text: 'Radix sort', link: '/src/article/sort/radix/' },\n ],\n },\n ],\n },\n ],\n },\n};\n\nexport { themeEnConfig };\n" }, { "path": "packages/docs/.vitepress/lib/constant.ts", "content": "export enum INPUT_STATUS {\n NORMAL = 'normal',\n ERROR = 'error',\n WARNING = 'warning',\n}\n// 支持语言包字典\nexport enum LANGS_DICT {\n EN = 'en', // 英文\n ZH_CN = 'zh-CN', // 简体中文\n}\n// localStorage 中的多语言标识\nexport const RAN_CHAXUS_LANG = 'ran_chaxus_lang';\n\nexport const LOADED_LOCALES: string[] = [];\n\nexport const LANG_MESSAGES = {\n 'zh-CN': {\n lang: '简体中文',\n },\n en: {\n lang: 'English',\n },\n};\n\nexport enum I18N_MODE {\n LEGACY = 'legacy',\n}\n\nexport const PWA_INSTALL_ID = 'PWA_INSTALL_ID';\nexport const PWA_ELEMENT_NAME = 'pwa-install';\nexport const MANIFEST_PATH_ROOT = '/ran/manifest.json';\n" }, { "path": "packages/docs/.vitepress/plugins/env.ts", "content": "import { currentDevice, isBangDevice, isMobile, isWeiXin } from 'ranuts/utils';\nimport type { App } from 'vue';\nimport type { CurrentDevice } from 'ranuts/utils';\nimport { LANGS_DICT } from '../lib/constant';\n\n// env 信息\nconst isDev = process.env.NODE_ENV !== 'production';\n\n// debug 开关信息\n// const { debug = '' } = getAllQueryString() || {};\n\nexport interface Env {\n isDev: boolean;\n locale: LANGS_DICT | string;\n currentDevice: CurrentDevice;\n isWeiXin: boolean;\n isMobile: boolean;\n isBang: boolean;\n}\n\nexport const $env: Env = {\n isDev,\n locale: LANGS_DICT.EN,\n currentDevice: currentDevice(),\n isWeiXin: isWeiXin(),\n isMobile: isMobile(),\n isBang: isBangDevice(), // 是否是刘海机型\n // theme: localStorage.getItem(\"ran-chaxus-theme\")\n};\n\nexport default {\n install: (app: App): void => {\n app.config.globalProperties.$env = $env;\n app.provide('$env', $env);\n },\n};\n" }, { "path": "packages/docs/.vitepress/theme/index.ts", "content": "import DefaultTheme from 'vitepress/theme';\nimport type { EnhanceAppContext } from 'vitepress';\nimport { localStorageGetItem, setAttributeByGlobal } from 'ranuts/utils';\nimport env from '../plugins/env';\nimport TOTP from '../components/TOTP.vue';\nimport Layout from '../components/Layout.vue';\nimport i18n, { loadLanguageAsync } from '../lang';\nimport { LANGS_DICT, MANIFEST_PATH_ROOT, PWA_ELEMENT_NAME, PWA_INSTALL_ID, RAN_CHAXUS_LANG } from '../lib/constant';\nimport './styles/index.less';\nimport './styles/vars.less';\nimport './tailwind.min.css';\nimport 'ranui/style';\n\ndeclare global {\n interface ImportMeta {\n env: {\n SSR: boolean;\n };\n }\n}\n/**\n * @description: pwa 引导安装\n */\nconst pwaInstall = () => {\n import('@khmyznikov/pwa-install').then(() => {\n let pwaInstall = document.getElementById(PWA_INSTALL_ID);\n if (!pwaInstall) {\n pwaInstall = document.createElement(PWA_ELEMENT_NAME);\n pwaInstall.setAttribute('manifest-url', MANIFEST_PATH_ROOT);\n pwaInstall.setAttribute('id', PWA_INSTALL_ID);\n document.body.appendChild(pwaInstall);\n }\n });\n};\n\nexport default {\n extends: DefaultTheme,\n // Layout,\n enhanceApp({ app }: EnhanceAppContext): void {\n if (!import.meta.env.SSR) {\n import('ranui');\n import('@ranui/preview');\n pwaInstall();\n }\n app.use(env);\n const locale = localStorageGetItem(RAN_CHAXUS_LANG) || LANGS_DICT.EN;\n loadLanguageAsync(locale)\n .then(() => {\n setAttributeByGlobal('__VUE_PROD_DEVTOOLS__', false);\n app.use(i18n);\n app.component('Layout', Layout);\n app.component('TOTP', TOTP);\n })\n .catch((error) => {\n console.log('error', error);\n });\n },\n};\n" }, { "path": "packages/docs/.vitepress/theme/styles/index.less", "content": "#app .VPNavBar {\n border-bottom: 1px solid var(--vp-c-divider-light);\n}\n\n#app .VPHomeHero {\n margin-top: 20px;\n margin-bottom: 35px;\n\n .main {\n margin-top: -40px;\n }\n}\n\n#app .VPNavBarTitle {\n .title {\n color: transparent;\n background: var(--vp-home-hero-name-background);\n -webkit-background-clip: text;\n }\n}\n\n.font-icon {\n padding: 2px 8px;\n border-radius: 4px;\n\n display: inline-block;\n background-color: var(--vp-c-gray-light-4);\n}\n\n.dark .font-icon {\n background-color: var(--vp-c-bg);\n}\n\np img {\n margin-top: 2px;\n}\n\n@media (max-width: 960px) {\n #app .image {\n margin-top: -75px;\n }\n\n #app .VPHomeHero {\n margin-bottom: 5px;\n\n .main {\n margin-top: 50px;\n }\n }\n}\n\n@media (min-width: 960px) {\n}\n" }, { "path": "packages/docs/.vitepress/theme/styles/vars.less", "content": "/**\n * Colors\n * -------------------------------------------------------------------------- */\n\n:root {\n --vp-c-brand: #646cff;\n --vp-c-brand-light: #747bff;\n --vp-c-brand-lighter: #9499ff;\n --vp-c-brand-lightest: #bcc0ff;\n --vp-c-brand-dark: #535bf2;\n --vp-c-brand-darker: #454ce1;\n --vp-c-brand-dimm: rgba(100, 108, 255, 0.08);\n}\n\n/**\n * Component: Button\n * -------------------------------------------------------------------------- */\n\n:root {\n --vp-button-brand-border: var(--vp-c-brand-light);\n --vp-button-brand-bg: var(--vp-c-brand);\n --vp-button-brand-text: #fff;\n --vp-button-brand-hover-border: var(--vp-c-brand-light);\n --vp-button-alt-hover-text: var(--vp-c-brand);\n --vp-button-brand-hover-bg: var(--vp-c-brand-lighter);\n --vp-button-brand-hover-border: var(--vp-c-brand-lighter);\n --vp-button-brand-active-border: var(--vp-c-brand-light);\n --vp-button-brand-active-text: var(--vp-c-text-dark-1);\n --vp-button-brand-active-bg: var(--vp-button-brand-bg);\n}\n\n/**\n * Component: Home\n * -------------------------------------------------------------------------- */\n\n:root {\n --vp-home-hero-name-color: transparent;\n --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe 30%, #41d1ff);\n\n --vp-home-hero-image-background-image: linear-gradient(-45deg, #bd34fe 50%, #47caff 50%);\n --vp-home-hero-image-filter: blur(40px);\n}\n\n@media (min-width: 640px) {\n :root {\n --vp-home-hero-image-filter: blur(56px);\n }\n}\n\n@media (min-width: 960px) {\n :root {\n --vp-home-hero-image-filter: blur(72px);\n }\n}\n\n/**\n * Component: Custom Block\n * -------------------------------------------------------------------------- */\n\n:root {\n --vp-custom-block-tip-border: var(--vp-c-brand);\n --vp-custom-block-tip-text: var(--vp-c-brand-darker);\n --vp-custom-block-tip-bg: var(--vp-c-brand-dimm);\n}\n\n.dark {\n --vp-custom-block-tip-border: var(--vp-c-brand);\n --vp-custom-block-tip-text: var(--vp-c-brand-lightest);\n --vp-custom-block-tip-bg: var(--vp-c-brand-dimm);\n}\n\n/**\n * Component: Algolia\n * -------------------------------------------------------------------------- */\n\n.DocSearch {\n --docsearch-primary-color: var(--vp-c-brand) !important;\n}\n\n/**\n * VitePress: Custom fix\n * -------------------------------------------------------------------------- */\n\n/*\n Use lighter colors for links in dark mode for a11y.\n Also specify some classes twice to have higher specificity\n over scoped class data attribute.\n*/\n.dark .vp-doc a,\n.dark .vp-doc a > code,\n.dark .VPNavBarMenuLink.VPNavBarMenuLink:hover,\n.dark .VPNavBarMenuLink.VPNavBarMenuLink.active,\n.dark .link.link:hover,\n.dark .link.link.active,\n.dark .edit-link-button.edit-link-button,\n.dark .pager-link .title {\n color: var(--vp-c-brand-lighter);\n}\n\n.dark .vp-doc a:hover,\n.dark .vp-doc a > code:hover {\n color: var(--vp-c-brand-lightest);\n opacity: 1;\n}\n\n/* Transition by color instead of opacity */\n.dark .vp-doc .custom-block a {\n transition: color 0.25s;\n}\n" }, { "path": "packages/docs/.vitepress/theme/theme.less", "content": ":root {\n --bg-color: #f5f6f6;\n --front-bg-color-2: #fafafa;\n --front-bg-color-1: #ffffff;\n --front-bg-color1: #ffffff;\n --front-bg-color: #f5f6f6;\n --tag-bg-color: #f5f6f6;\n --line-color: #eaebec;\n --tag-border-color: #c7cacc;\n --text-color-3: #afb3b6;\n --text-color-2: #82888d;\n --text-color-2-raw: 130, 136, 141;\n --text-color-1-supplement: #464f56;\n --text-color-1: #000000;\n --link-text-color: #37a0ff;\n --environment-text-color-3: #ffffff;\n --environment-text-color-2: #f5f6f6;\n --environment-text-color-1: #1f2a32;\n --wtt-brand-color: #5622cf;\n --brand-color: #37a0ff;\n --brand-color-raw: 55, 160, 255;\n --brand-color-2: #ff4040;\n --brand-color-3: #ffc700;\n --up-color: #ff5000;\n --down-color: #00b99a;\n --list-bg-color: #ffffff;\n --green-color: #00b99a;\n --red-color: #ff5000;\n}\n\n:root[theme='dark'] {\n --bg-color: #07121c;\n --front-bg-color-2: #141f28;\n --front-bg-color-1: #1a252e;\n --front-bg-color1: #1a252e;\n --front-bg-color: #2a343c;\n --tag-bg-color: #2a343c;\n --line-color: #384149;\n --tag-border-color: #424b53;\n --text-color-3: #61686e;\n --text-color-2: #82888d;\n --text-color-2-raw: 130, 136, 141;\n --text-color-1-supplement: #cfd1d3;\n --text-color-1: #ffffff;\n --link-text-color: #37a0ff;\n --environment-text-color-3: #ffffff;\n --environment-text-color-2: #f5f6f6;\n --environment-text-color-1: #1f2a32;\n --wtt-brand-color: #5622cf;\n --brand-color: #37a0ff;\n --brand-color-2: #ff4040;\n --brand-color-3: #ffc700;\n --up-color: #ff5000;\n --down-color: #00b99a;\n --list-bg-color: #2a343c;\n --green-color: #00b99a;\n --red-color: #ff5000;\n}\n" }, { "path": "packages/docs/bin/build.sh", "content": "#!/bin/bash\n# 更新 service work的版本号\nversion=$(date +%s)\n# 将版本号写入 variable 目录下 SERVICE_WORK_VERSION.ts\nSERVICE_WORK_VERSION=\"./variable/SERVICE_WORK_VERSION.ts\"\n\necho \"export const SERVICE_WORK_VERSION = \\\"$version\\\"\" > $SERVICE_WORK_VERSION\n# 执行 ssg 构建命令\nbin=./node_modules/.bin\n$bin/vitepress build\n# 开启调试模式\n# set -x\n# 指定输出的目录\ndir=\"./.vitepress/dist\"\n# 生成的目标文件\ntarget=\"./.vitepress/dist/sw.js\"\n# 改名\nmv \"$target\" \"./.vitepress/dist/sw$version.js\"\n\ntarget=\"./.vitepress/dist/sw$version.js\"\n# 创建一个临时文件\ntmpfile=$(mktemp)\n# 将目录 dir 下的文件名追加到临时文件中\nfind \"$dir\" -type f > \"$tmpfile\"\n# service worker中生成\n# SERVICE_WORK_CACHE_FILE_PATHS（根据打包后生成的文件来生成）\n# VERSION （时间戳）\n# 的临时文件\nSERVICE_WORK_VARABLE=\"./.vitepress/dist/sw-file.js\"\n\n# 拼接字符串\necho \"const SERVICE_WORK_CACHE_FILE_PATHS = [\" > \"$SERVICE_WORK_VARABLE\"\n# 根路径\nran=\"/ran\"\nwhile read -r file; do\n # if [[ $file != *\".DS_Store\"* ]]; then\n str=\"${file##./.vitepress/dist}\"\n echo \"\\\"$ran$str\\\",\" >> \"$SERVICE_WORK_VARABLE\"\n # fi\ndone < \"$tmpfile\"\n# 拼接字符串\necho \"];\" >> \"$SERVICE_WORK_VARABLE\"\n# 更新 sw 的版本号\necho \"const VERSION = \\\"$version\\\";\" >> \"$SERVICE_WORK_VARABLE\"\n# 删除临时文件\nrm \"$tmpfile\"\n\ntmpfile=$(mktemp)\n\ncat \"$SERVICE_WORK_VARABLE\" >> \"$tmpfile\"\n\ncat \"$target\" >> \"$tmpfile\"\n\nmv \"$tmpfile\" \"$target\"\n\nrm \"$SERVICE_WORK_VARABLE\"\n\n# # 打印完成消息\necho \"service work file paths have been generate for $target\"\n# 关闭调试模式\n# set +x\n" }, { "path": "packages/docs/cn/index.md", "content": "---\nlayout: home\n\ntitle: Home\n\nhero:\n name: ran\n text: 风起于青萍之末\n tagline: A ship in harbor is safe, but that is not what ships are built for.\n image:\n src: /home.svg\n alt: logo\n actions:\n - theme: alt\n text: 更多详情\n link: https://github.com/chaxus/ran\n - theme: alt\n text: 访问我的 GitHub\n link: https://github.com/chaxus/ran\nfeatures:\n - icon: ⚡️\n title: 记录\n details: 每段旅程都有终点\n - icon: 🛠️\n title: 解决\n details: 无法衡量，无法改进\n - icon: 🖖\n title: 分享\n details: 一个人可以走得很快，一群人可以走的很远\n---\n" }, { "path": "packages/docs/cn/src/article/ai/index.md", "content": "# Prompt\n\n## System Prompt\n\n用来描述 AI 的角色，性格，背景知识，语气等，总之只要不是用户直接说出来的内容，都可以放到 System Prompt 里面。\n\n## User Prompt\n\n用户直接发送给 AI 的内容。\n\n每次用户发送 User Prompt 的时候，系统会自动把 System Prompt 也一起发起 AI 模型，这样就会显得非常自然。\n\n但到了这个程度，AI 也只是一个聊天机器人，只能问问题，然后 AI 模型去回复问题。\n\n那么如何让 AI 模型去自动的执行一些任务呢？这时候，Agent 就出现了。\n\n# Agent\n\n比如期望用 AI 来管理一些文件，那么得先写好一些文件管理函数：\n\n- list_file 列出目录下的所有文件\n- read_file 读取文件的内容\n\n然后把这些函数及其他们的功能描述，使用方法，注册到 Agent 中。\n\nAgent 会根据这些信息，生成一个 System Prompt，告诉 AI 模型，用户给了哪些工具，能够做什么。\n\n以及 AI 使用他们应该返回什么样的格式。\n\n当用户在发送 User Prompt 的时候，连同 System Prompt，一起发送给 AI 模型。\n\n如果 AI 模型足够聪明，就会返回一个格式：需要调用某个函数，比如 list_file 给 Agent。\n\nAgent 解析之后，就会调用对应的函数，然后把结果再给 AI，AI 再根据 Agent 返回的结果，再决定下一步去做什么操作。\n\n这个过程就这样反复，直到任务完成为止。\n\n最后，把这种在 AI 模型，提供的工具 (list_file,read_file)，和最终用户之间传话的工具，就叫 AI Agent。\n\n这些提供给 AI Agent 调用的函数，或者服务，就叫 Agent Tool。\n\n但这样可能存在一个问题，虽然我们在 System Prompt 里面描述和规定了 AI 应该用什么格式进行返回，但 AI 模型说到底是一个概率模型。还是有可能返回的格式不对。\n\n一般的 AI Agent 会判断，如果 AI 模型返回的格式不对，会自动进行重试。面对这种场景，FunctionCalling 就出现了。\n\n# FunctionCalling\n\n核心作用就是统一格式，规范描述，比如上面的 System Prompt，使用自然语言描述的，AI 看的懂就行。\n\nFunctionCalling 则对这些描述进行了标准化，每一个 Tool 都用一个 json 来定义，比如：\n\n```json\n{\n \"name\": \"list_file\",\n \"desc\": \"列出目录下的所有文件\",\n \"params\": {\n \"path\": \"str\"\n }\n}\n```\n\n然后这些字段也从 System Prompt 中剥离了出来，这样，所有的工具定义，描述，和返回都放在了相同的地方。这样 AI 使用工具时，也会遵循相同 json 格式进行回复。于是人们就可以更加有针对性的训练 AI 模型。甚至在这种情况下，如果 AI 依然返回了错误的回复，因为这种返回的格式是固定的，AI 服务端自己就能检测到，然后进行重试。这样用户根本感觉不到，降低了用户端的开发难度，同时也节约了重试的 token 成本。\n\n但 FunctionCalling 也有自己的问题，那就是没有统一的标准。目前每家大厂的 API 格式都不太一样。甚至还有一些模型，不支持 FunctionCalling，所以，要写一个通用的 AI Agent，还是挺麻烦的。\n\n因此 FunctionCalling 和 System Prompt 这两种方式，在市面上都是并存的。\n\n以上都是 AI Agent 如何和 AI 模型之间的通信，那么 Agent Tool 和 Agent 是怎么通信的呢。\n\n# MCP\n\n一般都是把 Agent 和 Agent Tool 写到一个程序里，这样就能直接调用，搞定。\n\n但后来人们发现，有些 Agent Tool 还是挺通用的，比如浏览网页的功能，每个 Agent 都需要，那么总不能在每个 Agent 里面都拷贝一份吧。于是，就想到来一个办法：\n\n把 Tool 做成一个服务，进行统一的托管。让所有的 Agent 都来调用，这个过程，就是 MCP。\n\nMCP 是一个通信协议，专门用来规范 Agent 和 Tool 服务之间是怎么交互的。\n\n运行 Tool 的服务叫 MCP Server，调用它的 Agent 叫 MCP Client。\n\nMCP 规定了 MCP Server 如何和 MCP Client 进行通信，以及 MCP Server 要提供哪些接口，比如查询 MCP Server 有哪些接口，接口的功能，描述，如何使用。除了普通的 Tool 这种函数的调用形式。\n\nMCP 也可以直接提供数据，提供文件读取的服务 Resources，或者为 Agent 提供提示词的模版叫 Prompt。\n\nMCP Server 既可以和 Agent 跑在同一台机器上，通过标准输入输出进行通信，也可以部署在网络上，通过 http 进行通信。\n\n虽然 MCP 是为了 AI 而定制出来的标准，但实际上，MCP 本身和 AI 模型没有关系，它并不关心 Agent 用的是哪个模型，MCP 只负责帮 Agent 管理工具，资源和提示词。\n\n最后，总结一下全部的流程：\n\n用户 --> 发送消息给 Agent，Agent（MCP Client）调用 MCP Server 的函数，并把结果一起给 AI 模型。\n\nAI 模型通过 FunctionCalling 或者普通回复的方式，产生调用 Tool 的请求，Agent 收到这个请求后，通过 MCP 协议去调用 MCP Server 的工具。将结果返回给 Agent，Agent 再把结果给 AI 模型，AI 模型再把最终结果，返回个 Agent，Agent 再发送给用户。\n\n# 写一个 Agent\n\nAgent 是一个在用户，AI 模型，工具函数之间进行传话的程序。\n\n```mermaid\nsequenceDiagram\n Tools->>Agent: 将 Tools 里的函数注册到 Agent，让 Agent 知道有哪些工具函数可以使用\n User->>Agent: 将问题发送给 Agent\n Agent->>AI: 用户的问题是 User Prompt，还有将工具函数信息通过 System Prompt 或者 FunctionCalling 的方式告诉 AI 模型\n AI->>Agent: 思考用户的问题，并返回响应的指令，告诉 Agent 应该执行 Tools 中的哪些方法。\n Agent->>Tools: 使用 Tools 中的方法，并获得结果\n Agent->>AI: 将结果告诉给 AI 模型，AI 模型继续分析问题，看是否需要继续调用 Agent，直到结束。\n AI->>Agent: 告诉 Agent 思考过程结束，并将结果发送给 Agent。\n Agent->>User: 将最终结果给用户输出。\n\n```\n\n简单来说，就是下面这种方式\n\n```mermaid\ngraph TD\n customer[用户] --> Agent\n Agent --> AI\n Tools[工具函数] --> Agent\n Agent --> customer[用户]\n Agent --> Tools[工具函数]\n Agent --> AI\n```\n" }, { "path": "packages/docs/cn/src/article/ast_parse/tokenizer.md", "content": "# Abstract Syntax Tree\n\n## 一.（`abstract syntax tree`）抽象语法树的作用\n\n源码是一串按照语法格式来组织的字符串，人能够认识，但是计算机并不认识，想让计算机认识就要转成一种数据结构，通过不同的对象来保存不同的数据，并且按照依赖关系组织起来，这种数据结构就是抽象语法树（`abstract syntax tree`）。\n\n之所以叫“抽象”语法树是因为数据结构中省略掉了一些无具体意义的分隔符比如 `; { }` 等。\n\n有了 `AST`，计算机就能理解源码字符串的意思，而理解是能够转换的前提，所以编译的第一步需要把源码 `parse` 成 `AST`。\n\n转成 `AST` 之后就可以通过修改 `AST` ，分析 `AST` 的方式来修改和分析代码，比如 `babel` 就通过这种方式进行代码的转换，比如 `rollup` 的 `Tree Shaking` ，就是通过分析 `AST`的 导入导出语法，从而分析出没有使用的代码，进行去除。\n\n## 二。常见的 AST 节点\n\n常见的 AST 节点\nAST 是对源码的抽象，字面量、标识符、表达式、语句、模块语法、class 语法都有各自的 AST。\n\n我们分别来了解一下：\n\n### Literal\n\n`Literal` 是字面量的意思，比如 `let name = 'value'`中，`'value'`就是一个字符串字面量 `StringLiteral`，相应的还有数字字面量 `NumericLiteral`，布尔字面量 `BooleanLiteral`，字符串字面量 `StringLiteral`，正则表达式字面量 `RegExpLiteral` 等。\n\n下面这些字面量都有对应的 `Literal` 节点：\n\n![](../../../../assets//ranuts//astParse//Literal.jpeg)\n\n代码中的字面量很多，`babel` 就是通过 `xxLiteral` 来抽象这部分内容的。\n\n### Identifier\n\n`Identifer` 是标识符的意思，变量名、属性名、参数名等各种声明和引用的名字，都是`Identifer`。\n\n我们知道， `JS` 中的标识符只能包含字母或数字或下划线 `（“_”）` 或美元符号 `（“$”）` ，且不能以数字开头。这是 `Identifier` 的词法特点。\n\n尝试分析一下，下面这一段代码里面有多少 `Identifier` 呢？\n\n```js\nconst name = 'value';\n\nfunction say(name) {\n console.log(name);\n}\n\nconst obj = {\n name: 'guang',\n};\n```\n\n答案是这些\n\n![](../../../../assets//ranuts//astParse//Identifier.jpeg)\n\n### Statement\n\n`statement` 是语句，它是可以独立执行的单位，比如 `break、continue、debugger、return` 或者 `if` 语句、`while` 语句、`for` 语句，还有声明语句，表达式语句等。我们写的每一条可以独立执行的代码都是语句。\n\n语句末尾一般会加一个分号分隔，或者用换行分隔。\n\n下面这些我们经常写的代码，每一行都是一个 `Statement`：\n\n```js\nbreak;\ncontinue;\nreturn;\ndebugger;\nthrow Error();\n{}\ntry {} catch(e) {} finally{}\nfor (let key in obj) {}\nfor (let i = 0;i < 10;i ++) {}\nwhile (true) {}\ndo {} while (true)\nswitch (v){case 1: break;default:;}\nlabel: console.log();\nwith (a){}\n```\n\n它们对应的 AST 节点如下图所示：\n\n![](../../../../assets//ranuts//astParse//Statement.jpeg)\n\n语句是代码执行的最小单位，可以说，代码是由语句 `（Statement）` 构成的。\n\n### Declaration\n\n声明语句是一种特殊的语句，它执行的逻辑是在作用域内声明一个变量、函数、 `class、import、export` 等。\n\n比如下面这些语句都是声明语句：\n\n```js\nconst a = 1;\nfunction b() {}\nclass C {}\n\nimport d from 'e';\n\nexport default e = 1;\nexport { e };\nexport * from 'e';\n```\n\n它们对应的 AST 节点如下图：\n\n![](../../../../assets//ranuts//astParse//Declaration.jpeg)\n\n声明语句用于定义变量，这也是代码中一个基础组成部分。\n\n### Expression\n\n`expression` 是表达式，特点是执行完以后有返回值，这是和语句 (`statement`) 的区别。\n\n下面是一些常见的表达式\n\n```js\n[1,2,3]\na = 1\n1 + 2;\n-1;\nfunction(){};\n() => {};\nclass{};\na;\nthis;\nsuper;\na::b;\n```\n\n它们对应的 AST 如图：\n\n![](../../../../assets//ranuts//astParse//Expression.jpeg)\n\n细心的同学可能会问 `identifier` 和 `super` 怎么也是表达式呢？\n\n因为 `identifier、super` 有返回值，符合表达式的特点，所以也是 `expression` 。\n\n我们判断 `AST` 节点是不是某种类型要看它是不是符合该种类型的特点，比如语句的特点是能够单独执行，表达式的特点是有返回值。\n\n有的表达式可以单独执行，符合语句的特点，所以也是语句，比如赋值表达式、数组表达式等。\n\n```js\na = 1;\n[1, 2, 3];\n```\n\n但有的表达式不能单独执行，需要和其他类型的节点组合在一起构成语句。\n\n比如匿名函数表达式和匿名 `class` 表达式单独执行会报错：\n\n```js\nfunction(){};\nclass{}\n```\n\n需要和其他部分一起构成一条语句，比如组成赋值语句：\n\n```js\na = function () {};\nb = class {};\n```\n\n这条赋值语句对应的 `AST` 是这样的：\n\n![](../../../../assets//ranuts//astParse//ExpressionStatement.jpeg)\n\n你会发现赋值语句的 AST 节点 `AssignmentExpression` 包裹了一层 `ExpressionStatement` 的节点，代表这个表达式是被当成语句执行的。\n\n### Class\n\n`class` 的语法也有专门的 AST 节点来表示。\n\n整个 `class` 的内容是 `ClassBody` ，属性是 `ClassProperty` ，方法是 `ClassMethod` （通过 `kind` 属性来区分是 `constructor` 还是 `method` ）。\n\n比如下面的代码\n\n```js\nclass Guang extends Person {\n name = 'guang';\n constructor() {}\n eat() {}\n}\n```\n\n对应的 AST 是这样的\n\n![](../../../../assets//ranuts//astParse//Class.jpeg)\n\n`class` 是 `es next` 的语法， `babel` 中有专门的 `AST` 来表示它的内容。\n\n### Modules\n\n`es module` 是语法级别的模块规范，所以也有专门的 `AST` 节点。\n\n**import**\n`import` 有 3 种语法：\n\n`named import`：\n\n```js\nimport { c, d } from 'c';\n```\n\n`default import`：\n\n```js\nimport a from 'a';\n```\n\n`namespaced import`:\n\n```js\nimport * as b from 'b';\n```\n\n这 3 种语法都对应 `ImportDeclaration` 节点，但是 `specifiers` 属性不同，分别对应 `ImportSpicifier` `、ImportDefaultSpecifier` `、ImportNamespaceSpcifier` 。\n\n![](../../../../assets//ranuts//astParse//import.jpeg)\n\n图中黄框标出的就是 `specifier` 部分。可以直观的看出整体结构相同，只是 `specifier` 部分不同，所以 `import` 语法的 `AST` 的结构是 `ImportDeclaration` 包含着各种 `import specifier` 。\n\n**export**\n`export` 也有 3 种语法：\n\n`named export`：\n\n```js\nexport { b, d };\n```\n\n`default export`：\n\n```js\nexport default a;\n```\n\n`all export`：\n\n```js\nexport * from 'c';\n```\n\n分别对应 `ExportNamedDeclaration` `、ExportDefaultDeclaration` `、ExportAllDeclaration` 的 `AST` 。\n\n比如这三种 `export`\n\n```js\nexport { b, d };\nexport default a;\nexport * from 'c';\n```\n\n对应的 AST 节点为\n\n![](../../../../assets//ranuts//astParse//export.jpeg)\n\n### Program & Directive\n\n`program` 是代表整个程序的节点，它有 `body` 属性代表程序体，存放 `statement` 数组，就是具体执行的语句的集合。还有 `directives` 属性，存放 `Directive` 节点，比如 `\"use strict\"` 这种指令会使用 `Directive` 节点表示。\n\n![](../../../../assets//ranuts//astParse//Program.jpeg)\n\n`Program` 是包裹具体执行语句的节点，而 `Directive` 则是代码中的指令部分。\n\n### File & Comment\n\n`babel` 的 `AST` 最外层节点是 `File` ，它有 `program` 、 `comments` 、 `tokens` 等属性，分别存放 `Program` 程序体、注释、 `token` 等，是最外层节点。\n\n注释分为块注释和行内注释，对应 `CommentBlock` 和 `CommentLine` 节点。\n\n![](../../../../assets//ranuts//astParse//File.jpeg)\n\n上面 6 种就是常见的一些 `AST` 节点类型， `babel` 就是通过这些节点来抽象源码中不同的部分。\n\n### `AST` 可视化查看工具\n\n这么多 `AST` 我们都要记住么？\n\n不需要。可以通过 `axtexplorer.net` 这个网站来可视化的查看。\n\n![](../../../../assets//ranuts//astParse//axtexplorer.jpeg)\n\n这个网站可以查看代码 `parse` 以后的 `AST` ，可以切换 `parse` 的语言和用的 `parser` ，也可以修改 `parse options` 。\n\n点击这里的 `save` 就可以保存下来，然后把 `url` 分享出去：\n\n![](../../../../assets//ranuts//astParse//axtexplorerSave.jpeg)\n\n比如这个链接：`https://astexplorer.net/`\n\n如果想查看全部的 `AST` 可以在 `babel parser` 仓库里的 `AST` 文档里查，或者直接去看 `@babel/types` 的 `typescript` 类型定义。\n\n### AST 的公共属性\n\n每种 `AST` 都有自己的属性，但是它们也有一些公共的属性：\n\n`type`： `AST` 节点的类型\n\n`start` 、 `end` 、`loc：start` 和 `end` 代表该节点在源码中的开始和结束下标。而 `loc` 属性是一个对象，有 `line` 和 `column` 属性分别记录开始和结束的行列号。\n\n`leadingComments` 、 `innerComments` 、 `trailingComments` ：表示开始的注释、中间的注释、结尾的注释，每个 `AST` 节点中都可能存在注释，而且可能在开始、中间、结束这三种位置，想拿到某个 AST 的注释就通过这三个属性。\n\n比如这段有注释的代码的 `AST` ：\n\n![](../../../../assets//ranuts//astParse//Comment.jpeg)\n\n`extra：`记录一些额外的信息，用于处理一些特殊情况。比如 `StringLiteral` 的 `value` 只是值的修改，而修改 `extra.raw` 则可以连同单双引号一起修改。\n比如这段代码的 `AST`：\n\n![](../../../../assets//ranuts//astParse//extra.jpeg)\n\n修改 `value` 只能修改值，修改 `extra.raw` 可以连引号一起修改。\n\n### 总结\n\n了解了这些节点，就能知道平时写的代码是怎么用 `AST` 表示的。\n\n当然也不需要记，可以用 `(astexpoler.net)` 可视化的查看。\n\n`AST` 节点可能同时有多种类型，确定一种 AST 节点是什么类型主要看它的特点，比如 `Statement` 的特点是可以单独执行， `Expression` 的特点是有返回值，所以一些可以单独执行的 `Expression` 会包一层 `ExpressionStatement`。\n\n不同 `AST` 节点有不同的属性来存放对应的源码信息，但是都有一些公共属性如 `type` `、xxComments` 、 `loc` 等。\n\n学会了 `AST` ，就可以把对代码的操作转为对 `AST` 的操作了，这是编译、静态分析的第一步。\n\n## 三。编写词法分析器（Tokenizer）\n\n词法分析器，也叫分词器 (`Tokenizer`)，它的作用是将代码划分为一个个词法单元，便于进行后续的语法分析。比如下面的这段代码：\n\n```js\nlet foo = function () {};\n```\n\n在经过分词之后，代码会被切分为如下的 `token` 数组：\n\n```js\n['let', 'foo', '=', 'function', '(', ')', '{', '}'];\n```\n\n从中你可以看到，原本一行普通的代码字符串被拆分成了拥有语法属性的 `token` 列表，不同的 `token` 之间也存在千丝万缕的联系，而后面所要介绍的语法分析器，就是来梳理各个 `token` 之间的联系，整理出 `AST` 数据结构。\n\n当下我们所要实现的词法分析器，本质上是对代码字符串进行逐个字符的扫描，然后根据一定的语法规则进行分组。其中，涉及到几个关键的步骤：\n\n1. 确定语法规则，包括语言内置的关键词、单字符、分隔符等\n2. 逐个代码字符扫描，根据语法规则进行 `token` 分组\n\n### 1. 确定 Token 的类型和规则\n\n增加 `Token` 的类型\n\n```ts\nexport enum TokenType {\n // let\n Let = 'Let',\n // =\n Assign = 'Assign',\n // function\n Function = 'Function',\n // 变量名\n Identifier = 'Identifier',\n // (\n LeftParen = 'LeftParen',\n // )\n RightParen = 'RightParen',\n // {\n LeftCurly = 'LeftCurly',\n // }\n RightCurly = 'RightCurly',\n}\n\nexport type Token = {\n type: TokenType;\n value?: string;\n start: number;\n end: number;\n raw?: string;\n};\n```\n\n定义 Token 类型到规则的映射\n\n```ts\nconst TOKENS_GENERATOR: Record Token> = {\n let(start: number) {\n return { type: TokenType.Let, value: 'let', start, end: start + 3 };\n },\n assign(start: number) {\n return { type: TokenType.Assign, value: '=', start, end: start + 1 };\n },\n function(start: number) {\n return {\n type: TokenType.Function,\n value: 'function',\n start,\n end: start + 8,\n };\n },\n leftParen(start: number) {\n return { type: TokenType.LeftParen, value: '(', start, end: start + 1 };\n },\n rightParen(start: number) {\n return { type: TokenType.RightParen, value: ')', start, end: start + 1 };\n },\n leftCurly(start: number) {\n return { type: TokenType.LeftCurly, value: '{', start, end: start + 1 };\n },\n rightCurly(start: number) {\n return { type: TokenType.RightCurly, value: '}', start, end: start + 1 };\n },\n identifier(start: number, value: string) {\n return {\n type: TokenType.Identifier,\n value,\n start,\n end: start + value.length,\n };\n },\n};\n\ntype SingleCharTokens = '(' | ')' | '{' | '}' | '=';\n\n// 单字符到 Token 生成器的映射\nconst KNOWN_SINGLE_CHAR_TOKENS = new Map([\n ['(', TOKENS_GENERATOR.leftParen],\n [')', TOKENS_GENERATOR.rightParen],\n ['{', TOKENS_GENERATOR.leftCurly],\n ['}', TOKENS_GENERATOR.rightCurly],\n ['=', TOKENS_GENERATOR.assign],\n]);\n```\n\n有了 Token 类型和对应生成的规则，我们便可以去遍历分析代码，输出分析后的结果。\n\n### 2.代码字符扫描\n\n在扫描字符的过程，我们需要对不同的字符各自进行不同的处理，具体的策略如下：\n\n- 当前字符为分隔符，如空格，直接跳过，不处理；\n- 当前字符为字母，需要继续扫描，获取完整的单词：\n - 如果单词为语法关键字，则新建相应关键字的 `Token`\n - 否则视为普通的变量名\n- 当前字符为单字符，如`{、}、(、)`，则新建单字符对应的 `Token`\n\n```ts\nexport class Tokenizer {\n private _tokens: Token[] = [];\n private _currentIndex: number = 0;\n private _source: string;\n constructor(input: string) {\n this._source = input;\n }\n tokenize(): Token[] {\n while (this._currentIndex < this._source.length) {\n let currentChar = this._source[this._currentIndex];\n const startIndex = this._currentIndex;\n\n // 根据语法规则进行 token 分组\n // while 循环内部\n let currentChar = this._source[this._currentIndex];\n const startIndex = this._currentIndex;\n\n const isAlpha = (char: string): boolean => {\n return (char >= 'a' && char <= 'z') || (char >= 'A' && char <= 'Z');\n };\n\n // 1. 处理空格\n if (currentChar === ' ') {\n this._currentIndex++;\n continue;\n }\n // 2. 处理字母\n else if (isAlpha(currentChar)) {\n let identifier = '';\n while (isAlpha(currentChar)) {\n identifier += currentChar;\n this._currentIndex++;\n currentChar = this._source[this._currentIndex];\n }\n let token: Token;\n if (identifier in TOKENS_GENERATOR) {\n // 如果是关键字\n token = TOKENS_GENERATOR[identifier as keyof typeof TOKENS_GENERATOR](startIndex);\n } else {\n // 如果是普通标识符\n token = TOKENS_GENERATOR['identifier'](startIndex, identifier);\n }\n this._tokens.push(token);\n continue;\n }\n // 3. 处理单字符\n else if (KNOWN_SINGLE_CHAR_TOKENS.has(currentChar as SingleCharTokens)) {\n const token = KNOWN_SINGLE_CHAR_TOKENS.get(currentChar as SingleCharTokens)!(startIndex);\n this._tokens.push(token);\n this._currentIndex++;\n continue;\n }\n }\n return this._tokens;\n }\n}\n```\n\n使用方式\n\n```ts\nconst tokenizer = new Tokenizer('let a = function() {}');\n```\n\n结果\n\n```ts\nconst tokenizer = [\n { type: 'Let', value: 'let', start: 0, end: 3 },\n { type: 'Identifier', value: 'a', start: 4, end: 5 },\n { type: 'Assign', value: '=', start: 6, end: 7 },\n { type: 'Function', value: 'function', start: 8, end: 16 },\n { type: 'LeftParen', value: '(', start: 16, end: 17 },\n { type: 'RightParen', value: ')', start: 17, end: 18 },\n { type: 'LeftCurly', value: '{', start: 19, end: 20 },\n { type: 'RightCurly', value: '}', start: 20, end: 21 },\n];\n```\n\n一个简易版本的分词器已经被我们开发出来了，不过目前的分词器还比较简陋，仅仅支持有限的语法，不过在明确了核心的开发步骤之后，后面继续完善的过程就比较简单了。\n\n## 四。编写语法分析器（Parser）\n\n在解析出词法 `token` 之后，我们就可以进入语法分析阶段了。在这个阶段，我们会依次遍历 `token` ，对代码进行语法结构层面的分析，最后的目标是生成 `AST` 数据结构。至于代码的 `AST` 结构到底是什么样子，你可以去 `AST Explorer` 网站进行在线预览：\n\n![](../../../../assets//ranuts//astParse//Comment.jpeg)\n\n接下来，我们要做的就是将 `token` 数组转换为上图所示的 `AST` 数据。\n\n开发步骤主要分为：\n\n- 初始化类型声明\n-\n" }, { "path": "packages/docs/cn/src/article/babel.md", "content": "# Babel\n\nbabel 核心库主要是：\n\n- @babel/parser 对源码进行 parse，可以通过 plugins、sourceType 等来指定 parse 语法，功能是把源码转成 AST。\n- @babel/traverse 通过 visitor 函数对遍历到的 ast 进行处理，分为 enter 和 exit 两个阶段，具体操作 AST 使用 path 的 api，还可以通过 state 来在遍历过程中传递一些数据\n- @babel/types 用于创建、判断 AST 节点，提供了 xxx、isXxx、assertXxx 的 api\n- @babel/template 当需要批量创建 AST 的时候可以使用 @babel/template 来简化 AST 创建逻辑。\n- @babel/code-frame 可以创建友好的报错信息\n- @babel/generator 打印 AST 成目标代码字符串，支持 comments、minified、sourceMaps 等选项。\n- @babel/core 基于上面的包来完成 babel 的编译流程，并应用 plugin 和 preset。\n" }, { "path": "packages/docs/cn/src/article/bundle.md", "content": "# Bundle\n\nBundle 的本质就是输入，转换，输出。在机器上直接运行的代码，往往都难以维护和理解，我们需要将开发者方便理解和维护的代码，通过打包等工具转换成方便机器或者程序使用的代码。对于 web 前端来说，打包工具，至少需要以下功能：\n\n- 编译能力\n- 插件机制\n- HMR\n- cli 和命令行能力\n" }, { "path": "packages/docs/cn/src/article/design_mode.md", "content": "# 23 种经典设计模式\n\n> 设计模式 `Design Pattern` 是一套被反复使用、多数人知晓的、经过分类编目的、代码设计经验的总结，使用设计模式是为了可重用代码、让代码更容易被他人理解并且保证代码可靠性。。\n\n在《设计模式：可复用面向对象软件的基础》一书中所介绍的 23 种经典设计模式，不过设计模式并不仅仅只有这 23 种，随着软件开发行业的发展，越来越多的新模式不断诞生并得以应用。有经验的开发者在学习设计模式可以和过往的经验互相印证，更容易理解这些设计模式。\n\n设计模式一般包含模式名称、问题、目的、解决方案、效果等组成要素。问题描述了应该在何时使用模式，它包含了设计中存在的问题以及问题存在的原因。解决方案描述了一个设计模式的组成成分，以及这些组成成分之间的相互关系，各自的职责和协作方式，通常解决方案通过 `UML` 类图和核心代码来进行描述。效果描述了模式的优缺点以及在使用模式时应权衡的问题。\n\n**为什么要学习设计模式**:\n\n- 设计模式来源众多专家的经验和智慧，它们是从许多优秀的软件系统中总结出的成功的、能够实现可维护性复用的设计方案，使用这些方案将可以让我们避免做一些重复性的工作\n\n- 设计模式提供了一套通用的设计词汇和一种通用的形式来方便开发人员之间沟通和交流，使得设计方案更加通俗易懂\n\n- 大部分设计模式都兼顾了系统的可重用性和可扩展性，这使得我们可以更好地重用一些已有的设计方案、功能模块甚至一个完整的软件系统，避免我们经常做一些重复的设计、编写一些重复的代码\n\n- 合理使用设计模式并对设计模式的使用情况进行文档化，将有助于别人更快地理解系统\n\n- 学习设计模式将有助于初学者更加深入地理解面向对象思想\n\n**储备知识**：\n\n- 抽象类：一般抽象类都是作为基类，比如说「电脑」就可以作为一个抽象类，根据抽象类派生出「台式电脑」和「笔记本电脑」2 种具体类。一般不对抽象类进行实例化。\n\n- 组合优于继承：不能滥用继承来拓展功能，配合组合会更灵活。同样拿「电脑」抽象类来举例，如果使用继承，区分不同类型的「电脑」我们可以派生出「台式电脑」和「笔记本电脑」，如果再增加一个维度，根据品牌又能继续细分出「联想台式电脑」、「联想笔记本电脑」、「苹果台式电脑」和「苹果笔记本电脑」等等，如果再增加一个维度继续细分下去，显然继承是无法胜任的。这个时候可以使用继承加组合方式，组合的对象也可以进行抽象化设计：\n\n ```ts\n // 品牌\n interface Brand {\n // ...\n }\n interface Lenovo extends Brand {\n // ...\n }\n interface Apple extends Brand {\n // ...\n }\n // CPU\n interface CPU {\n // ...\n }\n interface Inter extends CPU {\n // ...\n }\n interface AMD extends CPU {\n // ...\n }\n // 电脑\n interface Computer {\n // ...\n }\n\n interface DesktopComputer extends Computer {}\n interface NotebookComputer extends Computer {}\n ```\n\n## 一、UML 类图\n\n每个模式都有相应的对象结构图，同时为了展示对象间的交互细节，有些时候会用到 `UML` 图来介绍其如何运行。这里不会将 `UML` 的各种元素都提到，只想讲讲类图中各个类之间的关系，能看懂类图中各个类之间的线条、箭头代表什么意思后，也就足够应对日常的工作和交流。同时，我们应该能将类图所表达的含义和最终的代码对应起来。有了这些知识，看后面章节的设计模式结构图就没有什么问题了。\n\n\n\n### 1.1 继承\n\n继承用一条带空心箭头的直接表示。\n\n![](../../../assets/article/designPattern/继承.png)\n\n### 1.2 实现\n\n实现关系用一条带空心箭头的虚线表示。\n\n![](../../../assets/article/designPattern/实现.png)\n\n### 1.3 组合\n\n与聚合关系一样，组合关系同样表示整体由部分构成的语义。比如公司由多个部门组成，但组合关系是一种强依赖的特殊聚合关系，如果整体不存在了，则部分也不存在了。例如，公司不存在了，部门也将不存在了。\n\n![](../../../assets/article/designPattern/组合.png)\n\n### 1.4 聚合\n\n聚合关系用于表示实体对象之间的关系，表示整体由部分构成的语义，例如一个部门由多个员工组成。与组合关系不同的是，整体和部分不是强依赖的，即使整体不存在了，部分仍然存在。例如，部门撤销了，人员不会消失，他们依然存在。\n\n![](../../../assets/article/designPattern/聚合.png)\n\n### 1.5 关联\n\n关联关系是用一条直线表示的，它描述不同类的对象之间的结构关系，它是一种静态关系，通常与运行状态无关，一般由常识等因素决定的。它一般用来定义对象之间静态的、天然的结构，所以，关联关系是一种“强关联”的关系。\n\n比如，乘车人和车票之间就是一种关联关系，学生和学校就是一种关联关系，关联关系默认不强调方向，表示对象间相互知道。如果特别强调方向，如下图，表示 A 知道 B，但 B 不知道 A。\n\n![](../../../assets/article/designPattern/关联.png)\n\n### 1.6 依赖\n\n依赖关系是用一套带箭头的虚线表示的，如 A 依赖于 B，他描述一个对象在运行期间会用到另一个对象的关系。\n\n与关联关系不同的是，它是一种临时性的关系，通常在运行期间产生，并且随着运行时的变化，依赖关系也可能发生变化。显然，依赖也有方向，双向依赖是一种非常糟糕的结构，我们总是应该保持单向依赖，杜绝双向依赖的产生。\n\n![](../../../assets/article/designPattern/依赖.png)\n\n## 二、六大原则\n\n### 2.1 开闭原则\n\n> 一个软件实体应当对扩展开放，对修改关闭。即软件实体应尽量在不修改原有代码的情况下进行扩展。\n\n任何软件都需要面临一个很重要的问题，即它们的需求会随时间的推移而发生变化。当软件系统需要面对新的需求时，我们应该尽量保证系统的设计框架是稳定的。如果一个软件设计符合开闭原则，那么可以非常方便地对系统进行扩展，而且在扩展时无须修改现有代码，使得软件系统在拥有适应性和灵活性的同时具备较好的稳定性和延续性。随着软件规模越来越大，软件寿命越来越长，软件维护成本越来越高，设计满足开闭原则的软件系统也变得越来越重要。\n\n为了满足开闭原则，需要对系统进行抽象化设计，抽象化是开闭原则的关键。在`Java`、`C#`等编程语言中，可以为系统定义一个相对稳定的抽象层，而将不同的实现行为移至具体的实现层中完成。在很多面向对象编程语言中都提供了接口、抽象类等机制，可以通过它们定义系统的抽象层，再通过具体类来进行扩展。如果需要修改系统的行为，无须对抽象层进行任何改动，只需要增加新的具体类来实现新的业务功能即可，实现在不修改已有代码的基础上扩展系统的功能，达到开闭原则的要求。\n\n**优点：实践开闭原则的优点在于可以在不改动原有代码的前提下给程序扩展功能。增加了程序的可扩展性，同时也降低了程序的维护成本。**\n\n### 2.2 里氏替换原则\n\n> 所有引用基类对象的地方能够透明地使用其子类的对象\n\n里氏代换原则告诉我们，在软件中将一个基类对象替换成它的子类对象，程序将不会产生任何错误和异常，反过来则不成立，如果一个软件实体使用的是一个子类对象的话，那么它不一定能够使用基类对象。例如：我喜欢动物，那我一定喜欢狗，因为狗是动物的子类。但是我喜欢狗，不能据此断定我喜欢动物，因为我并不喜欢老鼠，虽然它也是动物。\n\n例如有两个类，一个类为`BaseClass`，另一个是`SubClass`类，并且`SubClass`类是`BaseClass`类的子类，那么一个方法如果可以接受一个`BaseClass`类型的基类对象`base`的话，如：`method1(base)`，那么它必然可以接受一个`BaseClass`类型的子类对象`sub`，`method1(sub)`能够正常运行。反过来的代换不成立，如一个方法`method2`接受`BaseClass`类型的子类对象`sub`为参数：`method2(sub)`，那么一般而言不可以有`method2(base)`，除非是重载方法。\n\n里氏代换原则是实现开闭原则的重要方式之一，由于使用基类对象的地方都可以使用子类对象，因此在程序中尽量使用基类类型来对对象进行定义，而在运行时再确定其子类类型，用子类对象来替换父类对象。\n\n**优点：可以检验继承使用的正确性，约束继承在使用上的泛滥。**\n\n### 2.3 依赖倒置原则\n\n> 抽象不应该依赖于具体类，具体类应当依赖于抽象。换言之，要针对接口编程，而不是针对实现编程。\n\n依赖倒转原则要求我们在程序代码中传递参数时或在关联关系中，尽量引用层次高的抽象层类，即使用接口和抽象类进行变量类型声明、参数类型声明、方法返回类型声明，以及数据类型的转换等，而不要用具体类来做这些事情。为了确保该原则的应用，一个具体类应当只实现接口或抽象类中声明过的方法，而不要给出多余的方法，否则将无法调用到在子类中增加的新方法。\n\n在引入抽象层后，系统将具有很好的灵活性，在程序中尽量使用抽象层进行编程，而将具体类写在配置文件中，这样一来，如果系统行为发生变化，只需要对抽象层进行扩展，并修改配置文件，而无须修改原有系统的源代码，在不修改的情况下来扩展系统的功能，满足开闭原则的要求。\n\n**优点：通过抽象来搭建框架，建立类和类的关联，以减少类间的耦合性。而且以抽象搭建的系统要比以具体实现搭建的系统更加稳定，扩展性更高，同时也便于维护。**\n\n### 2.4 单一职责原则\n\n> 一个类只负责一个功能领域中的相应职责，或者可以定义为：就一个类而言，应该只有一个引起它变化的原因。\n\n单一职责原则告诉我们：一个类不能太“累”！在软件系统中，一个类（大到模块，小到方法）承担的职责越多，它被复用的可能性就越小，而且一个类承担的职责过多，就相当于将这些职责耦合在一起，当其中一个职责变化时，可能会影响其他职责的运作，因此要将这些职责进行分离，将不同的职责封装在不同的类中，即将不同的变化原因封装在不同的类中，如果多个职责总是同时发生改变则可将它们封装在同一类中。\n\n单一职责原则是实现高内聚、低耦合的指导方针，它是最简单但又最难运用的原则，需要设计人员发现类的不同职责并将其分离，而发现类的多重职责需要设计人员具有较强的分析设计能力和相关实践经验。\n\n**优点：如果类与方法的职责划分得很清晰，不但可以提高代码的可读性，更实际性地更降低了程序出错的风险，因为清晰的代码会让 bug 无处藏身，也有利于 bug 的追踪，也就是降低了程序的维护成本。**\n\n### 2.5 迪米特法则（最少知道原则）\n\n> 一个软件实体应当尽可能少地与其他实体发生相互作用\n\n如果一个系统符合迪米特法则，那么当其中某一个模块发生修改时，就会尽量少地影响其他模块，扩展会相对容易，这是对软件实体之间通信的限制，迪米特法则要求限制软件实体之间通信的宽度和深度。迪米特法则可降低系统的耦合度，使类与类之间保持松散的耦合关系。\n\n迪米特法则要求我们在设计系统时，应该尽量减少对象之间的交互，如果两个对象之间不必彼此直接通信，那么这两个对象就不应当发生任何直接的相互作用，如果其中的一个对象需要调用另一个对象的某一个方法的话，可以通过第三者转发这个调用。简言之，就是通过引入一个合理的第三者来降低现有对象之间的耦合度。\n\n在将迪米特法则运用到系统设计中时，要注意下面的几点：在类的划分上，应当尽量创建松耦合的类，类之间的耦合度越低，就越有利于复用，一个处在松耦合中的类一旦被修改，不会对关联的类造成太大波及。在类的结构设计上，每一个类都应当尽量降低其成员变量和成员函数的访问权限。在类的设计上，只要有可能，一个类型应当设计成不变类。在对其他类的引用上，一个对象对其他对象的引用应当降到最低。\n\n**优点：实践迪米特法则可以良好地降低类与类之间的耦合，减少类与类之间的关联程度，让类与类之间的协作更加直接。**\n\n### 2.6 接口分离原则\n\n> 使用多个专门的接口，而不使用单一的总接口，即客户端不应该依赖那些它不需要的接口。\n\n根据接口隔离原则，当一个接口太大时，我们需要将它分割成一些更细小的接口，使用该接口的客户端仅需知道与之相关的方法即可。每一个接口应该承担一种相对独立的角色，不干不该干的事，该干的事都要干。\n\n在使用接口隔离原则时，我们需要注意控制接口的粒度，接口不能太小，如果太小会导致系统中接口泛滥，不利于维护。接口也不能太大，太大的接口将违背接口隔离原则，灵活性较差，使用起来很不方便。\n\n**优点：避免同一个接口里面包含不同类职责的方法，接口责任划分更加明确，符合高内聚低耦合的思想。**\n\n### 2.7 合成复用原则（六大之外的）\n\n> 尽量使用对象组合，而不是继承来达到复用的目的\n\n合成复用原则就是在一个新的对象里通过关联关系（包括组合关系和聚合关系）来使用一些已有的对象，使之成为新对象的一部分，新对象通过委派调用已有对象的方法达到复用功能的目的。简而言之，复用时要尽量使用组合/聚合关系（关联关系），少用继承。\n\n在面向对象设计中，可以通过两种方法在不同的环境中复用已有的设计和实现，即通过组合/聚合关系或通过继承，但首先应该考虑使用组合/聚合，组合/聚合可以使系统更加灵活，降低类与类之间的耦合度。一个类的变化对其他类造成的影响相对较少，其次才考虑继承，在使用继承时，需要严格遵循里氏代换原则，有效使用继承会有助于对问题的理解，降低复杂度，而滥用继承反而会增加系统构建和维护的难度以及系统的复杂度，因此需要慎重使用继承复用。\n\n**优点：避免复用时滥用继承，合理使用组合关系，增加灵活性。**\n\n### 2.8 六大原则 - 学习心得\n\n六大原则中，**开闭原则**、**里氏替换原则**、**依赖倒置原则** 联系比较紧密，后两者是实现开闭原则重要前提，使用中通过抽象化设计具有很好的可拓展性和可维护性。\n\n**知道最少原则** 可以降低耦合，减少不必要的交互，主张设计接口和类要简单易使用，将复杂的逻辑封装并提供简单易用的接口。\n\n**单一职责原则** 使项目中的类和方法根据职责细分，避免单个类负担过重。职责越多，被复用的可能性就越小或使用起来越麻烦。\n\n**接口分离原则** 将功能复杂的接口细分成多个特定功能的接口，只做该做的事情，降低耦合，但是细化粒度不能太细，容易导致接口过多。单一职责原则强调单个类内部根据职责细分的设计，接口分离原则强调类之间的耦合，尽量建立最小的依赖关系。\n\n## 三、模式分类\n\n《设计模式：可复用面向对象软件的基础》一书中设计模式有 23 个，它们各具特色，每个模式都为某一个可重复的设计问题提供了一套解决方案。根据它们的用途，设计模式可分为创建型 (`Creational`)，结构型 (`Structural`) 和行为型 (`Behavioral`) 三种，其中创建型模式主要用于描述如何创建对象，结构型模式主要用于描述如何实现类或对象的组合，行为型模式主要用于描述类或对象怎样交互以及怎样分配职责。\n\n此外，根据某个模式主要是用于处理类之间的关系还是对象之间的关系，设计模式还可以分为类模式和对象模式。我们经常将两种分类方式结合使用，如单例模式是对象创建型模式，模板方法模式是类行为型模式。\n\n### 3.1 创建型\n\n创建型模式 (`Creational Pattern`) 对类的实例化过程进行了抽象，能够将模块中对象的创建和对象的使用分离。为了使结构更加清晰，外界对于这些对象只需要知道它们共同的接口，而不清楚其具体的实现细节，使整个系统的设计更加符合单一职责原则。\n\n1. 简单工厂模式（`Simple Factory Pattern`）\n2. 工厂方法模式（`Factory Method Pattern`）\n3. 抽象工厂模式（`Abstract Factory Pattern`）\n4. 单例模式（`Singleton Pattern`）\n5. 生成器模式（`Builder Pattern`）\n6. 原型模式（`Prototype Pattern`）\n\n### 3.2 结构型\n\n结构型模式 (`Structural Pattern`) 描述如何将类或者对 象结合在一起形成更大的结构，就像搭积木，可以通过 简单积木的组合形成复杂的、功能更为强大的结构。结构型模式可以分为类结构型模式和对象结构型模式：\n\n- 类结构型模式关心类的组合，由多个类可以组合成一个更大的系统，在类结构型模式中一般只存在继承关系和实现关系。\n\n- 对象结构型模式关心类与对象的组合，通过关联关系使得在一 个类中定义另一个类的实例对象，然后通过该对象调用其方法。根据“合成复用原则”，在系统中尽量使用关联关系来替代继 承关系，因此大部分结构型模式都是对象结构型模式。\n\n1. 外观模式\n2. 适配器模式\n3. 桥接模式\n4. 代理模式\n5. 装饰者模式\n6. 享元模式\n\n### 3.3 行为型\n\n行为型模式 (`Behavioral Pattern`) 是对在不同的对象之间划分责任和算法的抽象化。行为型模式不仅仅关注类和对象的结构，而且重点关注它们之间的相互作用。通过行为型模式，可以更加清晰地划分类与对象的职责，并研究系统在运行时实例对象之间的交互。\n\n1. 职责链模式\n2. 命令模式\n3. 解释器模式\n4. 迭代器模式\n5. 中介者模式\n6. 备忘录模式\n7. 观察者模式\n8. 状态模式\n9. 策略模式\n10. 模板方法模式\n11. 访问者模式\n\n## 四、创建型\n\n### 4.1 简单工厂模式\n\n> 简单工厂模式 (`Simple Factory Pattern`)：专门定义一个类（工厂类）来负责创建其他类的实例。可以根据创建方法的参数来返回不同类的实例，被创建的实例通常都具有共同的父类。\n\n![](../../../assets/article/designPattern/简单工厂.png)\n\n**举例：**\n\n简单工厂模式像一个代工厂，一个工厂可以生产多种产品。举个例子，一个饮料加工厂同时帮百事可乐和可口可乐生产，加工厂根据输入参数`Type`来生产不同的产品。\n\n```ts\n// 可乐抽象类\ninterface Cola {}\n\n// 可口可乐产品类\ninterface CocaCola extends Cola {}\n\n// 百事可乐产品类\ninterface PepsiCola extends Cola {}\n```\n\n```ts\n// 简单工厂实现\n// SimpleFactory\nconst createColaWithType = (type: number) => {\n switch (type) {\n case 0:\n return new CocaCola();\n case 1:\n return new PepsiCola();\n default:\n return null;\n break;\n }\n};\n```\n\n```ts\n// 0 生产可口可乐\nconst cocaCola: CocaCola = createColaWithType(0);\n\n// 1 生产百事可乐\nconst pepsiCola: PepsiCola = createColaWithType(1);\n```\n\n**优点：**\n\n- 使用者只需要给工厂类传入一个正确的约定好的参数，就可以获取你所需要的对象，而不需要知道其创建细节，一定程度上减少系统的耦合。\n- 客户端无须知道所创建的具体产品类的类名，只需要知道具体产品类所对应的参数即可，减少开发者的记忆成本。\n\n**缺点：**\n\n- 如果业务上添加新产品的话，就需要修改工厂类原有的判断逻辑，这其实是违背了开闭原则的。\n- 在产品类型较多时，有可能造成工厂逻辑过于复杂。所以简单工厂模式比较适合产品种类比较少而且增多的概率很低的情况。\n\n### 4.2 工厂方法模式\n\n> 工厂方法模式 (`Factory Method Pattern`) 又称为工厂模式，工厂父类负责定义创建产品对象的公共接口，而工厂子类则负责生成具体的产品对象，即通过不同的工厂子类来创建不同的产品对象。\n\n![](../../../assets/article/designPattern/工厂方法.png)\n\n**举例：**\n\n工厂方法和简单工厂有一些区别，简单工厂是由一个代工厂生产不同的产品，而工厂方法是对工厂进行抽象化，不同产品都由专门的具体工厂来生产。可口可乐工厂专门生产可口可乐，百事可乐工厂专门生产百事可乐。\n\n```ts\n// 工厂抽象类\nclass Cola {}\n\n// 可口可乐工厂\nclass CocaCola extends Cola {}\n\n// 百事可乐工厂\nclass PepsiCola extends Cola {}\n```\n\n```ts\n// 根据不同的工厂类生产不同的产品\nconst cocaCola = new CocaCola();\nconst pepsiCola = new PepsiCola();\n```\n\n**优点：**\n\n- 用户只需要关心其所需产品对应的具体工厂是哪一个即可，不需要关心产品的创建细节，也不需要知道具体产品类的类名。\n- 当系统中加入新产品时，不需要修改抽象工厂和抽象产品提供的接口，也无须修改客户端和其他的具体工厂和具体产品，而只要添加一个具体工厂和与其对应的具体产品就可以了，符合了开闭原则。\n\n**缺点：**\n\n- 当系统中加入新产品时，除了需要提供新的产品类之外，还要提供与其对应的具体工厂类。因此系统中类的个数将成对增加，增加了系统的复杂度。\n\n### 4.3 抽象工厂模式\n\n抽象工厂模式并不直接生成实例，而是用于对产品类簇的创建。\n\n> 抽象工厂模式 (Abstract Factory Pattern)：提供一个创建一系列相关或相互依赖对象的接口，而无须指定它们具体的类。\n\n![](../../../assets/article/designPattern/抽象工厂.png)\n\n**举例：**\n\n抽象工厂和工厂方法不同的地方在于，生产产品的工厂是抽象的。举例，可口可乐公司生产可乐的同时，也需要生产装可乐的瓶子和箱子，瓶子和箱子也是可口可乐专属定制的，同样百事可乐公司也会有这个需求。这个时候我们的工厂不仅仅是生产可乐饮料的工厂，还必须同时生产同一主题的瓶子和箱子，所以它是一个抽象的主题工厂，专门生产同一主题的不同商品。\n\n```ts\n// 可乐抽象类和派生类\nclass Cola {}\n\nclass CocaCola extends Cola {}\n\nclass PepsiCola extends Cola {}\n\n// 瓶子抽象类和派生类\nclass Bottle {}\n\nclass CocaColaBottle extends Bottle {}\n\nclass PepsiColaBottle extends Bottle {}\n\n// 箱子抽象类和派生类\nclass Box {}\n\nclass CocaColaBox extends Box {}\n\nclass PepsiColaBox extends Box {}\n\n// 工厂抽象类\nconst Factory = {\n createCola: () => new Cola(),\n createBottle: () => new Bottle(),\n createBox: () => new Box(),\n};\n\n// 可口可乐主题工厂\nconst CocaColaFactory = {\n createCola: () => new CocaCola(),\n createBottle: () => new CocaColaBottle(),\n createBox: () => new CocaColaBox(),\n};\n\n// 百事可乐主题工厂\nconst PepsiColaFactory = {\n createCola: () => new PepsiCola(),\n createBottle: () => new PepsiColaBottle(),\n createBox: () => new PepsiColaBox(),\n};\n```\n\n```ts\n// 可口可乐主题\nconst cocaCola = CocaColaFactory.createCola();\nconst cocaColaBottle = CocaColaFactory.createBottle();\nconst cocaColaBox = CocaColaFactory.createBox();\n\n// 百事可乐主题\nconst pepsiCola = PepsiColaFactory.createCola();\nconst pepsiColaBottle = PepsiColaFactory.createBottle();\nconst pepsiColaBox = PepsiColaFactory.createBox();\n```\n\n**优点：**\n\n- 具体产品在应用层代码隔离，不需要关心产品细节。只需要知道自己需要的产品是属于哪个工厂的即可 当一个产品族中的多个对象被设计成一起工作时，它能够保证客户端始终只使用同一个产品族中的对象。这对一些需要根据当前环境来决定其行为的软件系统来说，是一种非常实用的设计模式。\n\n**缺点：**\n\n- 规定了所有可能被创建的产品集合，产品族中扩展新的产品困难，需要修改抽象工厂的接口。\n\n### 4.4 单例模式\n\n> 单例模式 (`Singleton Pattern`)：单例模式确保某一个类只有一个实例，并提供一个访问它的全剧访问点。\n\n![](../../../assets/article/designPattern/UML/创建型/单例.jpg)\n\n**举例：**\n\n单例模式下，对应类只能生成一个实例。就像一个王国只能有一个国王，一旦王国里的事务多起来，这唯一的国王也容易职责过重。\n\n```ts\nclass Singleton {}\n\nfunction createSingleton() {\n let instance;\n return function () {\n if (!instance) return new Singleton();\n return instance;\n };\n}\n```\n\n**优点：**\n\n- 提供了对唯一实例的受控访问。因为单例类封装了它的唯一实例，所以它可以严格控制客户怎样以及何时访问它。\n- 因为该类在系统内存中只存在一个对象，所以可以节约系统资源。\n\n**缺点：**\n\n- 由于单例模式中没有抽象层，因此单例类很难进行扩展。\n- 对于有垃圾回收系统的语言 Java，C# 来说，如果对象长时间不被利用，则可能会被回收。那么如果这个单例持有一些数据的话，在回收后重新实例化时就不复存在了。\n\n### 4.5 生成器模式\n\n> 生成器模式 (Builder Pattern)：也叫创建者模式，它将一个复杂对象的构建与它的表示分离，使得同样的构建过程可以创建不同的表示。\n\n工厂模式主要是为了创建对象实例或者类簇（抽象工厂），关心的是最终产出 (创建) 的是什么，而不关心创建的过程。而建造者模式关心的是创建这个对象的整个过程，甚至于创建对象的每一个细节。\n\n![](../../../assets/article/designPattern/建造者.jpeg)\n\n**举例：**\n\n生成器模式的主要角色如下：\n\n1. 生成器：接口生命再所有类型生成器中通用的产品构造步骤\n2. 具体生成器：提供构造过程的不同实现。具体生成器也可以构造不遵循通用接口的产品\n3. 产品：是最终生成的对象。由不同生成器构造的产品无需属于同一类层次构造或接口\n4. 指挥者：定义调用构造步骤的顺序，这样你就可以创建和服用特定的产品配置\n5. 客户端：必须将某个生成器对象与主管类关联，一般情况下，你只需要通过指挥者类构造函数的参数进行一次性关联即可\n\n```ts\n// 抽象建造者\nabstract class Builder {\n public abstract buildPartA(): void;\n public abstract buildPartB(): void;\n public abstract buildPartC(): void;\n public abstract buildProduct(): Product;\n}\n\n// 具体建造者\nclass ConcreteBuilder extends Builder {\n private product: Product;\n constructor(product: Product) {\n super();\n this.product = product;\n }\n\n public buildPartA(): void {}\n public buildPartB(): void {}\n public buildPartC(): void {}\n\n // 最终组建一个产品\n public buildProduct(): Product {\n return this.product;\n }\n}\n\n// 产品角色\nclass Product {\n public doSomething(): void {\n // 独立业务\n }\n}\n\n// 指挥者\nclass Director {\n private _builder: Builder;\n constructor(builder: Builder) {\n this._builder = builder;\n }\n\n set builder(builder: Builder) {\n this._builder = builder;\n }\n\n // 将处理建造的流程交给指挥者\n public constructorProduct() {\n this._builder.buildPartA();\n this._builder.buildPartB();\n this._builder.buildPartC();\n return this._builder.buildProduct();\n }\n}\n\n// 使用\nconst builder: Builder = new ConcreteBuilder(new Product());\nconst director: Director = new Director(builder);\nconst product: Product = director.constructorProduct();\n```\n\n**优点：**\n\n- 客户端不必知道产品内部组成的细节，将产品本身与产品的创建过程解耦，使得相同的创建过程可以创建不同的产品对象。\n- 每一个具体建造者都相对独立，而与其他的具体建造者无关，因此可以很方便地替换具体建造者或增加新的具体建造者，用户使用不同的具体建造者即可得到不同的产品对象。\n- 增加新的具体建造者无须修改原有类库的代码，指挥者类针对抽象建造者类编程，系统扩展方便，符合“开闭原则”。\n- 可以更加精细地控制产品的创建过程。将复杂产品的创建步骤分解在不同的方法中，使得创建过程更加清晰，也更方便使用程序来控制创建过程。\n\n**缺点：**\n\n- 建造者模式所创建的产品一般具有较多的共同点，其组成部分相似，如果产品之间的差异性很大，则不适合使用建造者模式，因此其使用范围受到一定的限制。\n- 如果产品的内部变化复杂，可能会导致需要定义很多具体建造者类来实现这种变化，导致系统变得很庞大，增加系统的理解难度和运行成本。\n\n### 4.6 原型模式\n\n> 原型模式（`Prototype Pattern`）: 用原型实例指向创建对象的类，使用于创建新的对象的类的共享原型的属性与方法。\n\n![](../../../assets/article/designPattern/UML/创建型/原型.jpg)\n\n**举例：**\n\n原型模式就像复印技术，根据原对象复印出一个新对象，并根据需求对新对象进行微调。\n\n```ts\n// 因为不是构造函数，所以不用大写\nconst car = {\n drive: function () {},\n name: '马自达 3',\n};\n\n// 使用 Object.create 创建一个新车 x\nconst anotherCar = Object.create(someCar);\nanotherCar.name = '丰田佳美';\n```\n\n```ts\nconst vehiclePrototype = {\n init: function (carModel) {\n this.model = carModel;\n },\n getModel: function () {\n console.log('车辆模具是：' + this.model);\n },\n};\n\nfunction vehicle(model) {\n function F() {}\n F.prototype = vehiclePrototype;\n\n const f = new F();\n\n f.init(model);\n return f;\n}\n\nconst car = vehicle('福特 Escort');\ncar.getModel();\n```\n\n**优点：**\n\n- 可以利用原型模式简化对象的创建过程，尤其是对一些创建过程繁琐，包含对象层级比较多的对象来说，使用原型模式可以节约系统资源，提高对象生成的效率。\n- 可以很方便得通过改变值来生成新的对象：有些对象之间的差别可能只在于某些值的不同；用原型模式可以快速复制出新的对象并手动修改值即可。\n\n**缺点：**\n\n- 对象包含的所有对象都需要配备一个克隆的方法，这就使得在对象层级比较多的情况下，代码量会很大，也更加复杂。\n\n## 五、结构型\n\n### 5.1 装饰模式\n\n> 装饰模式 (`Decorator Pattern`) ：向一个现有的对象添加新的功能，同时又不改变其结构的设计模式被称为装饰器模式，它是作为现有的类的一个包装。\n\n可以将装饰器理解为游戏人物购买的装备，例如 LOL 中的英雄刚开始游戏时只有基础的攻击力和法强。但是在购买的装备后，在触发攻击和技能时，能够享受到装备带来的输出加成。我们可以理解为购买的装备给英雄的攻击和技能的相关方法进行了装饰。\n\n![](../../../assets/article/designPattern/装饰.jpg)\n\n**举例：**\n\n装饰模式贴合开闭原则，在不改变原有类的情况下，对父类进行改造或新增功能。\n\n装饰类\n\n```ts\n@annotation\nclass MyClass {}\n\nfunction annotation(target) {\n target.annotated = true;\n}\n```\n\n装饰方法或属性\n\n```js\nclass MyClass {\n @readonly\n method() {}\n}\n\nfunction readonly(target, name, descriptor) {\n descriptor.writable = false;\n return descriptor;\n}\n```\n\n**优点：**\n\n- 比继承更加灵活：不同于在编译期起作用的继承；装饰者模式可以在运行时扩展一个对象的功能。另外也可以通过配置文件在运行时选择不同的装饰器，从而实现不同的行为。也可以通过不同的组合，可以实现不同效果。\n- 符合“开闭原则”：装饰者和被装饰者可以独立变化。用户可以根据需要增加新的装饰类，在使用时再对其进行组合，原有代码无须改变。\n\n**缺点：**\n\n- 装饰者模式需要创建一些具体装饰类，会增加系统的复杂度。\n\n### 5.2 外观模式\n\n> 外观模式 (Facade Pattern)：外观模式定义了一个高层接口，为子系统中的一组接口提供一个统一的接口。使得子系统更容易使用，不仅简化类中的接口，而且实现调用者和接口的解耦。外观模式又称为门面模式，它是一种结构型设计模式模式。\n\n![](../../../assets/article/designPattern/外观.png)\n\n**举例：**\n\n外观模式提供了简单明确的接口，但是在内部众多子系统功能进行整合。就像图片缓存，内部包含了涉及到其他子系统的如缓存、下载等处理，外观模式将这些复杂的逻辑都隐藏了。在兼容浏览器事件绑定，你只需要调一个`addMyEvent`接口就可以了，达到解耦合的目的。\n\n```js\nconst addMyEvent = function (el, ev, fn) {\n if (el.addEventListener) {\n el.addEventListener(ev, fn, false);\n } else if (el.attachEvent) {\n el.attachEvent('on' + ev, fn);\n } else {\n el['on' + ev] = fn;\n }\n};\n```\n\n**优点：**\n\n- 实现了客户端与子系统间的解耦：客户端无需知道子系统的接口，简化了客户端调用子系统的调用过程，使得子系统使用起来更加容易。同时便于子系统的扩展和维护。\n- 符合迪米特法则（最少知道原则）：子系统只需要将需要外部调用的接口暴露给外观类即可，而且他的接口则可以隐藏起来。\n\n**缺点：**\n\n- 违背了开闭原则：在不引入抽象外观类的情况下，增加新的子系统可能需要修改外观类或客户端的代码。\n\n### 5.3 代理模式\n\n> 代理模式 (Proxy Pattern) ：为某个对象提供一个代理，并由这个代理对象控制对原对象的访问。\n\n![](../../../assets/article/designPattern/代理.png)\n\n**举例：**\n\n代理模式像一个房屋中介，买家只能通过中介来买房，代理具备被代理类的所有功能，就像房东有卖房功能，中介也具有卖房功能。此外代理实例还可以帮助被代理实例进行一些额外处理，比如中介可以帮助房东筛选优质买家的功能，帮助房东 pass 掉一些不符合条件的买家。还有消息队列也是该模式。\n\n参考`koa`中的代理模式，把`response`上的一些属性和方法代理出来，方便使用\n\n```js\n/**\n * Response delegation.\n */\nconst delegate = require('delegates');\n\nconst prototype = (module.exports = {});\n\ndelegate(prototype, 'response')\n .method('attachment')\n .method('redirect')\n .method('remove')\n .method('vary')\n .method('has')\n .method('set')\n .method('append')\n .method('flushHeaders')\n .access('status')\n .access('message')\n .access('body')\n .access('length')\n .access('type')\n .access('lastModified')\n .access('etag')\n .getter('headerSent')\n .getter('writable');\n```\n\n对`context`,`request`,`response`做一个代理，保护真正的`context`,`request`,`response`\n\n```js\nthis.context = Object.create(context);\nthis.request = Object.create(request);\nthis.response = Object.create(response);\n```\n\n**优点：**\n\n- 降低系统的耦合度：代理模式能够协调调用者和被调用者，在一定程度上降低了系 统的耦合度。\n- 不同类型的代理可以对客户端对目标对象的访问进行不同的控制：\n - 远程代理，使得客户端可以访问在远程机器上的对象，远程机器 可能具有更好的计算性能与处理速度，可以快速响应并处理客户端请求。\n - 虚拟代理通过使用一个小对象来代表一个大对象，可以减少系统资源的消耗，对系统进行优化并提高运行速度。\n - 保护代理可以控制客户端对真实对象的使用权限。\n\n**缺点：**\n\n- 由于在客户端和被代理对象之间增加了代理对象，因此可能会让客户端请求的速度变慢。\n\n### 5.4 享元模式\n\n> 享元模式 (`Flyweight Pattern`)：享元模式是一种优化程序性能的模式，本质为减少对象创建的个数。运用共享技术复用大量细粒度的对象，降低程序内存的占用，提高程序的性能。以下情况可以使用享元模式：有大量相似的对象，占用了大量内存。对象中大部分状态可以抽离为外部状态。\n\n![](../../../assets/article/designPattern/享元.png)\n\n**举例：**\n\n举例，音乐服务根据收费划分出免费用户和会员用户，免费用户只能听部分免费音乐，会员用户可以听全部的音乐，并且可以下载。虽然权限上二者间有一些区别，但是他们所享受的音乐来是自于同一个音乐库，这样所有的音乐都只需要保存一份就可以了。另外如果出现音乐库里没有的音乐时，则需要新增该音乐，然后其他服务也可以享受新增的音乐，相当于享元池或缓存池的功能。\n\n享元模式区保证共享内部状态如音乐库，而外部状态根据不同需求定制如各种访问权限，使用中不能去改变内部状态，以达到共享的目的。\n\n```ts\n// 音乐服务\nconst MusicService = {}\n\n// 共享的音乐库\nconst musicLibrary = {};\n\n// 听音乐\nconst listenToMusic = (music) => {\n ...\n}\n// 下载音乐\nconst downloadMusic = (music) => {\n ...\n}\n\n\n// 免费音乐服务\nconst FreeMusicService = {\n listenFreeMusic: (music)=>{\n if(isMusicFree(music)){\n // 如果是免费则播放\n listenToMusic()\n }else{\n \t // 如果是收费音乐，则提示用户升级 Vip\n console.log(\"please upgrade to Vip\")\n }\n }\n}\n\n\n// Vip 音乐服务\nconst VipMusicService = {\n // 可以听全部的音乐\n listenMusic\n // 可以下载音乐\n downloadMusic\n}\n```\n\n**优点：**\n\n- 使用享元模可以减少内存中对象的数量，使得相同对象或相似对象在内存中只保存一份，降低系统的使用内存，也可以提性能。\n- 享元模式的外部状态相对独立，而且不会影响其内部状态，从而使得享元对象可以在不同的环境中被共享。\n\n**缺点：**\n\n- 使用享元模式需要分离出内部状态和外部状态，这使得程序的逻辑复杂化。\n- 对象在缓冲池中的复用需要考虑线程问题。\n\n### 5.5 桥接模式\n\n> 桥接模式 (`Simple Factory Pattern`)：将抽象部分与它的实现部分分离，使它们都可以独立地变化。\n\n![](../../../assets/article/designPattern/桥接.png)\n\n**举例：**\n\n球和人都可以进行运动，但球有运动和颜色，人可以运动和说话。对共同部分进行抽象。\n\n```js\nclass Speed {\n // 运动模块\n constructor(x, y) {\n this.x = x;\n this.y = y;\n }\n run() {\n console.log(`运动起来 ${this.x} + ${this.y}`);\n }\n}\n\nclass Color {\n // 着色模块\n constructor(cl) {\n this.color = cl;\n }\n draw() {\n console.log(`绘制颜色 ${this.color}`);\n }\n}\n\nclass Speak {\n constructor(wd) {\n this.word = wd;\n }\n say() {\n console.log(`说话 ${this.word}`);\n }\n}\n\nclass Ball {\n // 创建球类，可以着色和运动\n constructor(x, y, cl) {\n this.speed = new Speed(x, y);\n this.color = new Color(cl);\n }\n init() {\n this.speed.run();\n this.color.draw();\n }\n}\n\nclass Man {\n // 人类，可以运动和说话\n constructor(x, y, wd) {\n this.speed = new Speed(x, y);\n this.speak = new Speak(wd);\n }\n init() {\n this.speed.run();\n this.speak.say();\n }\n}\n\nconst man = new Man(1, 2, 'hello ?');\nman.init(); // 运动起来 1 + 2 说话 hello?\n```\n\n**优点：**\n\n- 扩展性好，符合开闭原则：将抽象与实现分离，让二者可以独立变化\n\n**缺点：**\n\n- 在设计之前，需要识别出两个独立变化的维度。\n\n### 5.6 适配器模式\n\n> 适配器模式 (`Adapter Pattern`) ：适配器模式是用来解决两个接口不兼容的情况，不需要改变已有的接口，通过包装一层的方式，实现两个接口正常协作。当我们试图调用模块或者对象的某个接口时，却发现这个接口的格式并不符合目前的需求，则可以用适配器模式。\n\n![](../../../assets/article/designPattern/适配器.png)\n\n**举例：**\n\n事件绑定兼容各浏览器\n\n```js\nfunction addEvent(ele, event, callback) {\n if (ele.addEventListener) {\n ele.addEventListener(event, callback)\n } else if(ele.attachEvent) {\n ele.attachEvent('on' + event, callback)\n } else {\n ele['on' + event] = callback\n }\n }\n​\n```\n\n**优点：**\n\n- 符合开闭原则：使用适配器而不需要改变现有类，提高类的复用性。\n- 目标类和适配器类解耦，提高程序扩展性。\n\n**缺点：**\n\n- 增加了系统的复杂性\n\n## 六、行为型\n\n### 6.1 职责链模式\n\n> 职责链模式 (Chain of Responsibility Pattern)：避免请求发送者与接收者耦合在一起，让多个对象都有可能接收请求，将这些对象连接成一条链，并且沿着这条链传递请求，直到有对象处理它为止。职责链模式是一种对象行为型模式。类似多米诺骨牌，通过请求第一个条件，会持续执行后续的条件，直到返回结果为止。\n\n![](../../../assets/article/designPattern/责任链.png)\n\n**举例：**\n\n场景：某电商针对已付过定金的用户有优惠政策，在正式购买后，已经支付过 500 元定金的用户会收到 100 元的优惠券，200 元定金的用户可以收到 50 元优惠券，没有支付过定金的用户只能正常购买。\n\n```js\nconst order500 = function (orderType, pay, stock) {\n if (orderType === 1 && pay == true) {\n console.log('500 元定金预购，得到 100 元优惠劵');\n } else {\n return 'nextSuccess';\n }\n};\nconst order200 = function (orderType, pay, stock) {\n if (orderType === 2 && pay === true) {\n console.log('200 元定金预购，得到 50 元優惠卷');\n } else {\n return 'nextSuccess';\n }\n};\nconst orderCommon = function (orderType, pay, stock) {\n if (orderType == 3 && stock > 0) {\n console.log('普通購買，无優惠卷');\n } else {\n console.log('库存不够');\n }\n};\n//链路代码\nconst chain = function (fn) {\n this.fn = fn;\n this.successor = null;\n};\nchain.prototype.setNext = function (successor) {\n this.successor = successor;\n};\nchain.prototype.init = function () {\n const result = this.fn.apply(this, arguments);\n if (result == 'nextSuccess') {\n this.successor.init.apply(this.successor, arguments);\n }\n};\nconst order500New = new chain(order500);\nconst order200New = new chain(order200);\nconst orderCommonNew = new chain(orderCommon);\norder500New.setNext(order200New);\norder200New.setNext(orderCommonNew);\norder500New.init(3, true, 500); // 普通购买，无优惠券\n```\n\n**优点：**\n\n- 职责链模式使得一个对象无须知道是其他哪一个对象处理其请求，对象仅需知道该请求会被处理即可，接收者和发送者都没有对方的明确信息，且链中的对象不需要知道链的结构，由客户端负责链的创建，降低了系统的耦合度。\n- 请求处理对象仅需维持一个指向其后继者的引用，而不需要维持它对所有的候选处理者的引用，可简化对象的相互连接。\n- 在给对象分派职责时，职责链可以给我们更多的灵活性，可以通过在运行时对该链进行动态的增加或修改来增加或改变处理一个请求的职责。\n- 在系统中增加一个新的具体请求处理者时无须修改原有系统的代码，只需要在客户端重新建链即可，从这一点来看是符合“开闭原则”的。\n\n**缺点：**\n\n- 由于一个请求没有明确的接收者，那么就不能保证它一定会被处理，该请求可能一直到链的末端都得不到处理；一个请求也可能因职责链没有被正确配置而得不到处理。\n- 对于比较长的职责链，请求的处理可能涉及到多个处理对象，系统性能将受到一定影响，而且在进行代码调试时不太方便。\n- 如果建链不当，可能会造成循环调用，将导致系统陷入死循环。\n\n### 6.2 命令模式\n\n> 命令模式 (`Command Pattern`)：将一个请求封装为一个对象，从而让我们可用不同的请求对客户进行参数化；命令模式是一种对象行为型模式，其别名为动作 (`Action`) 模式或事务 (`Transaction`) 模式。\n\n命令模式由三种角色构成：\n\n1. 发布者 `invoker`（发出命令，调用命令对象，不知道如何执行与谁执行）；\n2. 接收者 `receiver` (提供对应接口处理请求，不知道谁发起请求）；\n3. 命令对象 `command`（接收命令，调用接收者对应接口处理发布者的请求）。\n 发布者 invoker 和接收者 receiver 各自独立，将请求封装成命令对象 command，请求的具体执行由命令对象 command 调用接收者 receiver 对应接口执行。\n\n![](../../../assets/article/designPattern/命令.png)\n\n**举例：**\n\n和之前代理模式中的举例有些相似，不过命令模式的本质是对命令进行封装，将发出命令的责任和执行命令的责任分割开。例如遥控器是一个调用者，不同按钮代表不同的命令，而电视是接收者。\n\n```js\nclass Receiver {\n // 接收者类\n execute() {\n console.log('接收者执行请求');\n }\n}\n\nclass Command {\n // 命令对象类\n constructor(receiver) {\n this.receiver = receiver;\n }\n execute() {\n // 调用接收者对应接口执行\n console.log('命令对象->接收者->对应接口执行');\n this.receiver.execute();\n }\n}\n\nclass Invoker {\n // 发布者类\n constructor(command) {\n this.command = command;\n }\n invoke() {\n // 发布请求，调用命令对象\n console.log('发布者发布请求');\n this.command.execute();\n }\n}\n\nconst warehouse = new Receiver(); // 仓库\nconst order = new Command(warehouse); // 订单\nconst client = new Invoker(order); // 客户\nclient.invoke();\n```\n\n**优点：**\n\n- 降低系统的耦合度。由于请求者与接收者之间不存在直接引用，因此请求者与接收者之间实现完全解耦，相同的请求者可以对应不同的接收者，同样，相同的接收者也可以供不同的请求者使用，两者之间具有良好的独立性。\n- 新的命令可以很容易地加入到系统中。由于增加新的具体命令类不会影响到其他类，因此增加新的具体命令类很容易，无须修改原有系统源代码，甚至客户类代码，满足“开闭原则”的要求。\n- 可以比较容易地设计一个命令队列或宏命令（组合命令）。\n- 为请求的撤销 (Undo) 和恢复 (Redo) 操作提供了一种设计和实现方案。\n\n**缺点：**\n\n- 使用命令模式可能会导致某些系统有过多的具体命令类。因为针对每一个对请求接收者的调用操作都需要设计一个具体命令类，因此在某些系统中可能需要提供大量的具体命令类，这将影响命令模式的使用。\n\n### 6.3 解释器模式\n\n> 解释器模式 (`Interpreter Pattern`)：定义一个语言的文法，并且建立一个解释器来解释该语言中的句子，这里的“语言”是指使用规定格式和语法的代码。解释器模式是一种类行为型模式。\n\n![](../../../assets/article/designPattern/解释器.jpg)\n\n**举例：**\n\n给定一个语言，定义它的文法的一种表示，并定义一个解释器，该解释器使用该表示来解释语言中的句子。\n\n```js\nclass Context {\n constructor() {\n this._list = []; // 存放 终结符表达式\n this._sum = 0; // 存放 非终结符表达式 (运算结果)\n }\n\n get sum() {\n return this._sum;\n }\n set sum(newValue) {\n this._sum = newValue;\n }\n add(expression) {\n this._list.push(expression);\n }\n get list() {\n return [...this._list];\n }\n}\n\nclass PlusExpression {\n interpret(context) {\n if (!(context instanceof Context)) {\n throw new Error('TypeError');\n }\n context.sum = ++context.sum;\n }\n}\nclass MinusExpression {\n interpret(context) {\n if (!(context instanceof Context)) {\n throw new Error('TypeError');\n }\n context.sum = --context.sum;\n }\n}\n\n/** 以下是测试代码 **/\nconst context = new Context();\n\n// 依次添加：加法 | 加法 | 减法 表达式\ncontext.add(new PlusExpression());\ncontext.add(new PlusExpression());\ncontext.add(new MinusExpression());\n\n// 依次执行：加法 | 加法 | 减法 表达式\ncontext.list.forEach((expression) => expression.interpret(context));\nconsole.log(context.sum);\n```\n\n**优点：**\n\n- 易于改变和扩展文法。由于在解释器模式中使用类来表示语言的文法规则，因此可以通过继承等机制来改变或扩展文法。\n- 每一条文法规则都可以表示为一个类，因此可以方便地实现一个简单的语言。\n- 实现文法较为容易。在抽象语法树中每一个表达式节点类的实现方式都是相似的，这些类的代码编写都不会特别复杂，还可以通过一些工具自动生成节点类代码。\n- 增加新的解释表达式较为方便。如果用户需要增加新的解释表达式只需要对应增加一个新的终结符表达式或非终结符表达式类，原有表达式类代码无须修改，符合“开闭原则”。\n\n**缺点：**\n\n- 对于复杂文法难以维护。在解释器模式中，每一条规则至少需要定义一个类，因此如果一个语言包含太多文法规则，类的个数将会急剧增加，导致系统难以管理和维护，此时可以考虑使用语法分析程序等方式来取代解释器模式。\n- 执行效率较低。由于在解释器模式中使用了大量的循环和递归调用，因此在解释较为复杂的句子时其速度很慢，而且代码的调试过程也比较麻烦。\n\n### 6.4 迭代器模式\n\n> 迭代器模式 (`Iterator Pattern`)：一个相对简单的模式，目前绝大多数语言都内置了迭代器，以至于大家都不觉得这是一种设计模式。迭代器并不只迭代数组，迭代器可以中止。提供一种方法来访问聚合对象，而不用暴露这个对象的内部表示，其别名为游标 (`Cursor`)。迭代器模式是一种对象行为型模式。\n\n![](../../../assets/article/designPattern/迭代器.png)\n\n**举例：**\n\n迭代器帮助请求方获取数据，避免直接操作数据聚合类，使数据聚合类专注存储数据。具体应用有分页等功能，分页功能的迭代器将专门负责操作分页数据，将操作逻辑和数据源分离。\n\n```js\nvar each = function (arr, callback) {\n for (var i = 0, len = arr.length; i < len; i++) {\n callback.call(arr[i], i, arr[i]);\n }\n};\n\neach([1, 2, 3, 4, 5], function (i, el) {\n console.log('index: ', i);\n console.log('item: ', el);\n});\n```\n\n**优点：**\n\n- 它支持以不同的方式遍历一个聚合对象，在同一个聚合对象上可以定义多种遍历方式。在迭代器模式中只需要用一个不同的迭代器来替换原有迭代器即可改变遍历算法，我们也可以自己定义迭代器的子类以支持新的遍历方式。\n- 迭代器简化了聚合类。由于引入了迭代器，在原有的聚合对象中不需要再自行提供数据遍历等方法，这样可以简化聚合类的设计。\n- 在迭代器模式中，由于引入了抽象层，增加新的聚合类和迭代器类都很方便，无须修改原有代码，满足“开闭原则”的要求。\n\n**缺点：**\n\n- 由于迭代器模式将存储数据和遍历数据的职责分离，增加新的聚合类需要对应增加新的迭代器类，类的个数成对增加，这在一定程度上增加了系统的复杂性。\n- 抽象迭代器的设计难度较大，需要充分考虑到系统将来的扩展，例如 JDK 内置迭代器 Iterator 就无法实现逆向遍历，如果需要实现逆向遍历，只能通过其子类 ListIterator 等来实现，而 ListIterator 迭代器无法用于操作 Set 类型的聚合对象。在自定义迭代器时，创建一个考虑全面的抽象迭代器并不是件很容易的事情。\n\n### 6.5 中介者模式\n\n> 中介者模式`(Mediator Pattern`)：对象和对象之间借助第三方中介者进行通信。用一个中介对象（中介者）来封装一系列的对象交互，中介者使各对象不需要显式地相互引用，从而使其耦合松散，而且可以独立地改变它们之间的交互。中介者模式又称为调停者模式，它是一种对象行为型模式。\n\n![](../../../assets/article/designPattern/中介者.png)\n\n**举例：**\n\n中介者模式将一个网状的系统结构变成一个以中介者对象为中心的星形结构，在这个星型结构中，使用中介者对象与其他对象的一对多关系来取代原有对象之间的多对多关系。所有成员通过中介者交互，方便拓展新的成员，例如下面的例子，一场测试结束后，公布结果：告知解答出题目的人挑战成功，否则挑战失败。在这段代码中 A、B、C 之间没有直接发生关系，而是通过另外的 playerMiddle 对象建立链接，姑且将之当成是中介者模式了。\n\n```js\nconst player = function (name) {\n this.name = name;\n playerMiddle.add(name);\n};\nplayer.prototype.win = function () {\n playerMiddle.win(this.name);\n};\nplayer.prototype.lose = function () {\n playerMiddle.lose(this.name);\n};\nconst playerMiddle = (function () {\n //将就用下这个 demo, 这个函数充当中介者\n const players = [];\n const winArr = [];\n const loseArr = [];\n return {\n add: function (name) {\n players.push(name);\n },\n win: function (name) {\n winArr.push(name);\n if (winArr.length + loseArr.length === players.length) {\n this.show();\n }\n },\n lose: function (name) {\n loseArr.push(name);\n if (winArr.length + loseArr.length === players.length) {\n this.show();\n }\n },\n show: function () {\n for (let winner of winArr) {\n console.log(winner + '挑戰成功;');\n }\n for (let loser of loseArr) {\n console.log(loser + '挑战失败;');\n }\n },\n };\n})();\nconst a = new player('A 选手');\nconst b = new player('B 选手');\nconst c = new player('C 选手');\na.win();\nb.lose();\nc.win();\n// A 选手挑战成功;\n// B 选手挑战成功;\n// C 选手挑战失败;\n```\n\n**优点：**\n\n- 中介者模式简化了对象之间的交互，它用中介者和同事的一对多交互代替了原来同事之间的多对多交互，一对多关系更容易理解、维护和扩展，将原本难以理解的网状结构转换成相对简单的星型结构。\n- 中介者模式可将各同事对象解耦。中介者有利于各同事之间的松耦合，我们可以独立的改变和复用每一个同事和中介者，增加新的中介者和新的同事类都比较方便，更好地符合“开闭原则”。\n- 可以减少子类生成，中介者将原本分布于多个对象间的行为集中在一起，改变这些行为只需生成新的中介者子类即可，这使各个同事类可被重用，无须对同事类进行扩展。\n\n**缺点：**\n\n- 在具体中介者类中包含了大量同事之间的交互细节，可能会导致具体中介者类非常复杂，使得系统难以维护。\n\n### 6.6 备忘录模式\n\n> 备忘录模式 (`Memento Pattern`)：在不破坏封装的前提下，捕获一个对象的内部状态，并在该对象之外保存这个状态，以便日后对象使用或者对象恢复到以前的某个状态。它是一种对象行为型模式，其别名为 Token。\n\n![](../../../assets/article/designPattern/UML/行为型/备忘录.jpg)\n**举例：**\n\n备忘录模式提供了一种状态恢复的实现机制，使得用户可以方便地回到一个特定的历史步骤，当新的状态无效或者存在问题时，可以使用暂时存储起来的备忘录将状态复原，当前很多软件都提供了撤销操作，其中就使用了备忘录模式。\n\n当我们开发一个分页组件的时候，点击下一页获取新的数据，但是当点击上一页时，又重新获取数据，造成无谓的流量浪费，这时可以对数据进行缓存。\n\n```js\n// 备忘录模式伪代码\nvar Page = function () {\n // 通过 cache 对象缓存数据\n var cache = {};\n return function (page, fn) {\n if (cache[page]) {\n showPage(page, cache[page]);\n } else {\n $.post('/url', function (data) {\n showPage(page, data);\n cache[page] = data;\n });\n }\n fn && fn();\n };\n};\n```\n\n**优点：**\n\n- 它提供了一种状态恢复的实现机制，使得用户可以方便地回到一个特定的历史步骤，当新的状态无效或者存在问题时，可以使用暂时存储起来的备忘录将状态复原。\n- 备忘录实现了对信息的封装，一个备忘录对象是一种原发器对象状态的表示，不会被其他代码所改动。备忘录保存了原发器的状态，采用列表、堆栈等集合来存储备忘录对象可以实现多次撤销操作。\n\n**缺点：**\n\n- 资源消耗过大，如果需要保存的原发器类的成员变量太多，就不可避免需要占用大量的存储空间，每保存一次对象的状态都需要消耗一定的系统资源。\n\n### 6.7 观察者模式\n\n> 观察者模式 (`Observer Pattern)`：定义对象之间的一种一对多依赖关系，使得每当一个对象状态发生改变时，其相关依赖对象皆得到通知并被自动更新。观察者模式的别名包括发布 - 订阅（`Publish/Subscribe`）模式、模型 - 视图（`Model/View`）模式、源 - 监听器（`Source/Listener`）模式或从属者（`Dependents`）模式。观察者模式是一种对象行为型模式。\n\n![](../../../assets/article/designPattern/观察者.png)\n\n**举例：**\n\n观察者模式是使用频率最高的设计模式之一，它用于建立一种对象与对象之间的依赖关系，一个对象发生改变时将自动通知其他对象，其他对象将相应作出反应。\n\n在`JavaScript`中观察者模式的实现主要用事件模型，`DOM`事件。\n\n```js\n// 发布者\nvar pub = function () {\n console.log('欢迎订阅！');\n};\n// 订阅者\nvar sub = document.body;\n\n// 订阅者实现订阅\nsub.addEventListener('click', pub, false);\n```\n\n**优点：**\n\n- 观察者模式可以实现表示层和数据逻辑层的分离，定义了稳定的消息更新传递机制，并抽象了更新接口，使得可以有各种各样不同的表示层充当具体观察者角色。\n- 观察者模式在观察目标和观察者之间建立一个抽象的耦合。观察目标只需要维持一个抽象观察者的集合，无须了解其具体观察者。由于观察目标和观察者没有紧密地耦合在一起，因此它们可以属于不同的抽象化层次。\n- 观察者模式支持广播通信，观察目标会向所有已注册的观察者对象发送通知，简化了一对多系统设计的难度。\n- 观察者模式满足“开闭原则”的要求，增加新的具体观察者无须修改原有系统代码，在具体观察者与观察目标之间不存在关联关系的情况下，增加新的观察目标也很方便。\n\n**缺点：**\n\n- 如果一个观察目标对象有很多直接和间接观察者，将所有的观察者都通知到会花费很多时间。\n- 如果在观察者和观察目标之间存在循环依赖，观察目标会触发它们之间进行循环调用，可能导致系统崩溃。\n- 观察者模式没有相应的机制让观察者知道所观察的目标对象是怎么发生变化的，而仅仅只是知道观察目标发生了变化。\n\n### 6.8 状态模式\n\n> 状态模式 (`State Pattern`)：允许一个对象在其内部状态改变时改变它的行为，对象看起来似乎修改了它的类。其别名为状态对象 (`Objects for States`)，其实就是用一个对象或者数组记录一组状态，每个状态对应一个实现，实现的时候根据状态挨个去运行实现。状态模式是一种对象行为型模式。\n\n![](../../../assets/article/designPattern/状态.png)\n\n**举例：**\n\n状态模式用于解决复杂对象的状态转换以及不同状态下行为的封装问题。当系统中某个对象存在多个状态，这些状态之间可以进行转换，所以对象在不同状态下具有不同行为时可以使用状态模式。状态模式将一个对象的状态从该对象中分离出来，封装到专门的状态类中，使得对象状态可以灵活变化。\n\n比如超级玛丽，就可能同时有好几个状态比如 跳跃，移动，射击，蹲下 等，如果对这些动作一个个进行处理判断，需要多个 if-else 或者 switch 不仅丑陋不说，而且在遇到有组合动作的时候，实现就会变的更为复杂，这里可以使用状态模式来实现。\n\n状态模式的思路是：首先创建一个状态对象或者数组，内部保存状态变量，然后内部封装好每种动作对应的状态，然后状态对象返回一个接口对象，它可以对内部的状态修改或者调用。\n\n```js\nclass SuperMarry {\n constructor() {\n this._currentState = [];\n this.states = {\n jump() {\n console.log('跳跃！');\n },\n move() {\n console.log('移动！');\n },\n shoot() {\n console.log('射击！');\n },\n squat() {\n console.log('蹲下！');\n },\n };\n }\n\n change(arr) {\n // 更改当前动作\n this._currentState = arr;\n return this;\n }\n\n go() {\n console.log('触发动作');\n this._currentState.forEach((T) => this.states[T] && this.states[T]());\n return this;\n }\n}\n\nnew SuperMarry()\n .change(['jump', 'shoot'])\n .go() // 触发动作 跳跃！射击！\n .go() // 触发动作 跳跃！射击！\n .change(['squat'])\n .go(); // 触发动作 蹲下！\n```\n\n**优点：**\n\n- 封装了状态的转换规则，在状态模式中可以将状态的转换代码封装在环境类或者具体状态类中，可以对状态转换代码进行集中管理，而不是分散在一个个业务方法中。\n- 将所有与某个状态有关的行为放到一个类中，只需要注入一个不同的状态对象即可使环境对象拥有不同的行为。\n- 允许状态转换逻辑与状态对象合成一体，而不是提供一个巨大的条件语句块，状态模式可以让我们避免使用庞大的条件语句来将业务方法和状态转换代码交织在一起。\n- 可以让多个环境对象共享一个状态对象，从而减少系统中对象的个数。\n\n**缺点：**\n\n- 状态模式的使用必然会增加系统中类和对象的个数，导致系统运行开销增大。\n- 状态模式的结构与实现都较为复杂，如果使用不当将导致程序结构和代码的混乱，增加系统设计的难度。\n- 状态模式对“开闭原则”的支持并不太好，增加新的状态类需要修改那些负责状态转换的源代码，否则无法转换到新增状态；而且修改某个状态类的行为也需修改对应类的源代码。\n\n### 6.9 策略模式\n\n> 策略模式 (`Strategy Pattern`)：定义一些列算法，把他们封装起来，并且可以相互替换。就是把看似毫无联系的代码提取封装、复用，使之更容易被理解和拓展。常见的用于一次 if 判断、switch 枚举、数据字典等流程判断语句中。也称为政策模式 (`Policy`)。策略模式是一种对象行为型模式。\n\n![](../../../assets/article/designPattern/策略.png)\n\n**举例：**\n\n使用策略模式时，我们可以定义一些策略类，每一个策略类中封装一种具体的算法。在这里，每一个封装算法的类我们都可以称之为一种策略，根据传入不同的策略类，使环境类执行不同策略类中的算法。\n\n在游戏中，我们每玩完一局游戏都有对用户进行等级评价，比如 S 级 4 倍经验，A 级 3 倍经验，B 级 2 倍经验，其他 1 倍经验，用函数来表达如下：\n\n```js\n// 改为策略模式 分成两个函数来写\nconst strategy = {\n S: function (experience) {\n return 4 * experience;\n },\n A: function (experience) {\n return 3 * experience;\n },\n B: function (experience) {\n return 2 * experience;\n },\n};\n// getExperience 可以复用\nfunction getExperience(strategy, level, experience) {\n return level in strategy ? strategy[level](experience) : experience;\n}\nvar s = getExperience(strategy, 'S', 100);\nvar a = getExperience(strategy, 'A', 100);\nconsole.log(s, a); // 400 300\n```\n\n```js\n// 指令处理集合\nvar compileUtil = {\n // v-text 更新视图原理\n text: function(node, vm, exp) {\n this.bind(node, vm, exp, 'text');\n },\n // v-html 更新视图原理\n html: function(node, vm, exp) {\n this.bind(node, vm, exp, 'html');\n },\n // v-class 绑定原理\n class: function(node, vm, exp) {\n this.bind(node, vm, exp, 'class');\n },\n bind: function(node, vm, exp, dir) {\n // 不同指令触发视图更新\n var updaterFn = updater[dir + 'Updater'];\n updaterFn && updaterFn(node, this._getVMVal(vm, exp));\n new Watcher(vm, exp, function(value, oldValue) {\n updaterFn && updaterFn(node, value, oldValue);\n });\n }\n ......\n}\n```\n\n**优点：**\n\n- 策略模式提供了对“开闭原则”的完美支持，用户可以在不修改原有系统的基础上选择算法或行为，也可以灵活地增加新的算法或行为。\n- 策略模式提供了管理相关的算法族的办法。策略类的等级结构定义了一个算法或行为族，恰当使用继承可以把公共的代码移到抽象策略类中，从而避免重复的代码。\n- 策略模式提供了一种可以替换继承关系的办法。如果不使用策略模式，那么使用算法的环境类就可能会有一些子类，每一个子类提供一种不同的算法。但是，这样一来算法的使用就和算法本身混在一起，不符合“单一职责原则”，决定使用哪一种算法的逻辑和该算法本身混合在一起，从而不可能再独立演化；而且使用继承无法实现算法或行为在程序运行时的动态切换。\n- 使用策略模式可以避免多重条件选择语句。多重条件选择语句不易维护，它把采取哪一种算法或行为的逻辑与算法或行为本身的实现逻辑混合在一起，将它们全部硬编码 (Hard Coding) 在一个庞大的多重条件选择语句中，比直接继承环境类的办法还要原始和落后。\n- 策略模式提供了一种算法的复用机制，由于将算法单独提取出来封装在策略类中，因此不同的环境类可以方便地复用这些策略类。\n\n**缺点：**\n\n- 客户端必须知道所有的策略类，并自行决定使用哪一个策略类。这就意味着客户端必须理解这些算法的区别，以便适时选择恰当的算法。换言之，策略模式只适用于客户端知道所有的算法或行为的情况。\n- 策略模式将造成系统产生很多具体策略类，任何细小的变化都将导致系统要增加一个新的具体策略类。\n- 无法同时在客户端使用多个策略类，也就是说，在使用策略模式时，客户端每次只能使用一个策略类，不支持使用一个策略类完成部分功能后再使用另一个策略类来完成剩余功能的情况。\n\n### 6.10 模板方法模式\n\n> 模板方法模式：定义一个操作中算法的框架，而将一些步骤延迟到子类中。模板方法模式使得子类可以不改变一个算法的结构即可重定义该算法的某些特定步骤。\n\n![](../../../assets/article/designPattern/模板.png)\n\n**举例：**\n\n模板方法模式的使用场景\n\n- 模板方法模式常被架构师用于搭建项目的框架，架构师定好了框架的骨架，程序员继承框架的结构之后，负责往里面填空\n- 钩子方法：各种框架中的钩子函数往往在初始化时就规定各个钩子函数的名称以及执行时机，对于使用者只需要在钩子函数中注入自定义逻辑代码即可\n- 回调函数：回调函数在特定的时机执行，但是具体的操作交给具体的函数实现。把变化的部分封装成一个函数剩下的就成了模板\n\n模板方法模式具体应用又分为三类：\n\n- 抽象方法：一个抽象方法由抽象类声明、由其具体子类实现。\n\n- 具体方法：一个具体方法由一个抽象类或具体类声明并实现，其子类可以进行覆盖也可以直接继承。\n\n- 钩子方法：一个钩子方法由一个抽象类或具体类声明并实现，而其子类可能会加以扩展。通常在父类中给出的实现是一个空实现，并以该空实现作为方法的默认实现，当然钩子方法也可以提供一个非空的默认实现。通过在子类中实现的钩子方法对父类方法的执行进行约束，实现子类对父类行为的反向控制。\n\n泡一杯咖啡\n\n先我们先来泡一杯咖啡，一般来说，泡咖啡的步骤通常如下：\n\n1.先把水煮沸；\n\n2.用沸水冲泡咖啡；\n\n3.把咖啡倒进杯子；\n\n4.加糖和牛奶。\n\n我们用 es5 来得到一杯香浓的咖啡吧：\n\n```js\nvar Coffee = function () {};\nCoffee.prototype.boilWater = function () {\n console.log('水煮开了');\n};\nCoffee.prototype.brewCoffeeGriends = function () {\n console.log('用沸水冲泡咖啡');\n};\nCoffee.prototype.pourInCup = function () {\n console.log('把咖啡倒进杯子');\n};\nCoffee.prototype.addSugarAndMilk = function () {\n console.log('加糖和牛奶');\n};\n// 封装 将实现的细节交给类的内部\nCoffee.prototype.init = function () {\n this.boilWater();\n this.brewCoffeeGriends();\n this.pourInCup();\n this.addSugarAndMilk();\n};\nvar coffee = new Coffee();\ncoffee.init();\n```\n\n泡一壶茶\n\n其实呢，泡茶的步骤跟泡咖啡的步骤相差不大，大致是这样的：\n\n1.把水煮沸；\n\n2.用沸水浸泡茶叶；\n\n3.把茶水倒进杯子；\n\n4.加柠檬。\n\n来，咱用 es6 来泡茶：\n\n```js\nclass Tea {\n constructor() {}\n boilWater() {\n console.log('把水烧开');\n }\n steepTeaBag() {\n console.log('浸泡茶叶');\n }\n pourInCup() {\n console.log('倒进杯子');\n }\n addLemon() {\n console.log('加柠檬');\n }\n init() {\n this.boilWater();\n this.steepTeaBag();\n this.pourInCup();\n this.addLemon();\n }\n}\nvar tea = new Tea();\ntea.init();\n```\n\n现在到了思考的时间，我们刚刚泡了一杯咖啡和一壶茶，有没有觉得这两个过程是大同小异的。我们能很容易的就找出他们的共同点，不同点就是原料不同嘛，茶和咖啡，我们可以把他们抽象为\"饮料\"哇；泡的方式不同嘛，一个是冲泡，一个是浸泡，我们可以把这个行为抽象为\"泡\"；加入的调料也不同咯，加糖和牛奶，加柠檬，它们也可以抽象为\"调料\"吖。\n\n这么一分析，是不是很清楚了吖，我们整理一下就是：\n\n1.把水煮沸；\n\n2.用沸水冲泡饮料；\n\n3.把饮料倒进杯子；\n\n4.加调料。\n\n大家请注意！大家请注意！主角来了！之前我们已经扔出了概念，所以我们现在可以创建一个抽象父类来表示泡一杯饮料的过程。那么，抽象父类？\n\n抽象类？\n\n抽象类是不能被实例化的，一定是用来继承的。继承了抽象类的所有子类都将拥有跟抽象类一致的接口方法，抽象类的主要作用就是为它的子类定义这些公共接口。\n\n通过上面分析，这里具体来说就是要把泡茶和泡咖啡的共同步骤共同点找出来，封装到父类，也就是抽象类中，然后不同的步骤写在子类中，也就是茶和咖啡中。抽象类既然不能被实例化，不怕啊，子类就是他的实例化。\n\n泡饮料啦！\n\n```js\nvar Beverage = function () {};\nBeverage.prototype.boilWater = function () {\n console.log('把水煮沸');\n};\nBeverage.prototype.brew = function () {};\nBeverage.prototype.pourInCup = function () {};\nBeverage.prototype.addCondiments = function () {};\n// 抽象方法\nBeverage.prototype.init = function () {\n this.boilWater();\n this.brew();\n this.pourInCup();\n this.addCondiments();\n};\nvar Coffee = function () {\n // 将父类的构造方法拿来执行一下\n Beverage.apply(this, arguments);\n // 就像 es6 的 super 执行 执行后 this 才会有对象的属性\n};\nCoffee.prototype = new Beverage();\nvar coffee = new Coffee();\ncoffee.init();\nvar Tea = function () {};\nTea.prototype = new Beverage();\nTea.prototype.brew = function () {\n console.log('用沸水浸泡茶叶');\n};\nTea.prototype.pourInCup = function () {\n console.log('把茶叶倒进杯子');\n};\nTea.prototype.addCondiments = function () {\n console.log('加柠檬');\n};\nvar tea = new Tea();\ntea.init();\n```\n\n这里既泡了咖啡又泡了茶，是不是没有之前那么繁琐呢，这里的代码可是很高级的呢。\n\n这里用一个父类 Beverage 来表示 Coffee 和 Tea，然后子类就是后面的 Coffee 和 Tea 啦，因为这里的 Beverage 是一个抽象的存在，需要子类来继承它。泡饮品的流程，可以理解为一个模板模式，抽象类 Beverage，抽象方法 init() 在子类中实现。js 的继承是基于原型链的继承，这里 prototype 就是类的原型链。这里由于 coffee 对象和 tea 对象的原型 prototype 上都没有对应的 init(),所以请求会顺着原型链，找到父类 Beverage 的 init()。子类寻找对应的属性和方法的时候会顺着原型链去查找，先找自己，没有找到会顺着去父类里面查找。\n\nBeverage.prototype.init 被称为模板方法的原因是，该方法中封装了子类的算法框架，它作为一个算法的模板，指导子类以何种顺序去执行哪些方法。\n\n**优点：**\n\n- 在父类中形式化地定义一个算法，而由它的子类来实现细节的处理，在子类实现详细的处理算法时并不会改变算法中步骤的执行次序。\n- 模板方法模式是一种代码复用技术，它在类库设计中尤为重要，它提取了类库中的公共行为，将公共行为放在父类中，而通过其子类来实现不同的行为，它鼓励我们恰当使用继承来实现代码复用。\n- 可实现一种反向控制结构，通过子类覆盖父类的钩子方法来决定某一特定步骤是否需要执行。\n- 在模板方法模式中可以通过子类来覆盖父类的基本方法，不同的子类可以提供基本方法的不同实现，更换和增加新的子类很方便，符合单一职责原则和开闭原则。\n\n**缺点：**\n\n- 需要为每一个基本方法的不同实现提供一个子类，如果父类中可变的基本方法太多，将会导致类的个数增加，系统更加庞大，设计也更加抽象，此时，可结合桥接模式来进行设计。\n\n### 6.11 访问者模式\n\n> 访问者模式 (`Visitor Pattern`):提供一个作用于某对象结构中的各元素的操作表示，它使我们可以在不改变各元素的类的前提下定义作用于这些元素的新操作。访问者模式是一种对象行为型模式。\n\n![](../../../assets/article/designPattern/访问者.png)\n\n**举例：**\n\n访问者模式是一种较为复杂的行为型设计模式，它包含访问者和被访问元素两个主要组成部分，这些被访问的元素通常具有不同的类型，且不同的访问者可以对它们进行不同的访问操作。访问者模式使得用户可以在不修改现有系统的情况下扩展系统的功能，为这些不同类型的元素增加新的操作。\n\n在使用访问者模式时，被访问元素通常不是单独存在的，它们存储在一个集合中，这个集合被称为「对象结构」，访问者通过遍历对象结构实现对其中存储的元素的逐个操作。\n\n```js\n// 访问者模式：DOM 事件绑定\nvar bindEvent = function(dom, type, fn, data) {\n if (dom.addEventListener) {\n dom.addEventListener(type, fn, false);\n } else if (dom.attachEvent) {\n // dom.attachEvent('on'+type, fn);\n var data = data || {};\n dom.attachEvent('on' + type, function(e) {\n // 在 IE 中 this 指向 window，使用 call 改变 this 的指向\n fn.call(dom, e, data);\n });\n } else {\n dom['on' + type] = fn;\n }\n}\nfunction $(id) {\n return document.getElementById(id);\n}\n​\nbindEvent($(demo), 'click', function() {\n // this 指向 dom 对象\n this.style.background = 'red';\n});\n​\nbindEvent($('btn'), 'click', function(e, data) {\n $('text').innerHTML = e.type + data.text + this.tagName;\n}, { text: 'demo' });\n```\n\n访问者模式的思想就是在不改变操作对象的同时，为它添加新的操作方法，以实现对操作对象的访问。我们知道，call 和 apply 的作用就是更改函数执行时的作用域，这正是访问者模式的精髓。通过 call、apply 这两种方式我们就可以让某个对象在其它作用域中运行。\n\n```js\n// 数组方法封装\nvar Visitor = (function() {\n return {\n splice: function() {\n var args = Array.prototype.splice.call(arguments, 1);\n return Array.prototype.splice.apply(arguments[0], args);\n },\n push: function() {\n var len = arguments[0].length || 0;\n var args = this.splice(arguments, 1);\n arguments[0].length = len + arguments.length - 1;\n return Array.prototype.push.apply(arguments[0], args);\n },\n pop: function() {\n return Array.prototype.pop.apply(arguments[0]);\n }\n }\n})();\n​\nvar a = new Object();\nVisitor.push(a,1,2,3,4);\nVisitor.push(a,4,5,6);\nVisitor.pop(a);\nVisitor.splice(a,2);\n```\n\n访问者模式解决了数据与数据的操作方法之间的耦合，让数据的操作方法独立于数据，使其可以自由演变。因此，访问者模式更适合于那些数据稳定、但数据的操作方法易变的环境下。\n\n**优点：**\n\n- 增加新的访问操作很方便。使用访问者模式，增加新的访问操作就意味着增加一个新的具体访问者类，实现简单，无须修改源代码，符合“开闭原则”。\n- 将有关元素对象的访问行为集中到一个访问者对象中，而不是分散在一个个的元素类中。类的职责更加清晰，有利于对象结构中元素对象的复用，相同的对象结构可以供多个不同的访问者访问。\n- 让用户能够在不修改现有元素类层次结构的情况下，定义作用于该层次结构的操作。\n\n**缺点：**\n\n- 增加新的元素类很困难。在访问者模式中，每增加一个新的元素类都意味着要在抽象访问者角色中增加一个新的抽象操作，并在每一个具体访问者类中增加相应的具体操作，这违背了“开闭原则”的要求。\n- 破坏封装。访问者模式要求访问者对象访问并调用每一个元素对象的操作，这意味着元素对象有时候必须暴露一些自己的内部操作和内部状态，否则无法供访问者访问。\n\n## 总结\n\n系统地学习设计模式后，你可以在过往的开发经历中发现，设计模式是无处不在的。在学习设计模式之前的很多时候我们是凭借过往经验和智慧来完善系统的设计，而这些经验很多和某个设计模式的思想不谋而合。\n\n还有一些地方没有完全理解，文中有误之处还望不吝指出。\n\n## 参考资料\n\n- [Study-Plan](https://github.com/xietao3/Study-Plan)\n- [javaScript 设计模式统计](https://zhuanlan.zhihu.com/p/472719016)\n- [ES6 系列之我们来聊聊装饰器](https://juejin.cn/post/6844903713866252296)\n- [设计模式之生成器模式](https://segmentfault.com/a/1190000038250020)\n- [https://juejin.im/user/57f8ffda2e958a005581e3c0/posts](https://juejin.im/user/57f8ffda2e958a005581e3c0/posts)\n- [https://design-patterns.readthedocs.io/zh_CN/latest/index.html](https://design-patterns.readthedocs.io/zh_CN/latest/index.html)\n- [https://blog.csdn.net/lovelion/article/details/17517213](https://blog.csdn.net/lovelion/article/details/17517213)\n- [https://github.com/skyming/Trip-to-iOS-Design-Patterns](https://github.com/skyming/Trip-to-iOS-Design-Patterns)\n" }, { "path": "packages/docs/cn/src/article/doc_preview.md", "content": "

最全的 docx,pptx,xlsx(excel),pdf 文件预览方案总结

\n\n最近遇到了文件预览的需求，但一搜索发现，这还不是一个简单的功能。于是又去查询了很多资料，调研了一些方案，也踩了好多坑。最后总结方案如下\n\n1. 花钱解决 (使用市面上现有的文件预览服务)\n 1. 微软\n 2. google\n 3. 阿里云 IMM\n 4. XDOC\n 5. Office Web 365\n 6. wps 开放平台\n2. 前端方案\n 1. pptx 的预览方案\n 2. pdf 的预览方案\n 3. docx 的预览方案\n 4. xlsx(excel) 的预览方案\n 5. 前端预览方案总结\n3. 服务端方案\n 1. openOffice\n 2. kkFileView\n 3. onlyOffice\n\n如果有其他人也遇到了同样的问题，有了这篇文章，希望能更方便的解决。\n\n基本涵盖了所有解决方案。因此，标题写上 **最全** 的文件预览方案调研总结，应该不为过吧。\n\n## 一：市面上现有的文件预览服务\n\n### 1.微软\n\n`docx`,`pptx`,`xlsx`可以说是`office`三件套，那自然得看一下 **微软官方** 提供的文件预览服务。使用方法特别简单，只需要将文件链接，拼接到参数后面即可。\n\n记得`encodeURL`\n\n```js\nhttps://view.officeapps.live.com/op/view.aspx?src=${encodeURIComponent(url)}\n```\n\n#### (1).PPTX 预览效果：\n\n![image.png](../../../assets/article/docPreview/ms_ppt.webp)\n\n- 优点：还原度很高，功能很丰富，可以选择翻页，甚至支持点击播放动画。\n- 缺点：不知道是不是墙的原因，加载稍慢。\n\n#### (2).Excel 预览效果：\n\n![image.png](../../../assets/article/docPreview/ms_excel.webp)\n\n#### (3).Doxc 预览效果\n\n![image.png](../../../assets/article/docPreview/ms_word.webp)\n\n#### (4).PDF 预览效果\n\n这个我测试没有成功，返回了一个错误，其他人可以试试。\n\n![image.png](../../../assets/article/docPreview/ms_file_not.webp)\n\n#### (5).总的来说\n\n对于`docx`,`pptx`,`xlsx`都有较好的支持，`pdf`不行。\n\n还有一个坑点是：这个服务是否稳定，有什么限制，是否收费，都查不到一个定论。在`office`官方网站上甚至找不到介绍这个东西的地方。\n\n目前只能找到一个`Q&A`:https://answers.microsoft.com/en-us/msoffice/forum/all/what-is-the-status-of-viewofficeappslivecom/830fd75c-9b47-43f9-89c9-4303703fd7f6\n\n微软官方人员回答表示：\n\n![image.png](../../../assets/article/docPreview/ms_answer.webp)\n\n翻译翻译，就是：几乎永久使用，没有收费计划，不会存储预览的文件数据，限制文件`10MB`，建议用于 **查看互联网上公开的文件**。\n\n但经过某些用户测试发现：\n\n![image.png](../../../assets/article/docPreview/ms_answer_2.webp)\n\n使用了微软的文件预览服务，然后删除了文件地址，仍然可访问，但过一段时间会失效。\n\n### 2.Google Drive 查看器\n\n接入简单，同 `Office Web Viewer`，只需要把 `src` 改为`https://drive.google.com/viewer?url=${encodeURIComponent(url)}`即可。\n\n限制`25MB`,支持以下格式：\n\n![image.png](../../../assets/article/docPreview/google_doc_view.webp)\n\n测试效果，支持`docx,pptx,xlsx,pdf`预览，但`pptx`预览的效果不如微软，没有动画效果，样式有小部分会错乱。\n\n**由于某些众所周知的原因，不可用**\n\n### 3.阿里云 IMM\n\n官方文档如下：https://help.aliyun.com/document_detail/63273.html\n\n![image.png](../../../assets/article/docPreview/ali_doc.webp)\n\n付费使用\n\n### 4.XDOC 文档预览\n\n说了一些大厂的，在介绍一些其他的，**需要自行分辨**\n\n官网地址：https://view.xdocin.com/view-xdocin-com_6x5f4x.htm\n\n![image.png](../../../assets/article/docPreview/xdoc.webp)\n\n### 5.Office Web 365\n\n需要注意的是，虽然名字很像`office`，但我们看网页的`Copyright`可以发现，其实是一个西安的公司，**不是微软**。\n\n但毕竟也提供了文件预览的服务\n\n官网地址：https://www.officeweb365.com/\n\n![image.png](../../../assets/article/docPreview/ow365.webp)\n\n### 6.WPS 开放平台\n\n官方地址：https://solution.wps.cn/\n\n![image.png](../../../assets/article/docPreview/wps_office.webp)\n\n付费使用，价格如下：\n\n![image.png](../../../assets/article/docPreview/wps_office_price.webp)\n\n## 二：前端处理方案\n\n### 1.pptx 的预览方案\n\n先查一下有没有现成的轮子，目前`pptx`的开源预览方案能找到的只有这个：https://github.com/g21589/PPTX2HTML。但已经六七年没有更新，也没有维护，笔者使用的时候发现有很多兼容性问题。\n\n简单来说就是，没有。对于这种情况，我们可以自行解析，主要步骤如下：\n\n1. 查询`pptx`的国际标准\n2. 解析`pptx`文件\n3. 渲染成`html`或者`canvas`进行展示\n\n我们先去找一下`pptx`的国际标准，官方地址：[officeopenxml](http://officeopenxml.com/)\n\n先解释下什么是`officeopenxml`:\n\n> Office OpenXML，也称为 OpenXML 或 OOXML，是一种基于 XML 的办公文档格式，包括文字处理文档、电子表格、演示文稿以及图表、图表、形状和其他图形材料。该规范由微软开发，并于 2006 年被 ECMA 国际采用为 ECMA-376。第二个版本于 2008 年 12 月发布，第三个版本于 2011 年 6 月发布。该规范已被 ISO 和 IEC 采用为 ISO/IEC 29500。\n\n> 虽然 Microsoft 继续支持较旧的二进制格式 (.doc、.xls 和.ppt)，但 OOXML 现在是所有 Microsoft Office 文档 (.docx、.xlsx 和.pptx) 的默认格式。\n\n由此可见，`Office OpenXML`由微软开发，目前已经是国际标准。接下来我们看一下`pptx`里面有哪些内容，具体可以看`pptx`的官方标准：[officeopenxml-pptx](http://officeopenxml.com/anatomyofOOXML-pptx.php)\n\n> PresentationML 或.pptx 文件是一个**zip 文件**，其中包含许多“部分”（通常是 UTF-8 或 UTF-16 编码）或 XML 文件。该包还可能包含其他媒体文件，例如图像。该结构根据 OOXML 标准 ECMA-376 第 2 部分中概述的开放打包约定进行组织。\n\n![image.png](../../../assets/article/docPreview/xml.webp)\n\n根据国际标准，我们知道，`pptx`文件本质就是一个`zip`文件，其中包含许多部分：\n\n> 部件的数量和类型将根据演示文稿中的内容而有所不同，但始终会有一个 [Content_Types].xml、一个或多个关系（.rels）部件和一个演示文稿部件（演示文稿.xml），它位于 ppt 文件夹中，用于 Microsoft Powerpoint 文件。通常，还将至少有一个幻灯片部件，以及一张母版幻灯片和一张版式幻灯片，从中形成幻灯片。\n\n那么`js`如何读取`zip`呢？\n\n找到一个工具：https://www.npmjs.com/package/jszip\n\n于是我们可以开始尝试解析`pptx`了。\n\n```ts\nimport JSZip from 'jszip';\n// 加载 pptx 数据\nconst zip = await JSZip.loadAsync(pptxData);\n```\n\n- 解析`[Content_Types].xml`\n\n每个`pptx`必然会有一个 `[Content_Types].xml`。此文件包含包中部件的所有内容类型的列表。每个部件及其类型都必须列在 `[Content_Types].xml` 中。通过它里面的内容，可以解析其他的文件数据\n\n```ts\nconst filesInfo = await getContentTypes(zip);\n\nasync function getContentTypes(zip: JSZip) {\n const ContentTypesJson = await readXmlFile(zip, '[Content_Types].xml');\n const subObj = ContentTypesJson['Types']['Override'];\n const slidesLocArray = [];\n const slideLayoutsLocArray = [];\n for (let i = 0; i < subObj.length; i++) {\n switch (subObj[i]['attrs']['ContentType']) {\n case 'application/vnd.openxmlformats-officedocument.presentationml.slide+xml':\n slidesLocArray.push(subObj[i]['attrs']['PartName'].substr(1));\n break;\n case 'application/vnd.openxmlformats-officedocument.presentationml.slideLayout+xml':\n slideLayoutsLocArray.push(subObj[i]['attrs']['PartName'].substr(1));\n break;\n default:\n }\n }\n return {\n slides: slidesLocArray,\n slideLayouts: slideLayoutsLocArray,\n };\n}\n```\n\n- 解析演示文稿\n\n先获取`ppt`目录下的`presentation.xml`演示文稿的大小\n\n由于演示文稿是`xml`格式，要真正的读取内容需要执行 `readXmlFile`\n\n```ts\nconst slideSize = await getSlideSize(zip);\nasync function getSlideSize(zip: JSZip) {\n const content = await readXmlFile(zip, 'ppt/presentation.xml');\n const sldSzAttrs = content['p:presentation']['p:sldSz']['attrs'];\n return {\n width: (parseInt(sldSzAttrs['cx']) * 96) / 914400,\n height: (parseInt(sldSzAttrs['cy']) * 96) / 914400,\n };\n}\n```\n\n- 加载主题\n\n根据 `officeopenxml`的标准解释\n\n> 每个包都包含一个关系部件，用于定义其他部件之间的关系以及与包外部资源的关系。这样可以将关系与内容分开，并且可以轻松地更改关系，而无需更改引用目标的源。\n\n> 除了包的关系部分之外，作为一个或多个关系源的每个部件都有自己的关系部分。每个这样的关系部件都可以在部件的\\_rels 子文件夹中找到，并通过在部件名称后附加“.rels”来命名。\n\n其中主题的相关信息就在`ppt/_rels/presentation.xml.rels`中\n\n```ts\nasync function loadTheme(zip: JSZip) {\n const preResContent = await readXmlFile(zip, 'ppt/_rels/presentation.xml.rels');\n const relationshipArray = preResContent['Relationships']['Relationship'];\n let themeURI;\n if (relationshipArray.constructor === Array) {\n for (let i = 0; i < relationshipArray.length; i++) {\n if (\n relationshipArray[i]['attrs']['Type'] ===\n 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme'\n ) {\n themeURI = relationshipArray[i]['attrs']['Target'];\n break;\n }\n }\n } else if (\n relationshipArray['attrs']['Type'] === 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme'\n ) {\n themeURI = relationshipArray['attrs']['Target'];\n }\n\n if (themeURI === undefined) {\n throw Error(\"Can't open theme file.\");\n }\n\n return readXmlFile(zip, 'ppt/' + themeURI);\n}\n```\n\n后续`ppt`里面的其他内容，都可以这么去解析。根据`officeopenxml`标准，可能包含：\nPart | Description |\n| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Comments Authors | Contains information about each author who has added a comment to the presentation. |\n| Comments | Contains comments for a single slide. |\n| Handout Master | Contains the look, position, and size of the slides, notes, header and footer text, date, or page number on the presentation's handout. There can be only one such part. |\n| Notes Master | Contains information about the content and formatting of all notes pages. There can be only one such part. |\n| Notes Slide | Contains the notes for a single slide. |\n| Presentation | Contains the definition of a slide presentation. There must be one and only one such part. See [Presentation](http://officeopenxml.com/PrPresentation.php). |\n| Presentation Properties | Contains all of the presentation's properties. There must be one and only one such part. |\n| Slide | Contains the content of a single slide. |\n| Slide Layout | Contains the definition for a slide template. It defines the default appearance and positioning of drawing objects on the slide. There must be one or more such parts. |\n| Slide Master | Contains the master definition of formatting, text, and objects that appear on each slide in the presentation that is derived from the slide master. There must be one or more such parts. |\n| Slide Synchronization Data | Contains properties specifying the current state of a slide that is being synchronized with a version of the slide stored on a central server. |\n| User-Defined Tags | Contains a set of user-defined properties for an object in a presentation. There can be zero or more such parts. |\n| View Properties | Contains display properties for the presentation.\n\n等等内容，我们根据标准一点点解析并渲染就好了。\n\n完整源码：[ranui](https://github.com/chaxus/ran/tree/main/packages/ranui)\n\n使用文档：[preview 组件](https://chaxus.github.io/ran/src/ranui/preview/)\n\n### 2.pdf 的预览方案\n\n#### (1).iframe 和 embed\n\n`pdf`比较特别，一般的浏览器默认支持预览`pdf`。因此，我们可以使用浏览器的能力：\n\n```html\n