扩展开发入门

在节将介绍如何编写良好的 SketchUp 扩展，包括：

安全地命名扩展，以将其与其他扩展隔离。
向 SketchUp 扩展管理器注册您的“扩展类”扩展。
将扩展添加到 SketchUp 菜单系统。
在模型中绘制基本几何体（立方体）！

1. 注册扩展的通用模板

ruby

# 首先向 SketchUp 请求一些已经自带了的扩展注册功能
require 'sketchup.rb'
require 'extensions.rb'

# 在 SketchUp Ruby 中，所有代码都得加载到一个模块 (module) 中。如果不这么做，你很有可能会破坏别人的代码，别人也会破坏你的代码
# 请使用以下二级命名的模式（你的名字和扩展的名字）

module YourName
    module ExtensionName
        # 使用 file_loaded? 防止扩展被 SketchUp 多次加载
        # __FILE__ 常量是一个 Ruby 常量，它返回一个带有当前文件路径的字符串
        unless file_loaded?(__FILE__)
        # 请注意，加载的扩展文件 (hello_world/main) 必须位于与Root文件同名的文件夹中
        # ruby 文件的扩展名可以省略。实际加载的文件路径就是 hello_world/main.rb
        ex = SketchupExtension.new('Hello Cube', 'hello_cube/main')
        # 向扩展添加一些信息，方便管理
        ex.description = 'SketchUp Ruby API example creating a cube.'
        ex.version = '1.0.0'
        ex.copyright = 'Trimble Navigations © 2016'
        ex.creator = 'SketchUp'
        # 告诉 SketchUp 注册此扩展
        # 须将第二个参数设置为 true，否则用户在安装后还得手动启用扩展
        Sketchup.register_extension(ex, true)
        # 声明文件以被加载
        # 重复调用时在 unless file_loaded?(__FILE__) 处便会直接终止
        file_loaded(__FILE__)
        end

    end # module HelloCube
end # module Examples

在您的 SketchUp 扩展文件夹中创建一个空白文本文件，将以上代码复制进去并保存，最后将其命名为 hello_cube.rb。

这个文件被称为 “Root” 文件，用于向 SketchUp 注册你的扩展。

注意

不要使用 Root 文件执行任何其他代码任务，以避免与其他扩展发生冲突。

2. hello_cube\main.rb 的源码

这是扩展 Root 文件所加载的文件，包含了扩展的所有功能性代码。请阅读注释，以了解每行代码的作用。

ruby

# 与 Root 文件中的命名结构相同，以便将所有代码干净地包装在自己的 namepsace
module YourName
    module ExtensionName

        # 定义一个方法，用于在模型中的组内创建一个简单的立方体
        def self.create_cube
            # 引用当前的活动模型
            # SketchUp API 仅允许您处理活动模型
            # 在 Windows 下，一次只打开一个模型，但在 OSX 下可能会打开多个模型
            # 如果在 OSX 下没有打开任何模型，则 model 的值将为 nil
            model = Sketchup.active_model
            # 为了简单起见，此示例中默认环境为 Windows，省略了以下这行的真值判断
            # return if !model

            # 请注意，必须使用 start_operation 和 commit_operation 封装该函数所有对模型的修改
            # 否则，用户将可能需要手动点击几百次才能撤消该函数所做的修改
            # 确保模型更改可在单个步骤中撤消，是进入官方扩展仓库时质量检查的要求之一
            # 第一个参数是一个字符串，将附加到 Edit > Undo 菜单中，请确保是用户可以理解的名称
            model.start_operation('Create Cube', true)

            # 通过 API 创建群组（group），然后再将内容添加到其中
            group = model.active_entities.add_group
            entities = group.entities

            # SketchUp 中的内部单位是英寸，数据始终以英寸为单位存储
            # 直接输入 1 表示的是 0.0254 米（1 英寸）
            # 为了更容易处理长度，Numeric 类扩展了一些单位换算的方法，例如输入 1.m 表示 “1米”
            points = [
                Geom::Point3d.new(0, 0, 0),
                Geom::Point3d.new(1.m, 0, 0),
                Geom::Point3d.new(1.m, 1.m, 0),
                Geom::Point3d.new(0, 1.m, 0)
            ]

            # 请注意，生成面的方向（法线）一般是由点的顺序决定。但创建的水平面默认法线始终朝下
            face = entities.add_face(points)

            # 调用 SketchUp 的推拉功能从面生成体块
            # 请注意，必须使用负数才能使其沿 Z 轴的正方向向上挤出，这是因为之前创建的是水平面
            face.pushpull(-1.m)

            # 函数结束时提交所有操作到撤销记录
            model.commit_operation

            # 请注意，在生产环境中还需要捕获并处理可能发生的错误。简单起见，这里不这样做
        end

        # 创建扩展菜单
        # 再次使用负载防护来防止意外重复创建相同菜单
        unless file_loaded?(__FILE__)
            # 获取对要添加的顶级菜单的引用
            # 请注意，使用的 'Plugins' 是旧名称，以保持向后兼容。
            menu = UI.menu('Plugins')

            # 将菜单项直接添加到菜单的根目录中
            # 点击菜单项时将调用 create_cube 方法
            menu.add_item('Create Cube Example') {
                self.create_cube
            }

            file_loaded(__FILE__)
        end

    end
end

下一篇：常见问题

扩展开发入门 ​

1. 注册扩展的通用模板 ​

2. hello_cube\main.rb 的源码 ​

扩展开发入门

1. 注册扩展的通用模板

2. hello_cube\main.rb 的源码