# @clinic/clinic-common 中文文档 规范地址：https://npmcn.com/package/%40clinic/clinic-common/ 版本：7\.1\.0 npm 元数据更新时间：2022-08-23T17:41:22.762Z 中文译文更新时间：2026-11-10T01:45:33.200Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40clinic/clinic-common 原文对照：https://npmcn.com/package/%40clinic/clinic-common/?lang=original 项目主页：https://github.com/clinicjs/node-clinic-common#readme 源码仓库：https://github.com/clinicjs/node-clinic-common ## 关键信息（来自 npm 元数据） - 包体积（解压后）：505 kB，320 个文件 - 模块格式：CommonJS - TypeScript 类型：未声明 - Node.js 要求：\>= 12\.13\.0 - 运行依赖：9 个 - 首次发布：2021-11-11T21:13:00.353Z - 最新版本发布：2022-08-23T17:41:22.594Z - 近 30 天下载量：182511（2026-10-10 至 2026-11-08，npm 官方下载统计） - 已发布版本数：2（近 12 个月 0 个） ## 中文简介 Clinic.js套房共用部分 ## 安装 ```sh npm install @clinic/clinic-common ``` 也可以使用：`pnpm add @clinic/clinic-common`、`yarn add @clinic/clinic-common`、`bun add @clinic/clinic-common` ## README # 常见诊所.js 整个诊所的共同功能. 目录 - [节点- clinic- 常见](https://npmcn.com/package/%40clinic/clinic-common/#readme-node-clinic-common) - [用户](https://npmcn.com/package/%40clinic/clinic-common/#readme-utils) - [`getLoggingPaths(toolName, toolSpecificFiles=[])`](https://npmcn.com/package/%40clinic/clinic-common/#readme-getloggingpathstoolname-toolspecificfiles) - [`checkForTranspiledCode(fileName)`](https://npmcn.com/package/%40clinic/clinic-common/#readme-checkfortranspiledcode-filename) - [脚本](https://npmcn.com/package/%40clinic/clinic-common/#readme-scripts) - [`buildJs(opts = {})`](https://npmcn.com/package/%40clinic/clinic-common/#readme-buildjsopts) - [使用量](https://npmcn.com/package/%40clinic/clinic-common/#readme-usage) - [`buildCss(opts = {})`](https://npmcn.com/package/%40clinic/clinic-common/#readme-buildcssopts) - [使用量](https://npmcn.com/package/%40clinic/clinic-common/#readme-usage) - [模板](https://npmcn.com/package/%40clinic/clinic-common/#readme-templates) - [`mainTemplate(opts = {})`](https://npmcn.com/package/%40clinic/clinic-common/#readme-maintemplateopts) - [使用量](https://npmcn.com/package/%40clinic/clinic-common/#readme-usage) - [样式](https://npmcn.com/package/%40clinic/clinic-common/#readme-styles) - [使用量](https://npmcn.com/package/%40clinic/clinic-common/#readme-usage) - [标准](https://npmcn.com/package/%40clinic/clinic-common/#readme-standards) - [细目](https://npmcn.com/package/%40clinic/clinic-common/#readme-breakdown) - [图标](https://npmcn.com/package/%40clinic/clinic-common/#readme-icons) - [图像](https://npmcn.com/package/%40clinic/clinic-common/#readme-images) - [构成部分](https://npmcn.com/package/%40clinic/clinic-common/#readme-components) - [按钮](https://npmcn.com/package/%40clinic/clinic-common/#readme-button) - [链接](https://npmcn.com/package/%40clinic/clinic-common/#readme-link) - [降级](https://npmcn.com/package/%40clinic/clinic-common/#readme-dropdown) - [复选框](https://npmcn.com/package/%40clinic/clinic-common/#readme-checkbox) - [重叠](https://npmcn.com/package/%40clinic/clinic-common/#readme-contexoverlay) - [走过去](https://npmcn.com/package/%40clinic/clinic-common/#readme-walkthrough) - [行走按钮](https://npmcn.com/package/%40clinic/clinic-common/#readme-walkthroughbutton) - [帮助者](https://npmcn.com/package/%40clinic/clinic-common/#readme-helpers) - [旋转器](https://npmcn.com/package/%40clinic/clinic-common/#readme-spinner) - [许可证](https://npmcn.com/package/%40clinic/clinic-common/#readme-license) ## 用户 ### `getLoggingPaths(toolName, toolSpecificFiles=[])` 创建用于构建工具日志信息路径的函数 。 返回函数返回对象映射虚拟路径名称到实际路径名称,例如: ```js { '/systeminfo': '{pid}.clinic-{toolName}/{pid}.clinic-{toolName}-systeminfo' } ``` 参数 : - `toolName` - 名为Clinic.js工具. - `toolSpecificFiles` - 要生成的文件名的阵列, 在默认值之上(`/`, (中文(简体) ), `/systeminfo`) (中文(简体) ). 若为 `toolName` 是“ 博士” , 默认为 `['/traceevent', '/processstat']`。 。 。 . 若为 `toolName` 是“ bubbleprof ” , 默认为 `['/traceevent', '/stacktrace']`。 。 。 . ### `checkForTranspiledCode(fileName)` 用于检查文件内容以获取转录代码的函数 。 检查还包括搜索一个源地图注释. 参数 : - `fileName` - 正在传递的文件的路径. * * * ## 脚本 ### `buildJs(opts = {})` 返回浏览器捆绑( 可读流) #### 使用量 ```js const buildJs = require('@clinic/clinic-common/scripts/build-js') const scriptFile = buildJs({ basedir: __dirname, (String) debug: this.debug, (Boolean) fakeDataPath, (String) scriptPath, (String) beforeBundle: b => b.doSomethingWithBundle() (Function) }) ``` {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢 `debug` 选项将确保捆绑包含源图 如果 `fakeDataPath` 未提供,确保单独提供 `dataFile` 页:1 [主模板](https://npmcn.com/package/%40clinic/clinic-common/#readme-templates)。 。 。 . ### `buildCss(opts = {})` 返回 PostCSS 组合( 保证) #### 使用量 ```js const buildCss = require('@clinic/clinic-common/scripts/build-css') const styleFile = buildCss({ stylePath, (String) debug: this.debug (Boolean) }) ``` {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢 `debug` 选项将确保捆绑包含源图 * * * ## 模板 使用模板 [`stream-template`](https://github.com/almost/stream-template) 将流、承诺和字符串插入共同模板,而无需先缓冲. ### `mainTemplate(opts = {})` 返回流图( 可读流) 使用此模板来构建带有常见的染色体,包括一个头和弹出托盘的工具输出. 这将需要结合共同的UI使用 [样式](https://npmcn.com/package/%40clinic/clinic-common/#readme-styles) 和托盘 [行为](https://npmcn.com/package/%40clinic/clinic-common/#readme-behaviours)。 。 。 . #### 使用量 ```js const mainTemplate = require('@clinic/clinic-common/templates/main') const outputFile = mainTemplate({ htmlClass: '', (String) favicon: 'URI', (String) title: 'Title', (String) styles: styleFile, (Readable Stream) data: dataFile, (Readable Stream) script: scriptFile, (Promise) headerLogoUrl: 'https://github.com/somewhere', (String) headerLogoTitle: 'Logo title', (String) headerLogo: logoFile, (String) headerText: 'Text', (String) toolVersion: '1.2.3', (String) uploadId: 'ID', (String) head: 'extra content', (String) body: 'extra contents' (String) }) ``` 💡 `opts.data` 可以提供将分析的JSON输出放入自己的脚本标记. 未提供分析数据时,应在 `scriptFile` 由用户进行. * * * ## 样式 可导入 CSS 在使用时包含 `mainTemplate` 与《京都议定书》 `buildCss` 脚本可以确保它与特定工具的样式捆绑在一起. 这为信头和托盘增加了一些全局样式. CSS使用BEM来写来避免特异性,并具有以下可被推翻的CSS变量: ```css html { --nc-colour-text: white; --nc-colour-code: #E9F100; --nc-colour-notification-dot: #2165E5; --nc-colour-tray-backdrop: rgba(0, 0, 0, 0.6); --nc-colour-tray: #292d39; --nc-colour-header-background: #292d39; } ``` ### 使用量 ```css @import '@clinic/clinic-common/styles/styles.css'; .your { tool: styles; } ``` ### 标准 CSS 应使用使用 [贝姆](https://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/) 作为更好的封装和较低规格的命名公约. 里面,所有班级都有卖家 `.nc-` 以避免类别名称与第三方或工具特定样式相撞。 对于基于工具的样式,所有样式都应遵循相同的惯例,对工具前缀如下: ``` .ncd- Clinic.js Doctor .ncb- Clinic.js Bubbleprof .ncf- Clinic.js Flame ``` #### 细目 ```css /* Block: Tray component */ .nc-tray { ... /* Element: Tray inner component */ .nc-tray__inner { ... ``` * * * ## 图标 返回一个字典对象,其密钥是图标名称,其值是 svg 文件内容. 用于内置 svg 文件 . [在此查找图标列表](https://npmcn.com/package/%40clinic/master/icons/readme.md) **使用示例 :** ```js const icons = require('@clinic/clinic-common/icons') console.log(icons.activity) output: ` ` ``` 或者您可以单独导入所需的图标 : ```js const cog = require('@clinic/clinic-common/icons/cog') ... `${cog}` ``` Basic 样式可以通过在您主 ass 文件( 如果您使用) 中添加以下行来导入页面 [邮政进口](https://github.com/postcss/postcss-import): ```css @import "@clinic/clinic-common/icons/style.css"; ``` 这将增加以下规则: ```css /* SVG icons */ svg.icon-img { /* Default to same size as adjacent text */ width: 1em; height: 1em; display: block; } ``` **使用图标作为 BG 图像** 也可以使用图标作为背景图像. 在你身边 `style.css` 导入所需的图标,即: ```css @import "@clinic/clinic-common/icons/cog.css"; ``` 这将生成以下 **css 可变** 数字 : ```css html { --cog-icon: url(data:image/svg+xml;utf8,); } ``` 现在你可以像这样使用它: ```css .settings-button{ background-image: var(--cog-icon); width: 24px; height: 24px; ... } ``` * * * ## 图像 可以嵌入 Base64-Encoded 图像. `scripts/build-images.js` 揭露两种方法: ```js path(sourceDir, exportDir) // and file(filePath, exportDir) ``` 支持的文件扩展名为: `png` `jpeg` `jpg` 财务报告和审定财务报表 `gif` 使用实例 : ```js // in your npm script const buildImg = require('@clinic/clinic-common/scripts/build-images') buildImg.file('my/amazing/image.jpg', 'visualizer/assets/images') // in your .js file you first import the image const myImage = require('visualizer/assets/images/image.js') // and then you use it ` ``` * * * ## 构成部分 一套基础组件和帮助者. 所有组件样式都是 `@imported` 内 `style.css` 并且可以进口如下: ```css @import "@clinic/clinic-common/base/style.css"; ``` 每个组件可单独导入: ```js const button = require('@clinic/clinic-common/base/button.js') ``` 或者您可以同时导入多个组件 : ```js const { button, checkbox, contextOverlay } = require('@clinic/clinic-common/base') ``` 每个组件都是返回 HTML 元素的函数 ### 按钮 ```js // button({label, classNames = [], leftIcon = '', rightIcon = '', disabled = false, onClick, title}) myForm.appendChild(button({ label: 'Submit', title: 'Click me!', classNames: ['submitBtn', 'primaryButton'], leftIcon: submitIcon, onClick: () => validateAndSubmit() })) ``` 样式可以通过定义您 CSS 中的 CSS vars 来自定义 ```css --nc-button-bgColor --nc-button-color --nc-button-fontSize --nc-button-bgHover --nc-button-hoverOutline ``` ### 链接 ```js // link({ label, classNames = [], leftIcon = '', rightIcon = '', href, title = '', target = '' }) div.appendChild(link({ label: 'Documentation', title: 'Click me!', href: '/docs', classNames: ['openDocs'], rightIcon: externalLink })) ``` 样式可以通过定义您 CSS 中的 CSS vars 来自定义 ```css --nc-link-bgColor --nc-link-color --nc-link-fontSize --nc-link-bgHover --nc-link-hoverOutline ``` ### 降级 ```js // dropdown({ label, classNames = [], disabled = false, expandAbove = false, content }) div.appendChild(dropdown({ classNames: ['key-v8'], label: checkbox({ leftLabel: 'V8', onChange: e => { this.setCodeAreaVisibility('all-v8', e.target.checked) } }), content: `This is some content. ${greetings}`, expandAbove: true })) ``` 样式可以通过定义您 CSS 中的 CSS vars 来自定义 ```css --nc-checkbox-bgColor --nc-checkbox-hoverColor --nc-checkbox-hoverOutline --nc-checkbox-borderColor --nc-checkbox-checkedIconColor --nc-checkbox-indeterminateIconColor ``` ### 复选框 ```js // checkbox({ leftLabel, rightLabel, classNames = [], checked = false, disabled = false, indeterminate = false, onChange }) checkbox({ classNames: ['key-core'], leftLabel: `Node JS Node`, onChange: e => this.setCodeAreaVisibility('core', e.target.checked) }) ``` 样式可以通过定义您 CSS 中的 CSS vars 来自定义 ```css --nc-dropdown-borderColor --nc-dropdown-color --nc-dropdown-bgColor --nc-dropdown-contentBg --nc-dropdown-contentBorderColor ``` ### 重叠 显示给定的覆盖符 `msg` 位于目标Element 或目标Rect旁边 若为 **目标元素** 财务报告和审定财务报表 **目标矩形** 为: `null||undefined` 然后将覆盖内容集中在页面上. ```js // const options = { // msg, // targetElement, // targetRect, // outerRect, // offset, // pointerCoords, // verticalAlign = 'bottom' // } overlay.show({ msg: this.wrapper, classNames: ['wt-container'], offset: { y: 10, height: 20 }, targetElement: document.querySelector('.my-cool-element'), showArrow: true }) ``` ### 走过去 用于显示UI特性分步向导的类. ```js const wt = new Walkthrough({ steps = [], showBackdrop = false, showControls = true, onProgress }) ``` `WT` 揭露下列方法: ```js `start` `next` `end` `skipTo` ``` `steps` 是一个对象阵列,每个步骤都有以下属性: - `attachTo`: 用于识别所描述元素的 css 选择器 - `msg`: 要显示的消息的 HTML 元素或字符串模板 `onProgress(index)` 当行走组件状态发生变化时,会被触发. ```js // steps definition example const steps = [ { attachTo: '#selection-controls', msg: `
${flame} Hello, and welcome to Flame!
` }, { attachTo: '.frame-dropdown', msg: `

Do you like Flame?

${docs}
` } ] ``` ### 行走按钮 用于激活行道的工具的标准化按钮 ```js // walkthroughButton(steps, onProgress, [label]) const hdtw = walkthroughButton(wtSteps, index => { this.pushHistory() }) // hdtw.WtPlayer -> the embeded walkthrough player // hdtw.button -> the button instance to append to the DOM // label defaults to 'How does this work' ``` ### 帮助者 一套有用的函数. 目前载有: - `toHtml(data)` 数据可以是字符串,函数或HTMLElement. 输出为 HTML 元素 ```js const myHtml = helpers.toHtml(`${greetings}`) // or const myHtml = helpers.toHtml(getGreetings) ``` ## 旋转器 添加 `loading spinner` 请导入您的应用程序 `@clinic/clinic-common/spinner` 在你身边 `main.js` 和样式.cs文件到您的 `style.css` 示例 主要为.js ```js require('@clinic/clinic-common/spinner') ``` 样式.css ```css @import "@clinic/clinic-common/spinner/style.css"; ``` 这将在加载页面时显示加载旋转器 . 如果您需要稍后显示自旋器, 也许当应用程序忙于进行一些计算时, 您可以在程序上将自旋器打开和关闭, 如下例所示 : ```js const spinner = require('@clinic/clinic-common/spinner') ... const redrawSpinner = spinner.attachTo(document.querySelector('#myHtmlContainerNode')) redrawSpinner.show('Melting the North pole down...') // when finished redrawSpinner.hide() ``` 旋转边框默认为白色, 您可以设置 cs s var 来自定义 `--spinner-border-color` 在您的阴道中: ```css html { /* this will set the colour for the page-loading spinner*/ --spinner-border-color: --my-fancy-primary-color; } #myHtmlContainerNode { /* this will set the colour for the in-page spinner*/ /* this is optional and inherits from `html` if not defined*/ --spinner-border-color: --my-fancy-secondary-color; } ``` 将自旋器附加到一个元素中,将产生一个新的实例: `spinner` 可以在开关/关闭后使用。 当显示自旋器时,自旋器所附带的元素会变得模糊并被一个暗箱所覆盖. ![ezgif com-video-to-gif](https://user-images.githubusercontent.com/1298616/49368446-ffdb1f80-f6ee-11e8-9c08-b134bcdcc2e6.gif) ## 许可证 [麻省理工学院](https://npmcn.com/package/%40clinic/clinic-common/LICENSE) ## 常见问题 ### @clinic/clinic-common 是什么？ Clinic\.js套房共用部分 ### 如何安装 @clinic/clinic-common？ 在项目目录运行 npm install @clinic/clinic-common，或使用 pnpm add / yarn add / bun add。 ### @clinic/clinic-common 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/clinic\_\_clinic-common 是否存在。 ### @clinic/clinic-common 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @clinic/clinic-common 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>= 12\.13\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @clinic/clinic-common 可以商用吗？ @clinic/clinic-common 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @clinic/clinic-common 的下载量有多少？ 根据 npm 官方下载统计，@clinic/clinic-common 在 2026/10/10 – 2026/11/08 这 30 天内被下载 182,511 次，日均约 6,084 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @clinic/clinic-common 还在维护吗？ 最新版本 7\.1\.0 发布于 2022/08/24（4 年前）；至今共发布 2 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/11/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。