typograf开发指南：如何为开源排版工具贡献代码与规则

【免费下载链接】typograf📖 Типографика на JavaScript项目地址: https://gitcode.com/gh_mirrors/ty/typograf

typograf是一款强大的JavaScript排版工具，能够自动优化文本格式，提升内容可读性。本指南将详细介绍如何为这个开源项目贡献代码与规则，帮助你快速参与到项目开发中。

一、环境准备与项目克隆

要开始为typograf贡献代码，首先需要准备开发环境并克隆项目仓库。打开终端，执行以下命令：

git clone https://gitcode.com/gh_mirrors/ty/typograf cd typograf npm install

安装完成后，你可以使用以下命令进行项目构建和测试：

• 重新构建项目：npm run rebuild
• 运行测试：npm test
• 准备发布版本：npm run dist
• 性能基准测试：npm run benchmark

二、贡献代码的基本流程

2.1 了解项目结构

typograf的主要代码位于src/目录下，其中核心规则定义在src/rules/文件夹中。不同语言和功能的规则被组织在相应的子目录中，例如：

• 通用规则：src/rules/common/
• 俄语规则：src/rules/ru/
• 英语规则：src/rules/en-US/

2.2 创建新规则的步骤

1. 创建规则文件：在对应语言或功能的目录下新建.ts文件，例如src/rules/common/nbsp/newRule.ts

2. 定义规则结构：一个典型的规则包含名称、处理函数和设置，示例如下：

import type { TypografRule } from '../../../main'; export const myNewRule: TypografRule<{ param: number; }> = { name: 'common/nbsp/myNewRule', handler(text, settings, context) { // 规则处理逻辑 return text.replace(/pattern/g, 'replacement'); }, settings: { param: 2, // 默认参数 }, };

3. 添加测试用例：为新规则创建测试文件newRule.test.ts，确保规则按预期工作

4. 更新索引文件：在所在目录的index.ts中导出新规则

三、规则开发详解

3.1 规则处理函数

规则的核心是handler函数，它接收三个参数：

• text：需要处理的文本
• settings：规则的配置参数
• context：包含工具方法和数据的上下文对象

例如，src/rules/common/nbsp/afterShortWord.ts中的处理函数：

handler(text, settings, context) { const { lengthShortWord } = settings; const quote = getData('common/quote'); const char = context.getData('char'); const before = ' \u00A0(' + privateLabel + quote; const subStr = '(^|[' + before + '])([' + char + ']{1,' + lengthShortWord + '}) '; const newSubStr = '$1$2\u00A0'; const re = new RegExp(subStr, 'gim'); return text.replace(re, newSubStr).replace(re, newSubStr); }

3.2 使用数据和工具

项目提供了丰富的数据和工具函数：

• 数据获取：getData('common/quote')
• 正则工具：src/helpers/regExp.ts
• 字符串工具：src/helpers/string.ts

四、提交贡献的最佳实践

4.1 代码规范

• 遵循项目的ESLint配置：eslint.config.mjs
• 使用TypeScript类型定义确保类型安全
• 保持代码风格与现有代码一致

4.2 测试要求

• 为每个新规则编写测试用例
• 确保所有测试通过：npm test
• 考虑边界情况和不同语言环境

4.3 文档更新

• 如果添加新功能，更新相应的文档：docs/
• 记录规则的用途和参数说明
• 更新变更日志：CHANGELOG.md

五、常见问题与解决方案

5.1 规则冲突

当新规则与现有规则冲突时：

• 调整规则执行顺序
• 使用更精确的正则表达式
• 在groups.json中配置规则分组

5.2 性能优化

如果规则影响性能：

• 优化正则表达式
• 使用npm run benchmark测试性能
• 考虑使用缓存或减少不必要的替换

六、参与社区

• 阅读开发文档：docs/development.md
• 查看现有规则：src/rules/
• 提交issue或PR参与讨论

通过遵循以上指南，你可以顺利为typograf贡献代码和规则，帮助这个开源排版工具变得更加强大和完善。无论是修复bug、添加新功能还是优化现有规则，每一份贡献都将受到社区的欢迎！

【免费下载链接】typograf📖 Типографика на JavaScript项目地址: https://gitcode.com/gh_mirrors/ty/typograf