企业官网建设流程全解析

address4cj API速查手册：核心类、函数接口与类型扩展完整参考

【免费下载链接】address4cj处理地址表示、验证和格式化。项目地址: https://gitcode.com/Cangjie-SIG/address4cj

address4cj是一款面向仓颉语言的地址处理库，用于全球地址的表示、验证与格式化：内置约 200 个国家的地址格式规则、邮编正则与行政区划数据，并支持 HTML 输出和 HTTP JSON 分发。本文作为address4cj API 速查手册，帮你快速查清 6 个核心类、20+ 函数接口、类型别名与 String 类型扩展的用法，一张表看懂，随查随用 ⚡

📦 30秒了解 address4cj：模块与源码结构

上手 API 前，先知道每个接口定义在哪个文件，遇到问题能直接定位源码：

完整的接口文档在 doc/feature_api.md，本文内容与其保持同步。

🏛 核心类速查：6个类各管一件事

1. Address —— 地址数据模型（你最常用的类）

表示一个国际地址的 8 个字段，全部可选、默认为空字符串，实现JsonSerializable可直接序列化为 JSON（JSON 键为line1…country）。

👉 用法速记：Address(line1: "1098 Alta Ave", locality: "Mountain View", countryCode: "US")。

2. Format —— 单国地址格式规则（验证的核心）

每个国家一条Format，包含布局模板layout、必填字段required、邮编正则postalCodePattern、区域映射regions等。验证类方法一览：

• isRequired(field)：判断字段是否必填
• checkRequired(field, value)：必填字段是否填写合法
• checkRegion(region)：区域代码是否有效（空值视为合法）
• checkPostalCode(code)：邮编是否匹配正则（空值视为合法）
• postalCodeValidationPattern()：返回完整正则，如中国的^\d{6}$
• selectLayout(locale)/selectRegions(locale)：按语言自动选本地化布局/区域名

👉 通过 src/address.cj 可直接查看实现细节。

3. Formatter —— HTML 地址格式化器（展示的核心）

把Address渲染成带class的 HTML 片段，可直接嵌进网页。四个关键属性：

方法只有两个：format(addr)返回 HTML 字符串（空地址返回空串）；getLocale()取当前绑定的 Locale。所有输出字段都会自动做 HTML 转义，防止 XSS ✅

4. Locale —— 语言区域标识（标准化的关键）

对应 BCP 47 标识，三个字段：language、script（如Latn）、territory。newLocale("sr_rs_latn")会自动标准化为sr-Latn-RS；toString()输出language-script-territory格式，isEmpty()判断全空。

5. RegionMap —— 区域代码到名称的有序映射

例如日本"13" → "Tokyo"。方法：get(key)返回(名称, 是否存在)元组、hasKey(key)、getKeys()、len()。支持 JSON 序列化/反序列化，可从服务端直接还原。

6. FormatDistributor / FormatHandler —— HTTP 分发服务

• FormatDistributor：固定把/address-formats路径路由到FormatHandler，其余返回 404
• FormatHandler：返回全部国家的地址格式 JSON，locale 取值优先级：?locale=fr查询串 >Accept-Language请求头 > 默认英语

响应头自动带上Content-Type: application/json与Content-Language，实现细节见 src/http.cj。

🚀 函数接口速查表：按场景查找

💡 高频组合：checkCountryCode+getFormat+checkRequired+checkPostalCode就是完整的"地址表单校验四件套"。

🏷 类型别名与常量速查

定义于 src/const.cj，布局模板里的占位符就是这些常量：

布局模板规则：%1%2%3对应行 1~3，%S%L%R%P对应子区域/城市/大区/邮编，换行自动转<br>，空字段连同前导分隔符一起省略。

🔧 类型扩展接口：String.html_escapeString

src/formatter.cj 为String扩展了静态方法html_escapeString，转义& ' < > "五种字符，把用户输入安全地嵌入 HTML。Formatter.format内部已自动调用，但如果你手写 HTML 拼接，记得主动用它。

🎯 三大典型场景：接口怎么组合？

1. 表单地址验证：getFormat(countryCode)拿规则 →checkRequired查必填 →checkPostalCode查邮编 →checkRegion查区域
2. 页面展示格式化：newLocale("zh")→newFormatter(locale)→format(addr)输出带 class 的 HTML，可配noCountry/wrapperElement定制样式
3. 服务端多语言分发：注册FormatDistributor，客户端访问/address-formats?locale=ja即得该语言下的全部国家布局与区域 JSON，响应体积比原始数据小约 20%

更多完整示例可参考测试用例：src/test/address_test.cj、src/test/formatter_test.cj、src/test/http_test.cj、src/test/locale_test.cj。

✅ 速查小结

• 找数据模型 →Address；找验证规则 →Format；找页面输出 →Formatter
• 找国家/区域数据 →getCountryCodes/getFormats/RegionMap
• 找多语言支持 →Locale+newLocale；找 HTTP 服务 →FormatDistributor+FormatHandler
• 完整签名与注释见 doc/feature_api.md，国家格式库见 src/format.cj

把这份 address4cj API 速查手册收藏好，写地址功能时查表即可，10 分钟跑通表示、验证与格式化三大场景 📚

【免费下载链接】address4cj处理地址表示、验证和格式化。项目地址: https://gitcode.com/Cangjie-SIG/address4cj