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

address4cj API速查手册核心类、函数接口与类型扩展完整参考【免费下载链接】address4cj处理地址表示、验证和格式化。项目地址: https://gitcode.com/Cangjie-SIG/address4cjaddress4cj是一款面向仓颉语言的地址处理库用于全球地址的表示、验证与格式化内置约 200 个国家的地址格式规则、邮编正则与行政区划数据并支持 HTML 输出和 HTTP JSON 分发。本文作为address4cj API 速查手册帮你快速查清 6 个核心类、20 函数接口、类型别名与 String 类型扩展的用法一张表看懂随查随用 ⚡ 30秒了解 address4cj模块与源码结构上手 API 前先知道每个接口定义在哪个文件遇到问题能直接定位源码模块文件职责src/address.cjAddress、Format、RegionMap核心类与国家代码函数src/locale.cjLocale类与语言标识解析BCP 47 标准化src/formatter.cjFormatter类、newFormatter与 String 类型扩展src/const.cj字段/类型别名、常量与类型序列化函数src/format.cj约 200 个国家的地址格式库布局模板 邮编正则src/http.cjHTTP 地址格式 JSON 分发服务完整的接口文档在 doc/feature_api.md本文内容与其保持同步。 核心类速查6个类各管一件事1. Address —— 地址数据模型你最常用的类表示一个国际地址的 8 个字段全部可选、默认为空字符串实现JsonSerializable可直接序列化为 JSONJSON 键为line1…country。成员说明line1 / line2 / line3街道地址与补充行sublocality街区、社区、区locality城市、村庄或邮政镇region省/州/地区ISO 编码优先postalCode邮政编码countryCode两位国家代码CLDR 标准func isEmpty()国家代码为空即视为空地址 用法速记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 片段可直接嵌进网页。四个关键属性属性默认值作用noCountryfalse是否隐藏国家名wrapperElementp外层 HTML 标签wrapperClassaddress外层标签的 classcountryMapper内置英文名可替换为自定义多语言国家名映射方法只有两个format(addr)返回 HTML 字符串空地址返回空串getLocale()取当前绑定的 Locale。所有输出字段都会自动做 HTML 转义防止 XSS ✅4. Locale —— 语言区域标识标准化的关键对应 BCP 47 标识三个字段language、script如Latn、territory。newLocale(sr_rs_latn)会自动标准化为sr-Latn-RStoString()输出language-script-territory格式isEmpty()判断全空。5. RegionMap —— 区域代码到名称的有序映射例如日本13 → Tokyo。方法get(key)返回(名称, 是否存在)元组、hasKey(key)、getKeys()、len()。支持 JSON 序列化/反序列化可从服务端直接还原。6. FormatDistributor / FormatHandler —— HTTP 分发服务FormatDistributor固定把/address-formats路径路由到FormatHandler其余返回 404FormatHandler返回全部国家的地址格式 JSONlocale 取值优先级?localefr查询串 Accept-Language请求头 默认英语响应头自动带上Content-Type: application/json与Content-Language实现细节见 src/http.cj。 函数接口速查表按场景查找场景函数一句话说明建格式化器newFormatter(locale)创建带默认 HTML 配置的国家映射 Formatter建区域映射newRegionMap(pairs)键值对数组须偶数个构建 RegionMap建语言标识newLocale(id)解析并标准化语言标识字符串校验国家代码checkCountryCode(code)空值视为合法返回 Bool取全部国家代码getCountryCodes()按字母序排序的代码列表取国家名称表getCountryNames()代码 → 名称CLDR v47取全部格式getFormats()代码 → Format含通用格式ZZ取单国格式getFormat(code)无匹配时兜底返回ZZ格式类型 → 字符串stringRegionType等 4 个无效值返回空串序列化/反序列化serializeXxxType/deserializeXxxType共 8 个配合 JSON 使用 高频组合checkCountryCodegetFormatcheckRequiredcheckPostalCode就是完整的地址表单校验四件套。 类型别名与常量速查定义于 src/const.cj布局模板里的占位符就是这些常量类型底层类型常量/枚举值FieldString123行、S子区域、L城市、R大区、P邮编SublocalityTypeUInt8suburb(0) / district(1) / neighborhood(2) / village_township(3) / townland(4)LocalityTypeUInt8city(0) / district(1) / post_town(2) / suburb(3) / town_city(4)RegionTypeUInt8province、state、prefecture 等 13 种大区类型PostalCodeTypeUInt8postal(0) / eir(1) / pin(2) / zip(3)布局模板规则%1%2%3对应行 1~3%S%L%R%P对应子区域/城市/大区/邮编换行自动转br空字段连同前导分隔符一起省略。 类型扩展接口String.html_escapeStringsrc/formatter.cj 为String扩展了静态方法html_escapeString转义 五种字符把用户输入安全地嵌入 HTML。Formatter.format内部已自动调用但如果你手写 HTML 拼接记得主动用它。 三大典型场景接口怎么组合表单地址验证getFormat(countryCode)拿规则 →checkRequired查必填 →checkPostalCode查邮编 →checkRegion查区域页面展示格式化newLocale(zh)→newFormatter(locale)→format(addr)输出带 class 的 HTML可配noCountry/wrapperElement定制样式服务端多语言分发注册FormatDistributor客户端访问/address-formats?localeja即得该语言下的全部国家布局与区域 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找多语言支持 →LocalenewLocale找 HTTP 服务 →FormatDistributorFormatHandler完整签名与注释见 doc/feature_api.md国家格式库见 src/format.cj把这份 address4cj API 速查手册收藏好写地址功能时查表即可10 分钟跑通表示、验证与格式化三大场景 【免费下载链接】address4cj处理地址表示、验证和格式化。项目地址: https://gitcode.com/Cangjie-SIG/address4cj创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考