# @adobe/leonardo-contrast-colors 中文文档 规范地址：https://npmcn.com/package/%40adobe/leonardo-contrast-colors/ 版本：1\.1\.0 npm 元数据更新时间：2026-10-01T01:33:46.874Z 中文译文更新时间：2026-11-05T18:25:00.130Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40adobe/leonardo-contrast-colors 原文对照：https://npmcn.com/package/%40adobe/leonardo-contrast-colors/?lang=original 项目主页：https://github.com/adobe/leonardo#readme 源码仓库：https://github.com/adobe/leonardo ## 关键信息（来自 npm 元数据） - 包体积（解压后）：102 kB，15 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：5 个 - 首次发布：2019-12-09T22:13:08.289Z - 最新版本发布：2026-02-18T01:24:52.253Z - 近 30 天下载量：75188（2026-10-05 至 2026-11-03，npm 官方下载统计） - 已发布版本数：21（近 12 个月 2 个） ## 中文简介 根据想要的对比率生成颜色 ## 安装 ```sh npm install @adobe/leonardo-contrast-colors ``` 也可以使用：`pnpm add @adobe/leonardo-contrast-colors`、`yarn add @adobe/leonardo-contrast-colors`、`bun add @adobe/leonardo-contrast-colors` ## README # `@adobe/leonardo-contrast-colors` [![npm version](https://badge.fury.io/js/%40adobe%2Fleonardo-contrast-colors.svg)](https://www.npmjs.com/package/@adobe/leonardo-contrast-colors) [![Package size](https://badgen.net/packagephobia/publish/@adobe/leonardo-contrast-colors)](https://packagephobia.com/result?p=%40adobe%2Fleonardo-contrast-colors) [![Minified size](https://badgen.net/bundlephobia/min/@adobe/leonardo-contrast-colors)](https://bundlephobia.com/package/@adobe/leonardo-contrast-colors) [![Minified and gzipped size](https://badgen.net/bundlephobia/minzip/@adobe/leonardo-contrast-colors)](https://bundlephobia.com/package/@adobe/leonardo-contrast-colors) [![license](https://img.shields.io/github/license/adobe/leonardo)](https://github.com/adobe/leonardo/blob/master/LICENSE) ![Libraries.io dependency status for latest release, scoped npm package](https://img.shields.io/librariesio/release/npm/@adobe/leonardo-contrast-colors) [![license](https://img.shields.io/github/license/adobe/leonardo)](https://github.com/adobe/leonardo/blob/master/LICENSE) [![Pull requests welcome](https://img.shields.io/badge/PRs-welcome-blueviolet)](https://github.com/adobe/leonardo/blob/master/.github/CONTRIBUTING.md) 此软件包包含所有通过目标对比比生成颜色的功能. ## 使用 Leonardo 对比颜色 ### 安装软件包 : ``` npm i @adobe/leonardo-contrast-colors ``` ### 导入软件包 : #### CJS (节点 12.x) ```js const {Theme, Color, BackgroundColor} = require('@adobe/leonardo-contrast-colors'); ``` #### 无害环境管理(节点13.x) ```js import {Theme, Color, BackgroundColor} from '@adobe/leonardo-contrast-colors'; ``` ### 创建和传递新主题的颜色和背景颜色(见下文其他选项): ```js let gray = new BackgroundColor({ name: 'gray', colorKeys: ['#cacaca'], ratios: [2, 3, 4.5, 8] }); let blue = new Color({ name: 'blue', colorKeys: ['#5CDBFF', '#0000FF'], ratios: [3, 4.5] }); let red = new Color({ name: 'red', colorKeys: ['#FF9A81', '#FF0000'], ratios: [3, 4.5] }); let theme = new Theme({ colors: [gray, blue, red], backgroundColor: gray, lightness: 97 }); // returns theme colors as JSON let colors = theme.contrastColors; ``` ## API 参考 ### `Theme` 用于生成适应性对比色彩的类函数. 参数结构被调整,需要明确称呼. | 参数 | 类型 | 说明 | | --- | --- | --- | | `colors` | 阵列 | 清单 `Color` 选项 单人 `BackgroundColor` 需要分类. | | `lightness` | 数目 | 生成主题背景颜色( 整数) 0- 100 所期望的光度值 | | `contrast` | 数目 | 乘以所有主题颜色的增减对比度( 默认值为 `1`(中文(简体) ) | | `saturation` | 数目 | 0-100 值用于减少所有主题颜色的饱和度( 默认为 `100`(中文(简体) ) | | `output` | 数字 | 理想颜色输出格式 | #### 设置 | 编辑器 | 产出说明 | | --- | --- | | `Theme.lightness` | 设置主题的光度值 | | `Theme.contrast` | 设置主题的对比值 | | `Theme.saturation` | 设置主题的饱和值 | | `Theme.backgroundColor` | 设置主题的背景颜色( 创建新颜色 ) `BackgroundColor` 如果通过字符串) | | `Theme.colors` | 设置主题的颜色( 必须通过) `Color`(中文(简体) ) | | `Theme.output` | 设定主题输出格式 | | [`Theme.addColor`](https://npmcn.com/package/%40adobe/leonardo-contrast-colors/#readme-themeaddcolor--color) | 添加一个 `Color` 标题 | | [`Theme.removeColor`](https://npmcn.com/package/%40adobe/leonardo-contrast-colors/#readme-themeremovecolor--color) | 删除 a `Color` 从主题 | | [`Theme.updateColor`](https://npmcn.com/package/%40adobe/leonardo-contrast-colors/#readme-themeupdatecolor--name-property) | 更新a `Color` 通过主题的设置 | #### `Theme.addColor = color` 添加一个 `Color` 改为现有主题 ```js const red = new Color({...}) theme.addColor = red; ``` #### `Theme.removeColor = color` 删除 a `Color` 从已有主题。 接受带有 `Color`名称和价值,或通过传递 `Color` 班级本身. ```js // Remove via color name theme.removeColor = {name: 'Red'}; // Remove via Color class const red = new Color({...}) theme.removeColor = red; ``` #### `Theme.updateColor = {name, property}` 更新a `Color` 透过主题的设定 接受一个对象,其名称为您想要修改的颜色,然后是属性和您想要修改的新值. ```js const red = new Color({...}) // Change the colors ratios theme.updateColor = {name: 'red', ratios: [3, 4.5, 7]}; // Change the colors colorKeys theme.updateColor = {name: 'red', colorKeys: ['#ff0000']}; // Change the color's name theme.updateColor = {name: 'red', name: 'Crimson'}; ``` #### 支持的输出格式 : 现有产出格式符合 [W3C CSS 色彩模块 第4级](https://www.w3.org/TR/css-color-4/) 所支持选项的示例,如下所示: | 输出选项 | 样本值 | | --- | --- | | `'HEX'` _(默认)_ | `#RRGGBB` | | `'RGB'` | `rgb(255, 255, 255)` | | `'HSL'` | `hsl(360deg, 0%, 100%)` | | `'HSV'` | `hsv(360deg, 0%, 100%)` | | `'HSLuv'` | `hsluv(360, 0, 100)` | | `'LAB'` | `lab(100%, 0, 0)` | | `'LCH'` | `lch(100%, 0, 360deg)` | | `'CAM02'` | `jab(100%, 0, 0)` | | `'CAM02p'` | `jch(100%, 0, 360deg)` | * * * ### `Color` 用于定义主题颜色的类函数 。 参数结构被调整,需要明确称呼. | 参数 | 类型 | 说明 | | --- | --- | --- | | `name` | 字符串 | 一个颜色的用户定义名称,(如"蓝色"). 用于命名输出颜色值 | | `colorKeys` | 字符串组合 | 列出在相间插出的特定颜色,以产生颜色的全光度尺度. | | `colorspace` | 数字 | 这个 [颜色空间](https://npmcn.com/package/%40adobe/leonardo-contrast-colors/#readme-Supported-interpolation-colorspaces) 在其中插入密钥颜色. | | `ratios` | 矩阵或对象 | 列出目标对比比率,或每个值有指定密钥的对象. | | `smooth` | 布尔 | 将贝塞尔平滑应用到插值( 默认虚构) | | `output` | 数字 | 理想颜色输出格式 | #### 设置 | 编辑器 | 产出说明 | | --- | --- | | `Color.colorKeys` | 设置颜色密钥 | | `Color.colorspace` | 设置插值颜色空间 | | `Color.ratios` | 设定比率 | | `Color.name` | 设置名称 | | `Color.smooth` | 设置平滑选项 | | `Color.output` | 设置输出格式 | #### 支持的插值颜色空间 : 以下是列奥纳多语的可选插图: - [妇 人](https://en.wikipedia.org/wiki/HCL_color_space) - [劳工局](https://en.wikipedia.org/wiki/CIELAB_color_space) - [CAM02卫星](https://en.wikipedia.org/wiki/CIECAM02) - [高级](https://en.wikipedia.org/wiki/HSL_and_HSV) - [苏维埃](https://en.wikipedia.org/wiki/HSLuv) - [高级保险](https://en.wikipedia.org/wiki/HSL_and_HSV) - [RGB 语言](https://en.wikipedia.org/wiki/RGB_color_space) #### 作为数组的比例 当通过一个平坦的目标比例阵列时,您主题中的输出颜色将通过将颜色名称(如"蓝色")与数字递增相接来生成. 带有颜色 **正对比比** 与基数(即:2:1)相加后命名为100. 譬如说, `gray100`, (中文(简体) ), `gray200`。 。 。 . 带有颜色 **负对比比** 基数( ie-2:1) 将以低于100和 _基于已声明的负值数_。例如,如果有3个负值 `[-1.4, -1.3, -1.2, 1, 2, 3]`,这些值的名称将递增100/4(长度加一,以避免 `0` 值),例如 `gray25`, (中文(简体) ), `gray50`,以及 `gray75`。 。 。 . 例如: ```js new Color({ name: 'blue', colorKeys: ['#5CDBFF', '#0000FF'], colorSpace: 'LCH', ratios: [3, 4.5] }); // Returns: [ { name: 'blue', values: [ {name: 'blue100', contrast: 3, value: '#8d63ff'}, {name: 'blue200', contrast: 4.5, value: '#623aff'} ] } ]; ``` #### 作为对象的比例 当定义比例为带有密钥值对的对象时,您定义了您列奥纳多主题中的输出名称 . ```js new Color({ name: 'blue', colorKeys: ['#5CDBFF', '#0000FF'], colorSpace: 'LCH', ratios: { 'blue--largeText': 3, 'blue--normalText': 4.5 } }); // Returns: [ { name: 'blue', values: [ {name: 'blue--largeText', contrast: 3, value: '#8d63ff'}, {name: 'blue--normalText', contrast: 4.5, value: '#623aff'} ] } ]; ``` * * * ## 输出示例 输出有两种类型: `Theme` 类 : | 盖特 | 产出说明 | | --- | --- | | `Theme.contrastColors` | 返回带有密钥值对的颜色对象阵列 | | `Theme.contrastColorPairs` | 以密钥值对返回对象 | | `Theme.contrastColorValues` | 返回颜色值的平整数组 | ### `Theme.contrastColors` 每个颜色都是以用户定义的值命名的对象(例如: `name: 'gray'`)“值”数组由颜色的所有生成的颜色值组成,具有属性 `name`, (中文(简体) ), `contrast`,以及 `value`数字 : ```js [ {background: '#e0e0e0'}, { name: 'gray', values: [ {name: 'gray100', contrast: 1, value: '#e0e0e0'}, {name: 'gray200', contrast: 2, value: '#a0a0a0'}, {name: 'gray300', contrast: 3, value: '#808080'}, {name: 'gray400', contrast: 4.5, value: '#646464'} ] }, { name: 'blue', values: [ {name: 'blue100', contrast: 2, value: '#b18cff'}, {name: 'blue200', contrast: 3, value: '#8d63ff'}, {name: 'blue300', contrast: 4.5, value: '#623aff'}, {name: 'blue400', contrast: 8, value: '#1c0ad1'} ] } ]; ``` ### `Theme.contrastColorPairs` 作为键值对对象的简化格式. 财产等于 [生成](https://npmcn.com/package/%40adobe/leonardo-contrast-colors/#readme-Ratios-as-an-array) 或者说 [用户定义名称](https://npmcn.com/package/%40adobe/leonardo-contrast-colors/#readme-Ratios-as-an-object) 对于每个生成的值. ```js { "gray100": "#e0e0e0"; "gray200": "#a0a0a0"; "gray300": "#808080"; "gray400": "#646464"; "blue100": "#b18cff"; "blue200": "#8d63ff"; "blue300": "#623aff"; "blue400": "#1c0ad1"; } ``` ### `Theme.contrastColorValues` 在平面阵列中返回所有颜色值. ```js ['#e0e0e0', '#a0a0a0', '#808080', '#646464', '#b18cff', '#8d63ff', '#623aff', '#1c0ad1']; ``` * * * ## 带有 CSS 变量的 Leonardo 以下是几个实例,说明您如何利用莱昂纳多为您的应用程序动态创建或修改 CSS 变量 . ### 香草联署材料 ```js let varPrefix = '--'; // Iterate each color object for (let i = 0; i < myTheme.length; i++) { // Iterate each value object within each color object for (let j = 0; j < myTheme[i].values.length; j++) { // output "name" of color and prefix let key = myTheme[i].values[j].name; let prop = varPrefix.concat(key); // output value of color let value = myTheme[i].values[j].value; // create CSS property with name and value document.documentElement.style.setProperty(prop, value); } } ``` ### 反应 创建新的主题组件 `Theme.js` 使用参数 : ```js import * as Leo from '@adobe/leonardo-contrast-colors'; const Theme = () => { let gray = new Leo.BackgroundColor({ name: 'gray', colorKeys: ['#cacaca'], ratios: [2, 3, 4.5, 8] }); let blue = new Leo.Color({ name: 'blue', colorKeys: ['#5CDBFF', '#0000FF'], ratios: [3, 4.5] }); let red = new Leo.Color({ name: 'red', colorKeys: ['#FF9A81', '#FF0000'], ratios: [3, 4.5] }); const adaptiveTheme = new Leo.Theme({ colors: [gray, blue, red], backgroundColor: gray, lightness: 97, contrast: 1 }); return adaptiveTheme; }; export default Theme; ``` 导入您的 应用程序顶层的主题组件,并将主题作为应用程序属性传递: ```js // index.js import Theme from './components/Theme'; ReactDOM.render( , document.getElementById('root') ); ``` 在您的 App.js 文件中,导入 `useTheme` 从 `css-vars-hook` ,并在您的 App 函数内提供以下内容,以便将Leonardo 的输出格式化为所需的结构 `css-vars-hook`。 。 。 . ```js // App.js import {useTheme} from 'css-vars-hook'; function App(props) { const [lightness, setLightness] = useState(100); const [contrast, setContrast] = useState(1); const _createThemeObject = () => { let themeObj = {}; props.adaptiveTheme.contrastColors.forEach((color) => { if (color.name) { let values = color.values; values.forEach((instance) => { let name = instance.name; let val = instance.value; themeObj[name] = val; }); } else { // must be the background let name = 'background'; let val = color.background; themeObj[name] = val; } }); return themeObj; }; const theme = useState(_createThemeObject()); const {setRef, setVariable} = useTheme(theme); return
; } ``` 要适应应用程序,请在返回功能前包含更新主题的功能: ```js function _updateColorVariables() { let themeInstance = _createThemeObject(); for (const [key, value] of Object.entries(themeInstance)) { setVariable(key, value); } } // call function to set initial values _updateColorVariables(); ``` 最后,当用户与滑动器组件互动时,引用此函数并设定主题参数(对相容性进行相同): ```js { setLightness(e.target.value) props.adaptiveTheme.lightness = e.target.value _updateColorVariables() }} /> { setContrast(e.target.value) props.adaptiveTheme.contrast = e.target.value _updateColorVariables() }} /> ``` ### React 中的暗模式支持 在您的 App.js 文件中包含以下内容以监听黑暗模式 。 这将传递一个不同的光度值(你所选择的)给莱昂纳多. 建议根据模式限制光度范围,以避免无法进入的范围,并提供更好的总体经验 ```js const mq = window.matchMedia('(prefers-color-scheme: dark)'); // Update lightness and slider min/max to be conditional: const [lightness, setLightness] = useState(mq.matches ? 8 : 100); const [sliderMin, setSliderMin] = useState(mq.matches ? 0 : 80); const [sliderMax, setSliderMax] = useState(mq.matches ? 30 : 100); // Listener to update when user device mode changes: mq.addEventListener('change', function (evt) { props.adaptiveTheme.lightness = mq.matches ? 11 : 100; setLightness(mq.matches ? 11 : 100); setSliderMin(mq.matches ? 0 : 80); setSliderMax(mq.matches ? 30 : 100); }); ``` * * * ## 为什么不能提供所有对比比率? 您可能注意到该工具需要输入( 目标比) , 但通常输出的对比比略高 。 这与RGB色彩空间中可用的颜色,以及与计算这些比率相关的数学有关. 例如,让我们看看蓝色和白色. 蓝色: rgb( 0, 0, 255) 白色: rgb(255、255、255) 对比率 : **8.59 联合国**: 1 个 如果我们改变 RGB 频道中任何一种颜色的值, 比例会改变 : 蓝色: rgb (0), **1个**页:1 白色: rgb(255、255、255) 对比率 : **8.57 (中文(简体) )**: 1 个 如果8.58是输入以蓝色为起始颜色作为目标比,输出将不准确. 这被各种色相空间插值所夸大. 由于WCAG要求的定义是: _最低对比要求_,它应该很好产生 颜色一点点 _更多_ 可访问性超过最小值. * * * ## Chroma.js (英语) 这个项目目前正在使用 [Chroma.js (英语)](https://gka.github.io/chroma.js/) 有自定义扩展支持[CIE CAM02 互联网档案馆的存檔,存档日期2013-10-02](https://gramaz.io/d3-cam02/). 在Leonardo中添加了额外的功能来增强染色体鳞片来通过光度正确排列颜色并修正以HSLuv为基础的鳞片的光度. ## 捐款 欢迎捐款! 读取 [贡献指南](https://npmcn.com/package/.github/CONTRIBUTING.md) 更多信息. ## 发展 您可以使用 : ```sh pnpm dev ``` 或只用一次测试 : ```sh pnpm test ``` ## 许可证发放 这个项目根据Apache V2许可证获得许可. 见 [自由主义](https://npmcn.com/package/%40adobe/leonardo-contrast-colors/LICENSE) 更多信息. ## 常见问题 ### @adobe/leonardo-contrast-colors 是什么？ 根据想要的对比率生成颜色 ### 如何安装 @adobe/leonardo-contrast-colors？ 在项目目录运行 npm install @adobe/leonardo-contrast-colors，或使用 pnpm add / yarn add / bun add。 ### @adobe/leonardo-contrast-colors 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @adobe/leonardo-contrast-colors 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @adobe/leonardo-contrast-colors 可以商用吗？ @adobe/leonardo-contrast-colors 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @adobe/leonardo-contrast-colors 的下载量有多少？ 根据 npm 官方下载统计，@adobe/leonardo-contrast-colors 在 2026/10/05 – 2026/11/03 这 30 天内被下载 75,188 次，日均约 2,506 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @adobe/leonardo-contrast-colors 还在维护吗？ 最新版本 1\.1\.0 发布于 2026/02/18（8 个月前）；至今共发布 21 个版本，其中过去 12 个月发布了 2 个；首次发布于 2019/12/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。